WIDGET_TREE_MOVE

The WIDGET_TREE_MOVE procedure copies and moves tree widget nodes from one tree to another or within the same tree.

WIDGET_TREE_MOVE has two parameters that specify the widget IDs of the nodes to copy and the folder (or root) in which to move (or copy) them. Each of the nodes in the first parameter will be moved (or copied). The default behavior is to duplicate the entire hierarchy rooted at each folder.

These properties are automatically inherited by all newly created nodes:

Move operations handle any data associated with UVALUEs by taking data away from the source and attaching it to the destination node, without making a temporary copy. This allows for an efficient transfer of large data during a move. The callback function can be used to adjust the values based on the parent's values.

The following keywords represent properties that are not transferred:

If these keywords must be set, the new node could be destroyed and recreated in the procedure's callback (with the same parent and index). An alternative is to write a fully custom version of WIDGET_TREE_MOVE.

For a more detailed discussion of the tree widget, along with examples, see About Tree Widgets.

This routine is written in the IDL language. Its source code can be found in the file widget_treet_move.pro in the lib subdirectory of the IDL distribution.

Examples

For examples using WIDGET_TREE_MOVE, see About Tree Widgets.

Syntax

WIDGET_TREE_MOVE, wMoveNodes, wDestFolder, CALLBACK_FUNC=name, /COPY, INDEX=value, /SELECT, /UPDATE, USERDATA=value

Arguments

wMoveNodes

The widget IDs of the nodes that are to be moved or copied. The value can be a scalar or a vector. By default, moving or copying a folder node duplicates the entire hierarchy rooted at that folder. If a node in the list is a descendant of another node in the list, then it will be copied twice: once as a member of the list and once as a member of the ancestor's descendants. For drag and drop implementations, this situation can be avoided by using the TREE_DRAG_SELECT keyword to WIDGET_INFO, which removes duplicate nodes from a tree's current selection.

wDestFolder

The widget ID of the destination folder or tree root. The value must be a scalar. If the INDEX keyword is not specified then the moved/copied nodes will be placed at the end of the destination folder's current list of children.

Keywords

CALLBACK_FUNC

Set this keyword to the name of a function to customize node moving and/or copying. The callback is invoked immediately after each and every node is duplicated. The callback must be defined as:

FUNCTION Name, wOriginalNode, wNewNode, USERDATA=value

The value from the USERDATA keyword is passed to the callback function. During move operations, the original node's UVALUE is efficiently transferred to the new node. Copy operations duplicate all UVALUEs.

The callback's return value should typically be 1 (one). This causes the new node's children to be duplicated. Entire hierarchies can be duplicated in this manner. This is the default behavior when a callback is not specified. However, if a flat copy is desired, then 0 (zero) should be returned. Return values of 0 stop further duplication of the new node so that its children are not recursively copied. Mixing return values of 0 and 1 is possible and can produce more sophisticated moves/copies.

COPY

Set this keyword to make a copy of the widgets in wMoveNodes. If not set then the original wMoveNodes are destroyed.

INDEX

Set this keyword to an integer to specify the relative position at which to insert wMoveNodes into the wDestFolder. The position is zero-based and a value of -1 (the default value) inserts at the tail.

SELECT

Set this keyword to select the newly moved/copied nodes.

UPDATE

Set this keyword to allow the source and destination trees to be visually updated during the operation. The default is to turn off updates to prevent flickering.

USERDATA

Set this keyword to a value that is passed to the CALLBACK_FUNC function.

Version History

6.3

Introduced

See Also

WIDGET_TREE, WIDGET_CONTROL, WIDGET_INFO