
package com.smartgwt.client.docs;

/**
 * <h3>TreeGrid drag and drop</h3>
 * TreeGrids support drag and drop interactions to reorder or reparent nodes within the data tree,
 * or to add new data to the tree. <P> As with listGrid, drag and drop capabilities may be enabled
 * via properties such as {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getCanAcceptDroppedRecords
 * TreeGrid.canAcceptDroppedRecords}, {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getCanReorderRecords TreeGrid.canReorderRecords} and
 * {@link com.smartgwt.client.widgets.tree.TreeGrid#getCanDragRecordsOut
 * TreeGrid.canDragRecordsOut}.  By default, drops are only accepted on folders; set {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getCanDropOnLeaves TreeGrid.canDropOnLeaves} to true
 * to allow dropping on leaf nodes as well. <P> Note that the behaviors described below are
 * triggered automatically by interactive drag and drop, and can also be triggered
 * programmatically by calling {@link com.smartgwt.client.widgets.tree.TreeGrid#transferNodes
 * TreeGrid.transferNodes()}. <P> <b>Custom drop behavior</b>: To implement custom drop behavior,
 * developers may override {@link com.smartgwt.client.widgets.tree.TreeGrid#folderDrop
 * TreeGrid.folderDrop()}.  Use <code>event.cancel()</code> to suppress the built-in persistence
 * behavior, then perform the desired drop action such as calling updateData() or addData() as
 * needed. <P> <b>Drag within the same tree:</b> Default behavior when dragging node(s) to a new
 * folder within the same tree is to reparent the dropped node(s) by modifying their {@link
 * com.smartgwt.client.widgets.tree.Tree#getParentIdField parentId} field value. For {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getDataSource databound treeGrids}, an update
 * operation will be issued unless the tree has been configured to {@link
 * com.smartgwt.client.widgets.grid.ListGrid#getSaveLocally save locally}.<br> Dragging a node to
 * a different position within its current parent reorders it locally.<br> See also {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getCanReparentNodes TreeGrid.canReparentNodes}. <P>
 * <b>Drops from another component:</b> For drops from another widget default behavior is governed
 * by {@link com.smartgwt.client.widgets.tree.TreeGrid#getDragDataAction dragDataAction} on the
 * source widget plus {@link com.smartgwt.client.widgets.DataBoundComponent#getDragRecategorize
 * dragRecategorize} on this treeGrid. <code>dragDataAction</code> (set on the source) controls
 * whether dragged records are removed from the source data set on successful drop, or left in
 * place. <code>dragRecategorize</code> (set on this treeGrid) controls how  the dropped records
 * are persisted.<br> Dropped data may either be recategorized or added as a new node. <P>
 * <i>Drag-Recategorize</i>: TreeGrids support recategorizing records on drop when the source
 * component is either bound to the same DataSource, or a DataSource with a {@link
 * com.smartgwt.client.data.DataSourceField#getForeignKey foreignKey} relationship with this
 * treeGrid's DataSource. <P> 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 {@link
 * com.smartgwt.client.widgets.tree.Tree#getParentIdField parentIdField} on the dropped records to
 * match the {@link com.smartgwt.client.widgets.tree.Tree#getIdField idField} of the target
 * folder. <P> 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. <P> Whether
 * this automatic behavior is applied depends on {@link
 * com.smartgwt.client.widgets.DataBoundComponent#getDragRecategorize dragRecategorize} (set on
 * the target): <ul> <li><code>"checked"</code> (the default): recategorize     only if the source
 * widget's     {@link com.smartgwt.client.widgets.tree.TreeGrid#getDragDataAction 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. <li><code>"always"</code>: recategorize
 * regardless of     <code>dragDataAction</code>. This allows you to update     the
 * foreignKey/parentId even when the source retains a copy of the     record due to
 * <code>dragDataAction:"copy"</code> (e.g., dragging from a template palette).
 * <li><code>"never"</code>: never recategorize.  Drops     always go through the generic add path
 * below. </ul> <P> <i>Add data:</i> The default TreeGrid drop behavior when drag-recategorize is
 * not applicable or has been disabled via <code>dragRecategorize:"never"</code> is to add dropped
 * records to the tree via {@link com.smartgwt.client.data.DataSource#addData
 * DataSource.addData()}, with the {@link com.smartgwt.client.widgets.tree.Tree#getParentIdField
 * parentId} set to the target folder. {@link
 * com.smartgwt.client.widgets.DataBoundComponent#getAddDropValues addDropValues} and {@link
 * com.smartgwt.client.widgets.DataBoundComponent#getDropValues getDropValues} are applied. If
 * {@link com.smartgwt.client.widgets.DataBoundComponent#getPreventDuplicates
 * DataBoundComponent.preventDuplicates} is set, a duplicate check is performed (which may require
 * a server round-trip if the cache is incomplete). <P> In all databound cases, {@link
 * com.smartgwt.client.rpc.RPCManager 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. <P> <b>Visual feedback</b> <P> The {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getShowDropIcons TreeGrid.showDropIcons} and {@link
 * com.smartgwt.client.widgets.grid.ListGrid#getShowDropLines ListGrid.showDropLines} properties
 * enable customization of the grid appearance during drag interactions. <P> By default users may
 * drop data after the last node in the grid. The {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getCanDropSiblingAfterLastNode
 * TreeGrid.canDropSiblingAfterLastNode} feature allows data to be added as either a sibling of
 * the last node, or to the tree's root node.  The {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#getShowDropEndSpace 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 {@link com.smartgwt.client.widgets.grid.ListGrid#getCanDropInEmptyArea
 * ListGrid.canDropInEmptyArea} to false. <P> For details of how data transfer <i>from</i> a
 * TreeGrid to another DataBoundComponent is handled, see {@link
 * com.smartgwt.client.widgets.tree.TreeGrid#transferDragData TreeGrid.transferDragData()} and
 * {@link com.smartgwt.client.widgets.grid.ListGrid#getDragData ListGrid.getDragData()}.
 * @see com.smartgwt.client.widgets.tree.TreeGrid#willAcceptDrop
 * @see com.smartgwt.client.widgets.tree.events.FolderDropEvent
 * @see com.smartgwt.client.widgets.tree.TreeGrid#folderDrop
 * @see com.smartgwt.client.widgets.tree.TreeGrid#transferNodes
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getCanDragRecordsOut
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getCanAcceptDroppedRecords
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getCanReorderRecords
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getCanDropOnLeaves
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getCanReparentNodes
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getDragDataAction
 * @see com.smartgwt.client.widgets.tree.TreeGrid#getShowDropEndSpace
 */
public interface TreeGridDrop {
}
