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

General Properties

System Properties

DragSource Properties

DragSource Messages

DropTarget Properties

DropTarget Events

Drag and Drop functionality is built around three basic elements:

1. A Drag Source window/control
2. A Data Object
3. 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 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 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.

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.

The following properties are used to control the basic Drag and Drop operations:

• ENABLEDRAG
• ENABLEDRAGROWS
• ENABLEDRAGLIST
• ENABLEDROP
• ENABLEDROPHOVER
• ENABLEDROPEXPAND
• ENABLEDROPLIST

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

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.

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

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

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:

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:

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:

The following properties apply to the SYSTEM object:

• DRAGSOURCE
• DROPTARGET

Contains the name of the OpenInsight control that is the “drag source” during a drag-drop operation. Read-only.

Contains the name of the OpenInsight control that is currently the target of a DragDropoperation (if any). Read-only.

The following properties apply to the current Drag Source control. The majority of them are only effective during a DRAGSTART event:

• DRAGBUTTON
• DRAGCELLPOS
• DRAGCOPY
• DRAGFORMATLIST
• DRAGMOVE
• DRAGPOS
• DRAGSELROWCOUNT
• DRAGSELROWS
• DRAGTEXTSELECTION

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)

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.

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.

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:

See also: GETDRAGDATA, SETDRAGDATA, REMOVEDRAGDATA and CLEARDRAGDATA messages

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.

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)

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

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

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)

The following messages apply to the current Drag Source control. The majority of them are only effective during a DRAGSTART event:

• CLEARDRAGDATA
• GETDRAGDATA
• REMOVEDRAGDATA
• SETDRAGBITMAP
• SETDRAGDATA

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

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.

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

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.

This message is used to remove the specified data format from the dragged data.

retVal = Send_Message( ctrlEntID, “REMOVEDRAGDATA”, format )

Arguments

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.

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

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.

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

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.

These events apply to a control registered as a “drag source” (i.e. it’s ENABLEDRAG property is TRUE).

• DRAGSTART
• DRAGEND

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

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.

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

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.

• DRAGFORMATLIST
• DROPACCEPT
• DROPCOPY
• DROPFORMATLIST
• DROPMOVE
• DROPRESULT

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)

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.

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

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.

Used during the DRAGDROP event to let the system know what operation took place. Can be either “MOVE” or “COPY”.

See also: DRAGDROP event

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.

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.

These events apply to controls registered as “drop targets” (i.e. one of the following properties is TRUE: ENABLEDROP,ENABLEDROPHOVER or ENABLEDROPEXPAND).

• DRAGOVER
• DRAGDROP

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

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.

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

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.