Dragging and Dropping Tree Control Content
You can perform standard Windows drag and drop operations on XUI tree control items. XUI tree control drag and drop operations are accessible using ACL only. Drag and drop operations let you transfer data to and from the XUI tree control from and to other applications that also support drag and drop operations.
Two types of data can be transferred using a drag-and-drop operations:
• Text data — A block of text.
• File data — One or more file path names.
When a drag and drop operation begins in a XUI tree control, an ACL application is responsible for determining the type of data format that will be used, as well as providing the actual data. When a XUI tree control is the target of a drag and drop operation, the ACL application is responsible for examining the data available and determining how it is to be processed once it is dropped on the tree control. The meaning and the handling of the data in a drag and drop operation is completely up to the custom ACL application.
Drag and drop functionality is enabled by handling the following drag and drop events in your custom ACL application:
• DRAGDROPBEGIN — Signals the beginning of a drag and drop operation in a XUI tree control. This event is raised when the left mouse button is clicked and held down over a selected item in the source tree control and the mouse is moved. A handler for this event must be provided to allow a XUI tree control to be a drag-and-drop source. (That is, to have drag and drop operations begin in the tree control.)
DRAGDROPBEGIN has the following event handler:
ondragdropbegin(windowdlgitemddArray[])
Parameters:
◦ window — The identifier of the window containing the tree control.
◦ dlgitem — The tree control item for which the event is occurring.
◦ ddArray[] — The array to be filled with data. If the data format is DDF_TEXT, only the first element of the array contains data. All other entries in the array will be ignored for text data. If the data format is DDF_FILE, each element of the array contains an appropriate file path.
Return values:
◦ -1 — The drag and drop operation failed to start.
◦ 0 — The drag and drop operation started successfully with a data format of DDF_TEXT.
◦ 1 — The drag and drop operation started successfully with a data format of DDF_FILE.
• DRAGDROPENTER — Signals a drag and drop operation has entered the target tree control. This event is raised when the mouse is first moved into the tree control during a drag and drop operation. The handler function for this event determines what the drop effect would be if a drop were attempted at the current position.
DRAGDROPENTER has the following event handler:
ondragdropenter(windowdlgitemddFmtddArray[]keyModslisttag)
Parameters:
◦ window — The identifier of the window containing the tree control.
◦ dlgitem — The tree control item for which the event is occurring.
◦ ddFmt — The format of the drag and drop data. A value of 0 means DDF_TEXT data. A value of 1 means DDF_FILE data.
◦ ddarray[] — The array containing data. If the data format is DDF_TEXT, only the first element of the array contains data. All other entries in the array will be ignored for text data. If the data format is DDF_FILE, each element of the array contains an appropriate file path.
◦ keyMods — A bitmask specifying what relevant keys are being pressed during the drag and drop operation. This mask can be a combination of the following values:
▪ 0 — No keys are pressed.
▪ 1 — CTRL key is pressed.
▪ 2 — SHIFT key is pressed.
▪ 4 — ALT key is pressed.
◦ listtag — The tree control item to which the drop location is relative. The ACL application controls whether data is inserted before, after, or into this item. listtag may be empty if the drop position is not over a tree item.
Return values:
◦ 0 — A drop is not allowed at the current location.
◦ 1 — A drop of the data at the current location would result in data being copied.
◦ 2 — A drop of the data at the current location would result in data being moved.
The mouse cursor is set to standard Windows drag and drop cursors depending on the value returned.
• DRAGDROPOVER — Signals a drag and drop operation is over the target tree control. This event is raised when the mouse is over the tree control during a drag and drop operation. This handler function determines what the drop effect would be if a drop were attempted at the current position.
DRAGDROPOVER has the following event handler:
ondragdropover(windowdlgitemddFmtddArray[]keyModslisttag)
Parameters:
◦ window — The identifier of the window containing the tree control.
◦ dlgitem — The tree control item for which the event is occurring.
◦ ddFmt — The format of the drag and drop data. A value of 0 means DDF_TEXT data. A value of 1 means DDF_FILE data.
◦ ddarray[] — The array containing data. If the data format is DDF_TEXT, only the first element of the array contains data. All other entries in the array will be ignored for text data. If the data format is DDF_FILE, each element of the array contains an appropriate file path.
◦ keyMods — A bitmask specifying what relevant keys are being pressed during the drag and drop operation. This mask can be a combination of the following values:
▪ 0 — No keys are pressed.
▪ 1 — CTRL key is pressed.
▪ 2 — SHIFT key is pressed.
▪ 4 — ALT key is pressed.
◦ listtag — The tree control item to which the drop location is relative. The ACL application controls whether data is inserted before, after, or into this item. listtag may be empty if the drop position is not over a tree item.
Return values:
◦ 0 — A drop is not allowed at the current location.
◦ 1 — A drop of the data at the current location would result in data being copied.
◦ 2 — A drop of the data at the current location would result in data being moved.
The mouse cursor is set to standard Windows drag and drop cursors depending on the value returned.
• DRAGDROPLEAVE — Signals a drag-and-drop operation has left the target tree control. This event is raised when the mouse cursor leaves the tree control. Handle this event when you want to provide custom behavior when the drag and drop operation leaves a tree control.
DRAGDROPLEAVE has the following event handler:
ondragdropleave(windowdlgitem)
Parameters:
◦ window — The identifier of the window containing the tree control.
◦ dlgitem — The tree control item for which the event is occurring.
ondragdropenter does not return a value.
• DRAGDROPDROP — Signals a drop has occurred in the target tree control. This event is raised when a drop operation is to occur. Handle this event to insert the dropped data.
DRAGDROPENTER has the following event handler:
ondragdropenter(windowdlgitemddFmtddArray[]keyModslisttag)
Parameters:
◦ window — The identifier of the window containing the tree control.
◦ dlgitem — The tree control item for which the event is occurring.
◦ ddFmt — The format of the drag and drop data. A value of 0 means DDF_TEXT data. A value of 1 means DDF_FILE data.
◦ ddarray[] — The array containing data. If the data format is DDF_TEXT, only the first element of the array contains data. All other entries in the array will be ignored for text data. If the data format is DDF_FILE, each element of the array contains an appropriate file path.
◦ keyMods — A bitmask specifying what relevant keys are being pressed during the drag and drop operation. This mask can be a combination of the following values:
▪ 0 — No keys are pressed.
▪ 1 — CTRL key is pressed.
▪ 2 — SHIFT key is pressed.
▪ 4 — ALT key is pressed.
◦ listtag — The tree control item to which the drop location is relative. The ACL application controls whether data is inserted before, after, or into this item. listtag may be empty if the drop position is not over a tree item.
Return values:
◦ 0 — A drop is not allowed at the current location.
◦ 1 — A drop of the data at the current location would result in data being copied.
◦ 2 — A drop of the data at the current location would result in data being moved.
The mouse cursor is set to standard Windows drag and drop cursors depending on the value returned.
• DRAGDROPEND — Signals a drag and drop operation that started in the tree control has ended. This event is raised after the DRAGDROPDROP event only when the drag and drop operation started in this tree control. The event handler for this event should modify the tree control based on the resulting drop effect of the drag and drop operation. For example, if the drop effect result of the drag and drop operation is 2, meaning the drop succeeded as a move operation, the drop target will have inserted the data. This handler should delete the source data to complete the move operation.
DRAGDROPEND has the following event handler:
ontreectrldragdropend(windowdlgitemdropEff)
Parameters:
◦ window — The identifier of the window containing the tree control.
◦ dlgitem — The tree control item for which the event is occurring.
◦ dropEff — The resulting drop effect of the drag and drop operation:
▪ 0 — The drop was not allowed or was cancelled.
▪ 1 — The drop succeeded as a copy operation.
▪ 2 — The drop succeeded as a move operation.
ontreectrldragdropend does not return a value.
Example 10. Drag and drop example
A sample application demonstrating how to use the XUI tree control drag-and-drop and multiple selection functionality is included in the following directory.
Arbortext-path\samples\XUI\
The sample consists of the following files:
• treectrldddlg.xml — A XUI file defining a dockable window containing a tree control. The tree control is populated with some sample items.
• spaceimglist7.bmp — A bitmap graphic containing several images used for tree control items.
• treectrlddtest.acl — An ACL file which loads the dockable window described in treectrldddlg.xml and handles drag-and-drop functionality for it.
Use the following steps to run this sample application:
1. Copy treectrldddlg.xml and spaceimglist7.bmp to your \custom\dialogs directory.
2. Copy treectrlddtest.acl to your \custom\scripts directory.
3. Start Arbortext Editor.
4. At the Arbortext Editor command line, enter:
source treectrlddtest.acl
A window containing a tree control docked to the left side of the Arbortext Editor window will be displayed.
This sample can demonstrate the transfer of both text and file data to and from the tree control by dragging and dropping the data. For drag-and-drop operations that originate in the tree control, the convention used in this sample is:
• If a tree item has application-specific data associated with it, the application-specific data is a file path and the tree item should be dragged and dropped as file data.
• If a tree item has no application-specific data associated with it, the tree item should be dragged and dropped as text data with the item label as the data.
Initially, the tree control contains a set of sample items that have no application-specific data.
For multiple selection, no dragging and dropping is allowed if a parent-child combination is selected. This sample application provides no rules for how this should be handled, so it is not allowed.
• Demonstrating dragging and dropping text data within the tree control:
1. Select an item in the tree control.
2. Click the left mouse button on the selected item and drag it over another item in the tree control.
3. Release the left mouse button to move the item. over an item in the tree control. (Pressing CTRL while dragging and dropping copies the item.)
When a drag and drop operation beginning in the tree control results in a move operation, the original item will be deleted from the tree control automatically. The ACL application does not need to handle removing the item.
• Demonstrating dragging and dropping text data to Arbortext Editor:
1. Select an item in the tree control.
2. Click the left mouse button on the selected item and drag it over the Arbortext Editor Edit window.
3. Release the left mouse button over the Arbortext Editor window to drop the data into Arbortext Editor. The item label text will be copied into the Arbortext Editor window.
Pressing CTRL during the drag and drop operation has no effect. For dragging and dropping text data, Arbortext Editor always performs a copy operation.
• Demonstrating dragging and dropping text data from an external application:
1. Start WordPad.
2. Open a document in WordPad or type some text in an empty document.
3. Select some text in the WordPad document and drag and drop it over the tree control. The text will be inserted as an item in the tree control at the drop location and removed from the original document. Pressing CTRL while dragging and dropping copies the text to the tree control while leaving it in the original document.
Arbortext Editor does not support dragging and dropping text from an Edit window to a tree control. Text can only be dragged and dropped between Edit windows.
• Demonstrating dragging and dropping file data from an external application:
1. Open Windows Explorer and navigate to a directory containing some files. Make sure the files do not contain critical data and they are backed up.
2. Select one or more files in Windows Explorer and drag and drop them to the tree control. Each file will be inserted as an item in the tree control. The file name will be used as the item label and the application-specific data of the item will be set to the file path. The original files will also remain in their original locations.
• Demonstrating dragging and dropping file data to an external application:
1. Select a file item in the tree control placed there in the previous demonstration.
2. Drag and drop the file to a different directory in Windows Explorer. The file will move from the original location to the new location. (The original tree control item will remain, however.) Pressing CTRL during the drag and drop operation will place a copy of the file in the new location.
• Demonstrating dragging and dropping file data to Arbortext Editor:
1. Select a file item in the tree control placed there in the first file demonstration.
2. Drag the tree control item over Arbortext Editor and drop it. The file will open in Arbortext Editor.