Package com.smartgwt.client.docs

# Interface TreeGridDrop

public interface TreeGridDrop

### TreeGrid drag and drop

TreeGrids support drag and drop interactions to reorder or reparent nodes within the data tree, or to add new data to the tree.

As with listGrid, drag and drop capabilities may be enabled via properties such as `TreeGrid.canAcceptDroppedRecords`, `TreeGrid.canReorderRecords` and `TreeGrid.canDragRecordsOut`. By default, drops are only accepted on folders; set `TreeGrid.canDropOnLeaves` to true to allow dropping on leaf nodes as well.

Note that the behaviors described below are triggered automatically by interactive drag and drop, and can also be triggered programmatically by calling `TreeGrid.transferNodes()`.

Custom drop behavior: To implement custom drop behavior, developers may override `TreeGrid.folderDrop()`. Use `event.cancel()` to suppress the built-in persistence behavior, then perform the desired drop action such as calling updateData() or addData() as needed.

Drag within the same tree: Default behavior when dragging node(s) to a new folder within the same tree is to reparent the dropped node(s) by modifying their `parentId` field value. For `databound treeGrids`, an update operation will be issued unless the tree has been configured to `save locally`.
Dragging a node to a different position within its current parent reorders it locally.
See also `TreeGrid.canReparentNodes`.

Drops from another component: For drops from another widget default behavior is governed by `dragDataAction` on the source widget plus `dragRecategorize` on this treeGrid. `dragDataAction` (set on the source) controls whether dragged records are removed from the source data set on successful drop, or left in place. `dragRecategorize` (set on this treeGrid) controls how the dropped records are persisted.
Dropped data may either be recategorized or added as a new node.

Drag-Recategorize: TreeGrids support recategorizing records on drop when the source component is either bound to the same DataSource, or a DataSource with a `foreignKey` relationship with this treeGrid's DataSource.

When both the source and target components are bound to the same DataSource - for example when a ListGrid is used to display a flat list of nodes from the selected folder of a TreeGrid - dropping a record into the TreeGrid will update the `parentIdField` on the dropped records to match the `idField` of the target folder.

When the source and target components' DataSources are related by foreignKey - for example when a ListGrid displays related records from a master tree of categories - the foreignKey field on the dropped records is updated to point to the target folder.

Whether this automatic behavior is applied depends on `dragRecategorize` (set on the target):

- `"checked"` (the default): recategorize only if the source widget's `dragDataAction` is "move". This is the normal case: the user is moving data to a new location, so updating the foreignKey or parentId is appropriate.
- `"always"`: recategorize regardless of `dragDataAction`. This allows you to update the foreignKey/parentId even when the source retains a copy of the record due to `dragDataAction:"copy"` (e.g., dragging from a template palette).
- `"never"`: never recategorize. Drops always go through the generic add path below.

Add data: The default TreeGrid drop behavior when drag-recategorize is not applicable or has been disabled via `dragRecategorize:"never"` is to add dropped records to the tree via `DataSource.addData()`, with the `parentId` set to the target folder. `addDropValues` and `getDropValues` are applied. If `DataBoundComponent.preventDuplicates` is set, a duplicate check is performed (which may require a server round-trip if the cache is incomplete).

In all databound cases, `queuing` is used to combine the DSRequests for a multi-record drop into a single HTTP request, allowing the server to persist all changes in a single transaction.

Visual feedback

The `TreeGrid.showDropIcons` and `ListGrid.showDropLines` properties enable customization of the grid appearance during drag interactions.

By default users may drop data after the last node in the grid. The `TreeGrid.canDropSiblingAfterLastNode` feature allows data to be added as either a sibling of the last node, or to the tree's root node. The `TreeGrid.showDropEndSpace` causes a spacer to be written out after the last node during drag, so there is space available to accept the drop even if the data fills the TreeGrid viewport. To entirely disable this behavior, set `ListGrid.canDropInEmptyArea` to false.

For details of how data transfer from a TreeGrid to another DataBoundComponent is handled, see `TreeGrid.transferDragData()` and `ListGrid.getDragData()`.

See Also:
  - `TreeGrid.willAcceptDrop()`
  - `FolderDropEvent`
  - `com.smartgwt.client.widgets.tree.TreeGrid#folderDrop`
  - `TreeGrid.transferNodes(com.smartgwt.client.widgets.tree.TreeNode[], com.smartgwt.client.widgets.tree.TreeNode, java.lang.Integer, com.smartgwt.client.widgets.Canvas, com.smartgwt.client.widgets.tree.TransferNodesCallback)`
  - `TreeGrid.getCanDragRecordsOut()`
  - `TreeGrid.getCanAcceptDroppedRecords()`
  - `TreeGrid.getCanReorderRecords()`
  - `TreeGrid.getCanDropOnLeaves()`
  - `TreeGrid.getCanReparentNodes()`
  - `ListGrid.getDragDataAction()`
  - `TreeGrid.getShowDropEndSpace()`