EnableDragDrop Method

Syntax

Public Function EnableDragDrop( _
    ByVal [ClipboardString] As String, _
    ByVal [dragDrop] As [XTPGridDragDrop] _
) As Integer

Parameters

ClipboardString
A unique string used to identify the format of the items copied to the clipboard, for example, "GridSample:frmDragDrop". This string must be used for all Grid Controls that will receive objects of this type.
dragDrop
Specifies the type of drop operations Grid Control will support. The table below lists the values for dragDrop with a description of each.

Value	Description
`xtpGridAllowDrop`	Allow all drop operations. This allows items to be dropped into the Grid Control.
`xtpGridAllowDragCopy`	Allow copy operation. Please see XTPGridDragDrop.
`xtpGridAllowDragMove`	Allow move operation. Please see XTPGridDragDrop.
`xtpGridAllowDrag`	Allow all drag operations. This is a combination of both `xtpGridAllowDragCopy` and `xtpGridAllowDragMove`.
`xtpGridDontDropAsText`	Do not drag record as plain text.

Return Type

Returns an integer value that is used to indicate whether an item in the DataObject object matches the specified ClipboardString format. The DataObject is a parameter in OLEDrag events for controls that contains the data on the clipboard.

Remarks

To enable Drag and Drop in a Grid Control, the EnableDragDrop method must be used. EnableDragDrop does two things:

It sets a clipboard string that will be used to indicate the type of data that is copied to the clipboard.
It sets the drag and drop effects that are allowed when dragging items to/from the Grid control.

The available effects are stored in the XTPGridDragDrop enumeration. If dragging items to/from one or more Grid Controls, the same clipboard string must be used for all Grid Controls when calling EnableDragDrop.

Notes

CreateRecords is primarily used to create an empty GridRecords collection in Drag and Drop operations. The new GridRecords collection is used to create a collection of GridRecord objects to be dropped into the Grid Control or to retrieve records that have been dragged out of the Grid Control.
The CreateRecordsFromDropArray method is used when retrieving records that have been dragged from the Grid Control. CreateRecordsFromDropArray accepts the ByteArray returned from the Data.GetData parameter from any control's OLEDragDrop event and populates a GridRecords collection created by CreateRecords with the records stored on the clipboard.
The DragRecords method is used to prepare records to be dropped into the Grid Control. DragRecords accepts a GridRecords collection created by CreateRecords. Any records that have been prepared using DragRecords will be added to the Grid when the items are dropped into the Grid Control. Typically, DragRecords would be used in the MouseMove event of the control from which items are being dragged. The Grid Control will automatically add the new records to the grid once they have been dropped.
The BeginDrag event occurs when records are being dragged from the Grid Control and provides a GridRecords collection containing all of the selected records when the drag operation started. This gives the opportunity to modify the GridRecords collection before they are actually added to the clipboard.
The DropRecords event occurs when records are dropped into a Grid Control and provides a GridRecords collection containing all of the records that will be dropped into the Grid Control. This gives the opportunity to modify the GridRecords collection before they are actually added to the Grid Control.

Example

Drag and Drop Sample (Visual Basic)

This sample illustrates how to implement drag and drop support in the Grid Control. This sample is the complete code for a form that contains a single ListBox control and a single Grid Control. The name of the ListBox is 'lstItems' and the name of the Grid control is 'wdnGrid'.

Option Explicit

' An integer value that will be used to indicate whether an item in the DataObject object matches the  
' specified ClipboardString (Parameter in EnableDragDrop) format. The DataObject is a parameter in OLEDrag events for controls  
' that contains the data on the clipboard.  
Dim cfRecords As Integer  

Private Sub Form_Load()  
    ' Adds 3 items to the List Control  
    lstItems.AddItem "Item 1"  
    lstItems.AddItem "Item 2"  
    lstItems.AddItem "Item 3"  

    ' Do not allow columns to be removed from the Grid control  
    wdnGrid.AllowColumnRemove = False  

    ' Add a column named "Items" to the Grid control  
    wdnGrid.Columns.Add 0, "Items", 50, True  

    Dim Str As String, i As Long  

    ' Add 4 records/rows to the Grid control  
    For i = 4 To 8  
        Dim Record As GridRecord  
        Dim Item As GridRecordItem  

        Set Record = wdnGrid.Records.Add  
        Str = "Item " & CStr(i)  
        Set Item = Record.AddItem(Str)  
    Next i  

    ' Adds the records to the Grid control  
    wdnGrid.Populate  

    ' To enable Drag and Drop in a Grid control the EnableDragDrop method must be used. EnableDragDrop  
    ' does two things, first it sets a clipboard string that will be used to indicate the type of data  
    ' that is copied to the clipboard. Second, it sets the drag and drop effects that are allowed when  
    ' dragging items to/from the Grid control. The available effects are stored in the XTPGridDragDrop  
    ' enumeration. If dragging items to/from one or more Grid controls, the same clipboard string must  
    ' be used for all Grid controls when calling EnableDragDrop.  

    ' Below, the clipboard string is "GridSample:frmDragDrop" and we are allowing all drag and drop operations  
    cfRecords = wdnGrid.EnableDragDrop("GridSample:frmDragDrop", xtpGridAllowDrag Or xtpGridAllowDrop)  
End Sub  

Sub ClearListSelection()  
    Dim i As Long  
    For i = 0 To lstItems.ListCount - 1  
        lstItems.Selected(i) = False  
    Next  
