TreeList.CustomizeNewNodeFromOuterData Event
Fires when a node from another TreeList control is dropped onto the current TreeList control and thus, a new node in the current TreeList is about to be created. The event allows you to provide data for the new node that is to be created.
Namespace: DevExpress.XtraTreeList
Assembly: DevExpress.XtraTreeList.v19.1.dll
Declaration
[DXCategory("DragDrop")]
public event CustomizeNewNodeFromOuterDataEventHandler CustomizeNewNodeFromOuterDataEvent Data
The CustomizeNewNodeFromOuterData event's data class is CustomizeNewNodeFromOuterDataEventArgs. The following properties provide information specific to this event:
| Property | Description |
|---|---|
| DestinationNode | Gets the node onto which (or relative to which) the CustomizeNewNodeFromOuterDataEventArgs.SourceNode is dropped. |
| DestinationNodes | Gets the collection of sibling nodes relative to which the CustomizeNewNodeFromOuterDataEventArgs.SourceNode is dropped. |
| Handled | Gets or sets whether you perform all the required actions manually and no default processing is required. |
| NewData | Provides access to the dictionary that contains data to initialize a new node. |
| SourceNode | Gets the node (from another TreeList control) being dragged. |
Remarks
You can enable node drag-and-drop from another (source) TreeList control onto the current (destination) TreeList control as follows:
- Set the TreeListOptionsDragAndDrop.DragNodesMode property for the two TreeLists to Single or Multiple (depending on whether you want to enable single or multiple node drag-and-drop).
- Set the TreeListOptionsDragAndDrop.AcceptOuterNodes property to true for the current (destination) TreeList control.
- Optionally, set the TreeListOptionsDragAndDrop.CanCloneNodesOnDrop property to true for the current (destination) TreeList control to allow node copying, instead of node moving. The CTRL key needs to be pressed during a node drag to enable copy mode.
- Handle the CustomizeNewNodeFromOuterData event for the destination control to provide data for newly created nodes.
When you drop a node (CustomizeNewNodeFromOuterDataEventArgs.SourceNode) from another TreeList control onto the current (destination) TreeList, the CustomizeNewNodeFromOuterData event fires. At the time of firing the CustomizeNewNodeFromOuterData event, a new node in the current TreeList is not yet created. It will be created after your CustomizeNewNodeFromOuterData event handler is completed. The new node will be initialized with data specified by the CustomizeNewNodeFromOuterDataEventArgs.NewData dictionary.
The NewData dictionary stores key-value pairs. Keys are strings and they specify field names, while values in the dictionary are of the object type and they specify field values. After your CustomizeNewNodeFromOuterData event handler is executed, a new node will be created. Data from NewData items will be copied to the node’s corresponding fields.
Prior to calling your CustomizeNewNodeFromOuterData event handler, the NewData dictionary is initialized. “Key-value” pairs are added to the dictionary for all unique fields in the destination TreeList. The keys match the field names. If the source and destination TreeList controls contain an identical field name, the “value” portion of a corresponding NewData item is initialized with this field’s value from the source node (CustomizeNewNodeFromOuterDataEventArgs.SourceNode).
When handling the CustomizeNewNodeFromOuterData event, you can customize the NewData dictionary. For instance, you can set field values that haven’t been initialized or modify pre-initialized field values.
When the destination TreeList functions in bound mode, you have to initialize the key field name for the new node. These key field names are referred to by the TreeList.KeyFieldName and TreeList.ParentFieldName properties. Otherwise, the new node cannot be added to the TreeList control’s underlying data source. You may also need to initialize other field names based on your data source requirements.
If the Handled parameter is set to false (the default value), a new node will be created in the destination TreeList control after your CustomizeNewNodeFromOuterData event handler is completed, and it will be initialized with data from the NewData dictionary. If the Handled parameter is set to true, the new node is not automatically created. It’s up to you to manually perform this operation (when needed).
If the current drag-and-drop operation is a move operation, the source node (SourceNode) is removed from the source TreeList control (regardless of the Handled event parameter) after your CustomizeNewNodeFromOuterData event handler is executed. If the drag-and-drop operation is a copy operation (see TreeListOptionsDragAndDrop.CanCloneNodesOnDrop), the source node is not removed.
Note
Node drag-and-drop is not supported between TreeList controls that are bound to the same data source.
For an example of handling drag-and-drop between two TreeList controls, see the TreeList control’s demo.