The Yoix^® Scripting Language

Some Swing components, like JTextArea and JTextField, provide automatic drag and drop handling that can be enabled using their dragenabled field, but many others require that you do all or part of the work. Yoix, like Java, gives you several ways to tackle the job. You can use TransferHandler, which we describe here, or you can implement drag and drop event handlers, like dragGestureRecognized, dragEnter, and drop. TransferHandler Both approaches work, but we often prefer using the drag and drop event handlers, so we recommend you read about DragGestureEvent, DragSourceEvent, and DropTargetEvent, before you decide how to add drag and drop to your scripts.

There are lots of functions you can implement in a TransferHandler, but often all you really have to do is set the action and property fields, so pay close attention to them. Yoix programs normally interact with a TransferHandler using the following fields:

action	An int that describes the kind of transfers that are allowed by this transferhandler when the getSourceActions function is NULL. The value should be COPY (the default) , MOVE, COPY_OR_MOVE, LINK, or NONE, which are all defined in yoix.awt and yoix.swing. Data is not exported when the action supported by the transferhandler is not compatible with the action requested by exportAsDrag or exportToClipboard. A value of NONE when getSourceActions is also NULL means the transferhandler will not export data.
canImport(Object comp, Array mimetypes)	A Function that is called, if it is not NULL, when the transferhandler needs to know if Swing component comp can import data that is described by the strings in the mimetypes array. canImport should return 1 if the import is allowed 0 if it is not. The Yoix interpreter makes the decision when canImport is NULL, and most of the time that decision is perfectly acceptable, so canImport is usually not needed.
createTransferable(Object comp)	A Function that is called, if it is not NULL, whenever the transferhandler wants Swing component comp to provide transfer data. Any Object that createTransferable returns, other than NULL, can be transferred. property is used to pick data out of the Swing component when createTransferable is NULL. For example, set property to selected and any Swing component that uses the transferhandler and has a selected field will automatically get its transfer data by reading that field.
exportAsDrag(Object comp, MouseEvent event, int action)	A Builtin that starts a drag and drop operation in Swing component comp that is triggered by event and uses action, which should be COPY, MOVE, or LINK, to transfer data. No data will be exported if the requested action is not compatible with the action supported by the transferhandler. exportAsDrag should be called from comp's mouseDragged or mousePressed event handlers because the drag operation will not start if event was not generated by a real mouse event.
exportDone(Object comp, Object data, int action)	A Function that is called, if it is not NULL, after the data obtained from Swing component comp has been exported. The action argument will be one of COPY MOVE, LINK, or NONE, which are all defined in yoix.awt and yoix.swing. If action is NONE or data is NULL then exportDone should assume the transfer was not successful. property is used when exportDone is NULL and action is MOVE, and in that case the Yoix interpreter will try to store NULL in the field in Swing component comp that is selected by property.
exportToClipboard(Object comp, Clipboard clipboard, int action)	A Builtin that exports data from Swing component comp to clipboard using action, which should be COPY, MOVE, or LINK, to transfer data. No data will be exported if the requested action is not compatible with the action supported by the transferhandler.
getSourceActions(Object comp)	A Function that is called, if it is not NULL, whenever the transferhandler is asked to supply the supported actions. The value returned by getSourceActions should be COPY, MOVE, COPY_OR_MOVE, LINK, or NONE, which are all defined in yoix.awt and yoix.swing. Data is not exported when getSourceActions returns a value that is not compatible with the action requested by exportAsDrag or exportToClipboard. getSourceActions is rarely needed because the value stored in action is automatically used when getSourceActions is NULL.
getVisualRepresentation(Object data)	A Function that is called, if it is not NULL, whenever the transferhandler is asked to provide a visual Image that can represent data in a clipboard or as an image that is dragged along with the cursor in a drag and drop operation. We currently do not recommend using this function. We have never seen it called, so it has not been tested, and we are not even convinced current versions of Java really use it.
importData(Object comp, Object data)	A Function that is called, if it is not NULL, to import data into Swing component comp. importData should return 1 if the import was successful 0 if it was not. property is used when importData is NULL, and in that case the Yoix interpreter will try to store data in the field in Swing component comp that is selected by property.
property	A String that identifies a field in a Swing component that will be used as the default source or sink of the data that is transferred by this transferhandler. property is sometimes an easy way to implement the functionality that the createTransferable, exportDone, and importData functions are expected to provide.

Several permanent fields have not been documented and should not be used in Yoix applications.

Swing components define a field named transferhandler that is used to change the transferhandler the component is using. The ones that provide automatic drag handling, which is only activated when TRUE is stored in their dragenabled field, start out with a transferhandler field that is not NULL. Storing NULL in transferhandler disables Swing's automatic drag handling, which is something that has to be done before drag and drop event handlers, like dragGestureRecognized will start working.

Example:	The program, import yoix.*.*; JFrame f = { String title = "LabelDnD"; double border = 6; Dimension size = NULL; GridLayout layoutmanager = { int rows = 2; }; Array layout = { new JPanel { String border = "JTextField: drag and drop is enabled"; Array layout = { new JTextField { int columns = 40; int dragenabled = TRUE; TransferHandler transferhandler = { String property = "selected"; int action = COPY; }; }, }; }, new JLabel { String text = "I'm a Label!"; String border = "JLabel: drag from or drop to this label"; Color foreground = Color.blue; int alignment = LEADING; TransferHandler transferhandler = { String property = "text"; int action = COPY; }; mousePressed(e) { transferhandler.exportAsDrag(this, e, COPY); } }, }; }; f.visible = TRUE; adds a simple TransferHandler to a JLabel. Notice that we used mousePressed to start the drag, but a better approach would combine mousePressed and mouseDragged and only start the drag, by calling exportAsDrag, when the cursor moved a short distance from where the button was pressed. Finally, here's a slight variation of the last program that adds drag and drop to the JLabel using event handlers import yoix.*.*; JFrame f = { String title = "Drag and Drop Test"; double border = 72/12; Dimension size = NULL; GridLayout layoutmanager = { int rows = 2; }; Array layout = { new JPanel { String border = "Default drag and drop handling"; Array layout = { new JTextField { int columns = 40; int dragenabled = TRUE; }, }; }, new JLabel { String text = "Now is the time for all good men..."; String border = "Custom drag from or drop handling"; Object transferhandler = NULL; // just in case Color foreground = Color.blue; int alignment = LEADING; dragGestureRecognized(DragGestureEvent e) { e.visual = text; e.anchor = SOUTH; e.padding = 72/4; return(text); } dragEnter(DropTargetEvent e) { return(TRUE); // accept anything } drop(DropTargetEvent e) { // // See what happens to the text in TextField when // we return nothing or FALSE. // if (e.transferable instanceof String) text = e.transferable; return(TRUE); } }, }; }; f.visible = TRUE; instead of a TransferHandler. We included it here mostly to give you a quick look at both approaches.
See Also:	Clipboard, DragGestureEvent, DragSourceEvent, DropTargetEvent, JButton, JCanvas, JCheckBox, JCheckBoxMenuItem, JChoice, JColorChooser, JComboBox, JDesktopPane, JDialog, JFileChooser, JFileDialog, JDrame, JInternalFrame, JLabel, JLayeredPane, JList, JMenu, JMenuBar, JMenuItem, JPanel, JPasswordField, JPopupMenu, JProgressBar, JRadioButton, JRadioButtonMenuItem, JScrollBar, JScrollPane, JSeparator, JSlider, JSplitPane, JTabbedPane, JTable, JTextArea, JTextCanvas, JTextField, JTextPane, JTextTerm, JToggleButton, JToolBar, JTree, JWindow