Dragging Rows
- 7 minutes to read
The vertical grid controls (VGridControl and PropertyGridControl) provide enhanced facilities for dragging rows. End-users can drag rows within the control to change their order and organize them into a tree. In addition, rows can also be dragged to the Customization Form and back to the control to hide and show them respectively. These drag and drop operations are implemented by the control and do not require coding. See the Using drag and drop topic in the End-user Capabilities section for details on enabling or disabling such drag and drop operations and the ways in which they can be performed. Furthermore, the vertical grids simplify the implementation of dragging rows to other controls, it provides a number of events designed for this purpose. This topic describes these events and gives an example for implementing row drag and drop by handling them.
Row Dragging Concepts
There are three events specifically designed to control the row dragging process. These are the VGridControlBase.StartDragRow, VGridControlBase.ProcessDragRow and VGridControlBase.EndDragRow events. They fire respectively; when row dragging starts, during the dragging process and when dragging finishes. This section will describe how these events can be used. The next section will provide a code sample that uses all of them.
The VGridControlBase.StartDragRow event fires when starting to drag a row. It enables you to determine the row being dragged, the current mouse cursor position and whether the row is dragged from the control or Customization Form. These can be obtained using the RowEventArgs.Row, DragRowEventArgs.ScreenLocation and StartDragRowEventArgs.Source event parameters. You can use these parameters to determine if specific actions need to be performed. For instance, the example in the second section of this topic uses the Row parameter to determine if a multi-editor row is being dragged. If so, the target control becomes visible.
The VGridControlBase.StartDragRow event can also be used for illustrative purposes. For instance, you may wish to display an explanatory message within the status bar when dragging starts. This message could then explain that rows can be dragged to the Customization Form or within the control to rearrange them. The VGridControlBase.EndDragRow event handler could then clear the status bar in this case. Thus, the VGridControlBase.StartDragRow event can be used both when implementing custom row dragging or to provide additional facilities when dragging within the control or to the Customization Form.
The VGridControlBase.ProcessDragRow event fires repeatedly while dragging a row. It is used to handle the dragging process, to determine if a row can be dropped at the moment. This event provides the following: the row being dragged and the current mouse position. The possible effect of the drag and drop operation must be set using the DragRowEventArgs.Effect parameter. The value assigned to this property affects the mouse cursor appearance so end-users can determine whether dropping is allowed.
Write a VGridControlBase.StartDragRow event handler when implementing row dragging to external control. This event handler must, for instance, determine whether the current mouse cursor position is within the boundaries of the target control. If so, the DragRowEventArgs.Effect parameter must be set to a value that allows dropping or it must be set to RowDragEffect.None. The example in the second section of this topic shows how this can be performed.
The last event used in row dragging is the VGridControlBase.EndDragRow. This event fires when a row is dropped. Note that it is invoked regardless of whether the drop was allowed by the VGridControlBase.ProcessDragRow event handler. So, you need to obtain the control which is located under the mouse cursor to determine if there are any actions to perform. If the parameter value implies a successful drop, you need to perform any actions that are required after a successful drag and drop. For instance, if rows were dragged to a list box control, you would need to insert the item into the targeted list box. The RowEventArgs.Row event parameter can be used to determine what data to insert into the target control, or it can also be used to perform specific actions on the row which has been dragged as in the example below. The DragRowEventArgs.ScreenLocation parameter must be used if the drop depends on the target control’s element, located under the mouse cursor. For instance, if rows are dragged to the list box control, you may want to insert the caption of the dragged row prior to the item currently located under the cursor.
Custom Row Dragging Example
The example below will show you how to implement the dragging of rows to external controls using the VGridControlBase.StartDragRow, VGridControlBase.ProcessDragRow and VGridControlBase.EndDragRow events. Multi-editor rows can be moved to the picture box control. When dropping a row onto the target control, the row will be deleted from the grid and editor rows will be created in place of each row item in the dragged row. The newly created editor rows will copy the RowProperties.Caption and RowProperties.FieldName property values from the row items of the dragged multi-editor rows. Thus, dragging a multi-editor row onto the picture box will result in it splitting into several editor rows.
The sample below assumes that you already have an application with a VGridControl control on a form. This control must contain at least one multi-editor row and the VGridOptionsBehavior.DragRowHeaders behavior option must be enabled to allow row headers to be dragged.
Follow the steps below:
Place a PictureBox control onto the form. Set its Image property to be the image displayed below.
Set the picture box’s Visible property to false.
Write the following handler for the VGridControlBase.StartDragRow event. It will show the picture box control when the user starts to drag a multi-editor row.
Handle the VGridControlBase.ProcessDragRow event to allow the dragged object to be dropped when the mouse pointer is over the picture box. For this purpose, you will need to determine if the DragRowEventArgs.ScreenLocation event parameter represents a point inside the client rectangle of the picture box or not. See the required code below.
Implement the drop logic in the VGridControlBase.EndDragRow event handler as shown below. The code checks whether the dragged row has been dropped onto the picture box. If so, editor rows are created for each row item present in the dropped rows. Row items settings are copied to the newly created editor rows. After the editor rows have been created and added to the vertical grid, the dropped row is deleted and the picture box is again hidden.
private void vGridControl1_EndDragRow(object sender, DevExpress.XtraVerticalGrid.Events.EndDragRowEventArgs e) { VGridControl vGrid = sender as VGridControl; Point clientPoint = pictureBox1.PointToClient(e.ScreenLocation); if (pictureBox1.ClientRectangle.Contains(clientPoint)) { MultiEditorRow meRow = e.Row as MultiEditorRow; // assigning settings of row items to the newly created editor rows for (int i = 0; i < meRow.PropertiesCollection.Count; i++) { EditorRow row = new EditorRow(); row.Properties.Caption = meRow.PropertiesCollection[i].Caption; row.Properties.FieldName = meRow.PropertiesCollection[i].FieldName; vGrid.Rows.Add(row); } // removing the dropped row from the control vGrid.Rows.Remove(meRow); } pictureBox1.Visible = false; }Run the application and drag a multi-editor row onto the picture box. The image below displays an example of this being performed.
