Table of Contents
OpenInsight Drag and Drop
OpenInsight now includes the ability to implement Drag and Drop capabilities within you application. This document outlines the concept, elements, events and properties of Drag and Drop within OpenInsight.
Overview
Drag and Drop functionality is built around three basic elements:
- A Drag Source window/control
- A Drop Target window/control
These elements interact with each other in the following way:
- The user starts to drag data from a Drag Source control.
- If the Drag Source allows the operation a Data Object is created and populated with data.
- Control is passed to the operating system.
- As the data is dragged across the screen the operating system looked for controls registered as Drop Targets. When the data passes over one it is notified via various events.
- The Drop Target queries the Data Object and informs the operating system if it can accept the data.
- If the data is dropped the Drop Target updates itself with the dragged data.
- The Drop Source is notified of the drop result and performs any cleanup tasks like deleting selected data for a move operation for example.
The Drag Source
The Drag Source is defined as the control or window that is capable of having data dragged from it. It is responsible for:
- Deciding if the drag is actually allowed
- Creating a Data Object and populating it with dragged data in one or more formats
- Creating a drag image (if any)
- Deciding if the dragged data is allowed to be copied or moved
- Deleting the dragged data from itself if the data was moved.
In OpenInsight, a window or control is flagged as a Drag Source by setting its ENABLEDRAG property to TRUE$, either dynamically at runtime, by setting a PS style bit in the Form Designer or through the use of the ADD_DND system tool.
The Data Object
The Data Object is created to hold the data that is to be dragged. This data does not necessarily have to be in one format. Applications that use Drag and Drop frequently place more than one format in the Data Object – this allows target controls and applications to pick which format they prefer giving the Drag and Drop operation more chance of success.
The Data Object is populated by the Drag Source when the drag operation begins, and queried by a Drop Target during and on completion of a drag drop process.
The Data Object is created and managed internally by OpenInsight. It may be modified by the Drag Source when first created during a DRAGSTART event, and queried by the Drop Target during the DRAGOVER and DROPDROP events.
When created, OpenInsight usually fills the Data Object with one or more data formats.
The Drop Target
A Drop Target is defined as a control or window that can accept and respond to notifications that data is being dragged over it. It is responsible for:
- Deciding if it can accept the dragged data be querying the Data Object to see what formats it contains
- Giving visual feedback as the data is dragged over it. This includes operations such as automatic scrolling and listbox node expansion for example
- Copying data from the Data Object into the control when the data is dropped.
In OpenIsight, a window or control is flagged as a drop target by setting it’s ENABLEDROP property to TRUE$, either dynamically at runtime, by setting a PS style bit in the Form Designer or through the use of the ADD_DND system tool.
General Properties
The following properties are used to control the basic Drag and Drop operations:
ENABLEDRAG property
Set this property to TRUE$ to enable data to be dragged from a control. OpenInsight will monitor mouse messages sent to the control and will detect if the user attempts to drag data from them.
Applies To : All controls except OLE controls.
Remarks:
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
See also: DRAGSOURCE property, DRAGSTART, DRAGEND events
ENABLEDRAGROWS property
Set this property to TRUE to allow selected rows to be dragged in an edit table. If this flag is not set only data from single cells is allowed to be dragged (if their COLSTYLE is set accordingly).
Applies To: EDITTABLE
Remarks:
- This property only applies to EditTable controls that have an ENABLEDRAG property set to TRUE$.
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
See also: ENABLEDRAG property, COLSTYLE message.
ENABLEDRAGLIST property
Set this property to TRUE$ to allow combobox drag source controls to register their list component as a drag source too.
Applies To: COMBOBOX controls
Remarks:
- This property only applies to combobox controls that have an ENABLEDRAG property set to TRUE$.
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
See also: ENABLEDRAG property
ENABLEDROP property
Set this property to TRUE$ to mark the control as a drop target, which means that the control will be notified when data is dragged over it.
Applies To: All controls except OLE controls.
Remarks:
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
See also: DROPTARGET property, DRAGOVER, DRAGDROP events
ENABLEDROPSCROLL property
Set this property to TRUE$ to allow a drop target control to response to mouse hover notifications while data is dragged over it. In most cases this performs automatic scrolling of the drop target control when near the edge of the control’s client area.
Applies To: All controls except OLE controls.
Remarks:
- This property only applies to controls that have an ENABLEDROP property set to TRUE$.
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
ENABLEDROPEXPAND property
Set this property to TRUE$ to allow a hierarchical lisbox drop target control to response to mouse hover notifications but expanding a node automatically.
Applies To: Hierarchical LISTBOX controls
Remarks:
- This property only applies to a hierarchical listbox controls that have an ENABLEDROP property set to TRUE$.
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
ENABLEDROPLIST property
Set this property to TRUE$ to allow simple combobox drop target controls to register their list component as a drop target too.
Applies To: Simple COMBOBOX controls
Remarks:
- This property only applies to a combobox controls that have an ENABLEDROP property set to TRUE$.
- This property corresponds to the following PS style bit that may be set by in the Form Designer with the Raw Style Bit Editor:
SYSTEM properties
The following properties apply to the SYSTEM object:
DRAGSOURCE property
Contains the name of the OpenInsight control that is the “drag source” during a drag-drop operation. Read-only.
DROPTARGET property
Contains the name of the OpenInsight control that is currently the target of a DragDropoperation (if any). Read-only.
Drag Source Properties
The following properties apply to the current Drag Source control. The majority of them are only effective during a DRAGSTART event:
DRAGBUTTON property
Contains a number specifying which mouse button was used to start the drag operation. Read-only.
- 0: Left mouse button
- 1: Right mouse button
- 2: Middle mouse button
Applies To: The control that is currently the drag source (see the SYSTEM DRAGSOURCE property)
DRAGCELLPOS property
Contains the cell position of data being dragged from an edit table in the format:
Column : @fm : Row
Applies to: EDITTABLE when the control is currently the drag source (see the SYSTEM DRAGSOURCE property) and cell data is being dragged.
See also: DRAGTEXTSELECTION property.
DRAGCOPY property
Returns or sets a flag denoting if the drag source allows a COPY operation. This property should be set during the DRAGSTART event to override the default copy setting.
Applies To: Any control that is flagged as drag enabled (i.e. it’s ALLOWDRAG property is TRUE).
See also: ALLOWDRAG, DRAGMOVE properties.
DRAGFORMATLIST property
Contains an @fm-delimited list of data formats being dragged. Read-only.
Applies To: The control that is currently the drag source (see the SYSTEM DRAGSOURCE property)
Remarks:
- To modify the data being dragged use the GETDRAGDATA, SETDRAGDATA, REMOVEDRAGDATA and CLEARDRAGDATA messages.
- The following table describes what default data formats OpenInsight loads into the data object when a drag is started:
| Control Type | Formats | Notes |
|---|---|---|
| BITMAP | BITMAP | |
| FILENAME | (if applicable) | |
| COMBOBOX (Item) | TEXT | |
| COMBOBOX (List) | OI_LIST | @fm-delimited list |
| TEXT | CRLF-delimited list | |
| EDITLINE | TEXT | |
| EDITBOX | TEXT | CRLF-delimited text |
| EDITTABLE (Cell) | TEXT | |
| EDITTABLE (Rows) | OI_EDT_ROWLIST | @fm/@vm-delimited list |
| TEXT | CRLF/TAB delimited list | |
| LISTBOX | OI_LIST | @fm-delimited list |
| TEXT | CRLF-delimited list |
See also: GETDRAGDATA, SETDRAGDATA, REMOVEDRAGDATA and CLEARDRAGDATA messages
DRAGMOVE property
Returns or sets a flag denoting if the drag source allows a MOVE operation. This property should be set during the DRAGSTART event to override the default move setting.
Applies To: Any control that is flagged as drag enabled (i.e. it’s ALLOWDRAG property is TRUE).
See Also: ALLOWDRAG, DRAGCOPY properties.
DRAGPOS property
Contains the client coordinates of the mouse (i.e relative to the control’s client area) when the drag operation started. Read-Only.
Property is returned in the format:
xPos : @fm : yPos
Applies To: The control that is currently the DragSource (see the SYSTEM DRAGSOURCE property)
DRAGSELROWCOUNT property
Contains the number of rows being dragged from a row-oriented control.
Applies To: LISTBOX, EDITTABLE when the control is currently the drag source (see the SYSTEM DRAGSOURCE property) and row data is being dragged.
See also: DRAGSELROWS property
DRAGSELROWS property
Contains the row numbers of the data being dragged from a row-oriented control. Multiple row numbers are @fm delimited.
Applies To: LISTBOX, EDITTABLE when the control is currently the drag source (see the SYSTEM DRAGSOURCE property) and row data is being dragged.
See also: DRAGSELROWCOUNT property
DRAGTEXTSELECTION property
This property contains the starting point and length of selected text used for a drag operation in the format
startPos : @fm : length
Applies to: EDITLINE, EDITBOX, EDITTABLE when the control is currently the drag source (see the SYSTEM DRAGSOURCE property)
DragSource messages
The following messages apply to the current Drag Source control. The majority of them are only effective during a DRAGSTART event:
GETDRAGDATA message
This message is used to extract data of a specified format from a dragged data object. It may be used against both drag source and drop target controls in all drag-drop related events.
dragData = Send_Message( ctrlEntID, “GETDRAGDATA”, format, unicode, maxlen)
Arguments
| Argument | Description |
|---|---|
| ctrlEntID | Must be a current drag source or drop target control (See the SYSTEM DRAGSOURCE and DROPTARGET properties) |
| format | Name of the format that you want to extract. This can be a custom format or one of the following standard OI data formats: “TEXT” - Returns dragged textual data and automatically handles any Unicode translations required “FILENAME” - Returns a dragged filename. “BITMAP” - Returns a dragged bitmap handle. See notes below regarding dragged bitmap handles for further information. |
| unicode | When using a custom textual format set this flag to true for OI to perform a Unicode to UTF8/ANSI translation automatically if you know the data is a Unicode string. |
| maxlen | When using a custom format and extracting binary data set this to the maximum number of bytes that OI should extract. |
Returns
The dragged data for the specified format.
Remarks
- When extracting BITMAP data OI returns you a handle to the bitmap. This is actually a copy of the bitmap that is being dragged so YOU are responsible for deleting it when you no longer need it. You may do this with the DeleteObject() Windows API function.
SETDRAGDATA message
This message is used to set the data for a nominated format for a drag source control.
retVal = Send_Message( ctrlEntID, “SETDRAGDATA”, format, unicode, data )
Arguments
| Argument | Description |
|---|---|
| ctrlEntID | Must be a current drag source control (See the SYSTEM DRAGSOURCE property) |
| format | Name of the format that you want to set. This can be a custom format or one of the following standard OI data formats: “TEXT” - Sets textual data in both ANSI and Unicode format “FILENAME” - Sets a filename data format. “BITMAP” - Sets BITMAP a bitmap data format. The data should be a bitmap path (see BITMAP property) |
| unicode | When using a text-based custom format set this flag to true for OI to perform a UTF8/ANSI to Unicode translation automatically before setting the data. |
| data | The data to set. |
Returns
TRUE$ if the data was set correctly, FALSE$ otherwise
Remarks
- This message can only be used during the DRAGSTART event for the drag source control.
REMOVEDRAGDATA message
This message is used to remove the specified data format from the dragged data.
retVal = Send_Message( ctrlEntID, “REMOVEDRAGDATA”, format )
Arguments
| Argument | Description |
|---|---|
| ctrlEntID | Must be a current drag source control (See the SYSTEM DRAGSOURCE property) |
| format | Name of the format that you want to remove. This can be a custom format or one of the following standard OI data formats: “TEXT” - Sets textual data in both ANSI and Unicode format “FILENAME” - Sets a filename data format. “BITMAP” - Sets BITMAP a bitmap data format. The data should be a bitmap path (see BITMAP property) |
Returns
TRUE$ if the data was removed, FALSE$ otherwise
Remarks
- This message can only be used during the DRAGSTART event for the drag source control.
CLEARDRAGDATA message
This message removes all data from the drag source data object. This can be used during a DRAGSTART event to cancel the drag if you wish.
retVal = Send_Message( ctrlEntID, “CLEARDRAGDATA”, format )
Arguments
| Argument | Description |
|---|---|
| ctrlEntID | Must be a current drag source control (See the SYSTEM DRAGSOURCE property) |
Returns
TRUE$ if the data was removed, FALSE$ otherwise
Remarks
- This message can only be used during the DRAGSTART event for the drag source control.
SETDRAGBITMAP message
This message sets the bitmap used by the system when dragging data from the drag source.
retVal = Send_Message( ctrlEntID, “SETDRAGBITMAP”, bmp, xOffset, yOffset, tc )
Arguments
| Argument | Description |
|---|---|
| ctrlEntID | Must be a current drag source control (See the SYSTEM DRAGSOURCE property) |
| bmp | Path of the bitmap image to use – see the BITMAP property. |
| xOffset | X offset of the image from the cursor hotspot |
| yOffset | Y offset of the image from the cursor hotspot |
| tc | Color to use as the transparent color if the image has transparent parts |
Returns
TRUE$ if the image was created, FALSE$ otherwise
Remarks
- This message can only be used during the DRAGSTART event for the drag source control.
- The xOffset and yOffset arguments are used to place the image top left pixel relative to the cursor’s hotspot.
DragSource Events
These events apply to a control registered as a “drag source” (i.e. it’s ENABLEDRAG property is TRUE).
DRAGSTART event
This event is fired in response to a drag operation beginning on a control. This means that the user has clicked a mouse button down on a control and has begun to drag. The main tasks that should be addressed in this event are (in no particular order):
- Deciding if the drag operation should be aborted
- Amending dragged data formats by adding any custom ones and removing any unwanted defaults.
- Setting a drag image. This is the image that will be moved with the cursor and shown when over an OI drop target. (Dragging images over non-OI windows is not currently supported).
Event Parameters
| Parameter | Description |
|---|---|
| MouseDownX | x coordinate where the drag started (relative to the client area) |
| MouseDownY | y coordinate where the drag started (relative to the client area) |
| CtrlKey | TRUE$ if the Ctrl key was held down when the drag was started |
| ShiftKey | TRUE$ if the Shift key was held down when the drag was started |
| AltKey | TRUE$ if the Alt key was held down when the drag was started |
| MouseButton | Denotes which mouse button was held down when the drag was started: ‘0’ - Left Mouse Button ‘1’ - Right Mouse Button ‘2’ - Middle Mouse Button |
Remarks
- To abort the drag operation simply remove all drag data formats from the drop source by using the REMOVEDRAGDATA or CLEARDRAGDATA messages
- This event is fired synchronously. If it fails to fire for whatever reason the drag operation will be aborted.
DRAGEND event
This event is fired after a drop operation has ended and is used to inform the drop source of the results of the operation. The main tasks that should be addressed in this event are (in no particular order):
- If the operation was a MOVE using a custom data format then data will most likely need to be deleted from the control.
- Any cleanup procedures may be called.
Event Parameters
| Parameter | Description |
|---|---|
| DragResult | Result of the DragDrop operation. Can be one of the following: ‘CANCEL’ ‘COPY’ ‘MOVE’ |
Remarks
- Normal DragDrop operations from one control to another result in the target control copying and rendering the dropped data in it’s DRAGDROP event, and the source control deleting it during the DRAGEND event. However, in the case of a MOVE operation within the same control the normal convention is to handle all data movements within the source control DRAGEND event.
- This event is fired asynchronously.
DropTarget properties
DROPACCEPT property
Set to FALSE$ during a DRAGOVER event to stop OI performing any more data comparisons against the drop target until the control is entered again.
Applies To: The control that is currently the drop target (see the SYSTEM DROPTARGET property)
See also: DRAGFORMATLIST, DROPFORMATLIST properties, DRAGOVER, DRAGDROP events
Remarks
* This property is basically an optimization technique. If you are sure that the control will not accept the current drag data at any point during the operation then set this property to FALSE$ will save processing time. * It is reset to TRUE$ whenever drag data enters the control again (i.e. the DRAGOVER ENTER event)
DROPCOPY property
Set this property to TRUE$ to allow the drag data to be copied to the drop target.
Applies To: The control that is currently the drop target (see the SYSTEM DROPTARGET property)
See also: DRAGMOVE property, DRAGOVER, DRAGDROP events
Remarks
- If the drag source does not allow a copy operation setting this property to TRUE will have no effect.
- OI sets this property before calling the DRAGOVER over based upon the restrictions of the drag source and the user keyboard state.
DRAGFORMATLIST property
Returns an @fm delimited list of data formats being dragged. Read-only. OI compares the list of formats defined in the control’s DROPFORMATLIST property against the formats in the DRAGFORMATLIST property to determine if a drag can be made or not.
Applies To: The control that is currently the drop target (see the SYSTEM DROPTARGET property)
See also: Drop Source DRAGFORMATLIST property, DRAGOVER, DRAGDROP events
DROPFORMATLIST property
Returns an @fm delimited list of data formats accepted by the control and should be sorted in order of preference. During DRAGOVER events the system will examine the data being dragged and compare it to the formats in this list, selecting the first match it finds.
Applies To: Any control defined as a drop target.
See also: DRAGOVER, DRAGDROP events. DROPTARGET property.
DROPTYPE property
Used during the DRAGDROP event to let the system know what operation took place. Can be either “MOVE” or “COPY”.
See also: DRAGDROP event
DROPMOVE property
Set this property to TRUE$ to allow the drag data to be moved to the drop target.
Applies To: The control that is currently the drop target (see the SYSTEM DROPTARGET property)
See also: DRAGCOPY property, DRAGOVER, DRAGDROP events
Remarks
- If the drag source does not allow a move operation setting this property to TRUE will have no effect.
- OI sets this property before calling the DRAGOVER over based upon the restrictions of the drag source and the user keyboard state.
DROPRESULT property
When set during a DRAGDROP event it prevents the OI from performing any default data copy or move operations after the event returns. Basically you are saying that you have handled all operations necessary and that OI should perform no further processing after the DRAGDROP event returns.
Values you may set are:
- “MOVE”
- “COPY”
This value will be passed to the DRAGSOURCE DRAGEND event if appropriate.
Applies To: The control that is currently the “drop target” (see the SYSTEM DROPTARGET property)
Remarks: This property can only be set during a DRAGDROP event. If is reset to null at the start of every DRAGDROP event.
DropTarget Events
These events apply to controls registered as “drop targets” (i.e. one of the following properties is TRUE: ENABLEDROP,ENABLEDROPHOVER or ENABLEDROPEXPAND).
DRAGOVER event
This event is fired at a drop target control in response to data being dragged into, over and out of it. For this reason there are four separate subcategories:
1. DragEnter: Data has been dragged into the drop target. The main tasks that should be addressed at this point are (in no particular order):
- Determining if the data is in an acceptable format and can be dropped.
- Visual feedback – updating the cursor or selection position
- Caching any information needed to restore the controls state when the
2. DragMove: Data is being dragged across a control. The main tasks that should be addressed at this point are (in no particular order):
- Determining if the data is in an acceptable format and can be dropped.
- Visual feedback – updating the cursor or selection position
3. DragHover: The mouse is hovering over the control while dragging data. The main tasks that should be addressed at this point are (in no particular order):
- Visual feedback – updating the cursor or selection position, usually by scrolling if near the edge of the control.
- Determining if the data is in an acceptable format and can be dropped.
4. DragLeave: The data has been dragged out of the control without being dropped. The main tasks that should be addressed at this point are (in no particular order):
- Visual feedback – updating the cursor or selection position.
- Restoring the original control state before the Drag Enter if appropriate.
Event Parameters
| Parameter | Description |
|---|---|
| DragEvent | Describes the type of DRAGOVER event taking place. Can be one of the following: “ENTER” - Data has been dragged onto a control for the first time “MOVE” - Data is being dragged across a control “HOVER” - Mouse is hovering above a control with dragged data “LEAVE” - The data has been dragged outside of the control |
| MouseX | x coordinate of the mouse (relative to the client area) |
| MouseY | y coordinate of the mouse (relative to the client area) |
| CtrlKey | TRUE$ if the Ctrl key is held down |
| ShiftKey | TRUE$ if the Shift key is held down |
| AltKey | TRUE$ if the Alt key is held down |
| MouseButton | Denotes which mouse button is being held down: ‘0’ - Left Mouse Button ‘1’ - Right Mouse Button ‘2’ - Middle Mouse Button |
Remarks
- Before this event is fired OI performs some processing to determine if there is any need to actually execute it. It examines the various formats of the dragged data and compares them to the drop target’s DROPFORMATLIST property. If a match is not found then
- This event is fired synchronously.
DRAGDROP event
This event is fired at a drop target control when the user has dropped data onto it. The main tasks that should be addressed at this point are (in no particular order):
- Extract the data from the data object using the GETDRAGDATA message and load in into the Drop Target control
Event Parameters
| Parameter | Description |
|---|---|
| DataFormat | Contains the name of the dropped data format |
| DropResult | Contains the desired action – MOVE or COPY. |
| xDown | x coordinate where the data was dropped (relative to the client area) |
| yDown | y coordinate where the data was dropped (relative to the client area) |
| CtrlKey | TRUE$ if the Ctrl key was held down when the data was dropped |
| ShiftKey | TRUE$ if the Shift key was held down when the data was dropped |
| AltKey | TRUE$ if the Alt key was held down when the data was dropped |
| MouseButton | Denotes which mouse button was held down when the data was dropped: ‘0’ - Left Mouse Button ‘1’ - Right Mouse Button ‘2’ - Middle Mouse Button |
Remarks
- Before this event is fired OI performs some processing to determine if there is any need to actually execute it. It examines the various formats of the dragged data and compares them to the drop target’s DROPFORMATLIST property. If a match is not found then
- If the result of the operation is a MOVE and the drop source is the same control as the drop target then the actual data transfer is usually handled in the Drop Source DRAGEND event rather than in this event.
- This event is fired synchronously.