End Sub  

' The Mouse_Move event will be used to prepare records to be dropped into the grid.  
Private Sub lstItems_MouseMove(Button As Integer, Shift As Integer, X As Single, Y As Single)  
    ' If the left mouse button is pressed while in the List Control  
    If (Button And vbLeftButton) Then  
        Dim Records As GridRecords  

        ' CreateRecords is primarily used to create an empty GridRecords collection in Drag and Drop  
        ' operations. The new GridRecords collection is used to create a collection of GridRecord  
        ' objects to be dropped into the Grid control or to retrieve records that have been dragged  
        ' out of the Grid control.  

        ' Below, a records collection is created that will contain a record for each item that  
        ' is currently selected in the list control  
        Set Records = wdnGrid.CreateRecords  

        Dim i As Long  

        ' Loop through all items in the List Control  
        For i = 0 To lstItems.ListCount - 1  
            ' If the list item is selected, then add it to then create a record for it  
            ' in the records collection  
            If lstItems.Selected(i) Then  
                Dim Record As GridRecord  

                ' Add a new record to the records collection  
                Set Record = Records.Add  
                Record.AddItem lstItems.List(i)  

                Debug.Print "Added " & i  
            End If  
        Next  

        ' The DragRecords method is used to prepare records to be dropped into the Grid control.  
        ' DragRecords accepts a GridRecords collection created by CreateRecords. Any records that  
        ' have been prepared using DragRecords will be added to the Grid when the items are dropped  
        ' into the Grid control. Typically DragRecords would be used in the MouseMove event of the  
        ' control from which items are being dragged. The Grid control will automatically add the  
        ' new records to the grid once they have been dropped.  

        ' Below, the Records collection is filled with a record that corresponds to each item that is  
        ' currently selected in the List Control. If the items are dropped into the Grid control, then  
        ' all records contained in the Records collection will be added to the grid.  

        ' Now Data.GetFormat(cfRecords) will return True as some Records have been added to the clipboard  
        wdnGrid.DragRecords Records  
    End If  
End Sub  

' The OLEDragDrop event will be used to add items to the List Control that have been dragged from the Grid control  
Private Sub lstItems_OLEDragDrop(Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single)  
    ' If the format of the data on the clipboard is of type "GridSample:frmDragDrop" as set with EnableDragDrop  
    If Data.GetFormat(cfRecords) Then  
        ' Create a ByteArray  
        Dim byteData() As Byte  

        ' Retrieve the Records collection from the clipboard, the data is stored as a ByteArray  
        byteData = Data.GetData(cfRecords)  

        Dim Records As GridRecords  

        ' The CreateRecordsFromDropArray method is used when retrieving records that have been dragged  
        ' from the Grid control. CreateRecordsFromDropArray accepts the ByteArray returned from the  
        ' Data.GetData parameter from any control's OLEDragDrop event and populates a GridRecords  
        ' collection created by CreateRecords.  

        ' Below, the Records collection is populated by the records that were copied to the clipboard  
        Set Records = wdnGrid.CreateRecordsFromDropArray(byteData)  

        ' If there were some records on the clipboard  
        If (Not Records Is Nothing) Then  
            ' Unselect all items in the list control  
            ClearListSelection  

            Dim i As Long  

            ' Add a list item for each record that was on the clipboard  
            For i = 0 To Records.Count - 1  
                lstItems.AddItem Records(i).Item(0).Value  
                lstItems.Selected(lstItems.ListCount - 1) = True  
            Next  
        End If  

        ' If the ctrl key was pressed when the items were dropped, then the drag operation was a Copy  
        ' Else, a Move operation is performed  
        If ((Shift And 2) = 0) Then  
            Effect = vbDropEffectMove  
        Else  
            Effect = vbDropEffectCopy  
        End If  
    End If  
End Sub  

' The OLEDragOver event is used to detect when items are dragged over the list control  
Private Sub lstItems_OLEDragOver(Data As DataObject, Effect As Long, Button As Integer, Shift As Integer, X As Single, Y As Single, State As Integer)  
    Effect = 0  

    ' If the format of the data on the clipboard is of type "GridSample:frmDragDrop" as set with EnableDragDrop  
    If Data.GetFormat(cfRecords) Then  
        ' If the ctrl key is pressed when items are dragged over the list control, then the drag operation is Copy  
        ' Else, a Move operation is performed  
        If ((Shift And 2) = 0) Then  
            Effect = vbDropEffectMove  
        Else  
            Effect = vbDropEffectCopy  
        End If  
    End If  
End Sub  

' The BeginDrag event occurs when records are being dragged from the Grid control, and provides a  
' GridRecords collection containing all of the selected records when the drag operation started.  
Private Sub wndGrid_BeginDrag(ByVal Records As XtremeGridControl.IGridRecords)  
    Debug.Print "Begin Drag. Records.Count = " & Records.Count  
End Sub  

' The DropRecords event occurs when records are dropped into a Grid control, and provides a  
' GridRecords collection containing all of the records that will be dropped into the Grid control.  
' This gives the opportunity to modify the GridRecords collection before they are actually added  
' to the Grid control.  
Private Sub wndGrid_DropRecords(ByVal Records As XtremeGridControl.IGridRecords)  
    Debug.Print "Drop Records. Records.Count = " & Records.Count  
End Sub