BBj Drag and Drop

Description

In BBj 7.0 and higher, most BBj GUI controls support drag and drop. By default, this works as expected based on standard platform rules. If more advanced or unusual functionality is needed, APIs enable the programmer to take more complete control of the drag/drop process.

Definition

Drag and drop is a direct manipulation gesture that enables users to click on a screen object, drag it to another location (move the mouse while keeping the mouse button pressed), and drop it in place (release the mouse button). Drag and drop can COPY, MOVE, or LINK data from the source to the target, as described below.

Terms

Term

Definition

Drag Source

The origin of the drag operation where the user clicks the mouse button and starts to drag the mouse. This can be a BBjControl or any other GUI element on the desktop. When the drag source recognizes that the user initiated a drag operation, it packages its data in a format that can be scanned quickly by potential drop targets.

Drag/Drop Actions

When a drag source packages its data, it also announces the drag/drop action or actions that it supports – COPY, MOVE, and LINK.

  • COPY copies data from one location (equivalent to pressing CTRL+C) and pastes it to another location (equivalent to pressing CTRL+V)

  • MOVE cuts data from one location (equivalent to pressing CTRL+X) and pastes it to another location (again, equivalent to CTRL+V)

  • LINK is application-defined; it indicates that an ongoing linkage should be established between the source and the target

Keyboard Modifiers

The preference for a particular action when pressing one or more keys while dragging. These keyboard modifiers can vary for each platform, but typically,

  • SHIFT indicates a preference for a MOVE action

  • CTRL indicates a preference for a COPY action (Option or ALT on macOS)

  • CTRL+SHIFT indicates a preference for the LINK action.

Drop Target

As the user drags the mouse across each GUI element on the desktop, that element becomes a potential target for the drop. It examines the data formats being dragged and changes the cursor to indicate which of the available actions would be used if the data were to be dropped there. The user completes the drop process by releasing the mouse button over the drop target.

Drag/Drop Data Format

When a drag source packages its data for dragging, it typically makes it available in several different formats. Each potential drop target examines the list of available formats and actions and determines if it is prepared to accept one of the formats and actions being offered. Java and BBj identify data formats using MIME types. MIME types are strings in the general form "primary/secondary[;options]." Some common formats are "text/plain", "text/html", and "image/jpeg".

Drag/Drop Type Codes

The developer can assign an application-defined type to a control (Interface DragSource::setDragType) that identifies this control as having a particular meaning to other BBjControls. As data is dragged over potential drop targets, the drag type string is compared to an optional list of drop type strings to decide if the data is acceptable (Interface DropTarget::setDropTypes). For an additional level of control, the BBjTree allows for node-specific drag and drop types, and the BBjGrid allows for both column-specific and cell-specific drag and drop types. The combination of the DragType from the drag source control and the DropTypes on the drop target control enables the developer to define precise filters to control the drag/drop process to whatever level of detail is required.

Default Behavior

The following BBjControls implement default drag and drop behavior. See example.

BBjControl

Acting as a drag source

Acting as a drop target

BBjButton, BBjMenuButton, BBjToolButton

In BBj 16.0 and higher, the user can drag from a button, with the text label reported as the dragged content.

None.

BBjColorChooser

The user can drag (copy) a color.

Accepts a color.

BBjFontChooser

The user can drag (copy) a font.

None.

BBjFileChooser

The user can select and drag (copy) file names from the list. This does not affect the files.

None.

BBjCEdit, BBjEditBox, BBjInputD, BBjInputE, BBjInputN, BBjListEdit

The user can drag selected text from a BBj text-based control using either the MOVE or COPY action. If the control is non-editable, the MOVE action is not allowed.

The user can drop text to an editable BBj text-based control using either the MOVE or COPY action. If the drag source was a non-editable BBj text control, the MOVE action is not allowed.

BBjEditBox (password)

For security reasons, text cannot be copied and dragged from password controls.

The user can drop text to an editable password BBjEditBox control using either the MOVE or COPY action. If the drag source was a non-editable BBj text control, the MOVE action is not allowed.

BBjHtmlView

The user can drag selected text from a BBjHtmlView control using either the MOVE or COPY action. Data is transferred in both "text/plain" and "text/html" formats.

None.

BBjListBox

The user can select and drag row(s) from the list. Data is transferred in both "text/plain" and "text/html" formats.

None.

BBjTree

The user can select and drag node(s) from the tree. Data is transferred in both "text/plain" and "text/html" formats.

None.

BBjGrid

For backward compatibility, BBjGrid default drag/drop support is controlled by Set Drag Accept - GRID SENDMSG() Function 33 BBj.

Programmable Behavior

BBj 7.0 adds two event callbacks that change the drop behavior from automatic to developer-defined. The first of these event callbacks, ON_DROP_TARGET_DROP, is registered on a potential drop target:

myControl!.setCallback(sysgui!.ON_DROP_TARGET_DROP,"DropTargetDrop")

If a BBjControl implements this callback, a drop to the control does not change it directly, but instead fires a BBjDropTargetDropEvent. This event returns detailed information about the drop request to the application. The developer can examine the dropped data and determine how it should be processed.

The second callback, ON_DRAG_SOURCE_DROP, is registered on a potential drag source:

myControl!.setCallback(sysgui!.ON_DRAG_SOURCE_DROP,"DragSourceDrop")

When a drag/drop operation is completed, either successfully or unsuccessfully, a BBjDragSourceDropEvent is sent to original drag source control.

BBjDropTargetDropEvent

The BBjDropTargetDropEvent is delivered to the drop target. See example.

 

Returns

Method

Notes

 

BBjControl

getDragSource()

Returns a reference to the original drag source if the data was dragged from a BBjControl within the current BBjServices session. Returns null if the data was dragged from an external source (e.g. a word processor) or from a different BBjServices session.

BBjVector of Integers

getSelection()

Returns selection information from the drag source:

Drag Source Selection

BBjCEdit

Six Integers: The start offset and the end offset of the original selection, followed by four Integers in the same format as BBjCEdit::getSelection.

BBjEditBox, BBjInputD, BBjInputE, BBjInputN, BBjListEdit

Two Integers: The start offset and the end offset of the original selection.

BBjListBox

A list of selected rows (Integers) in the same format as BBjListBox::getSelectedIndices

BBjTree

A list of selected Node IDs (Integers).

BBjGrid

A list of selected cells, in groups of two (row, column, row, column, etc.), all Integers.

HashMap

getData()

Returns the dragged data, typically in multiple formats. The key is a MIME string that describes the data format. BBj 7.0 supports the MIME types "text/plain" and "text/html".

object

getData(String key$)

Equivalent to getData().get(key$).

BBjVector of Integers

getDropLocation

Returns the point at which the data was dropped within the drop target:

Drop Target Drop Location

BBjCEdit

Three Integers: The zero-based offset, the zero-based paragraph number and offset within the paragraph.

BBjEditBox, BBjInputD, BBjInputE, BBjInputN, BBjListEdit

One Integer: The zero-based offset.

BBjListBox

One Integer: The zero-based row number.

BBjTree

One Integer: Node ID.

BBjGrid

Two Integers: Row and column.

Other (e.g.BBjWindow) in BBj 16.0 and higher.

Two Integers: X and Y point location of the drop.

int

getAction()

Returns one of the following actions:

ACTION_NONE 

ACTION_COPY 

ACTION_MOVE 

ACTION_LINK 

If the drag source was a text component and the action was ACTION_MOVE, the text has already been removed from the source control.

string

getType()

This is an application-defined string that can be used to describe the semantic meaning of the data. If the drag source was a BBjControl, this returns the drag type string from that control. If the drag source was a BBjTree or BBjGrid, this may return a type string from a particular tree node, grid column, or grid cell.

BBjDragSourceDropEvent

The BBjDragSourceDropEvent is delivered to the drag source. See example.

Returns

Method

Remarks

int

getAction()

Returns one of the following actions:

ACTION_NONE 

ACTION_COPY 

ACTION_MOVE 

ACTION_LINK 

If the drag source was a text component and the action was ACTION_MOVE, the text has already been deleted from the source control.

boolean

getSuccess()

Indicates whether the drop was successful.

Drag/Drop Actions

Actions are specified as one or more of ACTION_COPY, ACTION_MOVE, and ACTION_LINK. These values are additive; ACTION_COPY+ACTION_MOVE (which can be specified as ACTION_COPY_OR_MOVE) indicates that both the COPY and MOVE actions are supported. See example.

Returns

Method

Remarks

void

setDragActions(int action)

Sets the actions that will be available to potential drop targets when this control acts as a drag source.

int

getDragActions()

Returns the currently supported actions when dragging from this control. If the control is disabled or non-editable, the MOVE action will be unavailable.

void

setDropActions(int action)

Sets the actions that will be allowed when this control acts as a drop target.

int

getDropActions()

Returns the currently supported actions when dropping to this control. Returns ACTION_NONE if the control is disabled or non-editable.

Drag/Drop Types

Drag/drop types are strings that can be used to indicate the semantic meaning of a control or a portion of a control (a tree node, or a grid column or cell. These strings can be used to control whether a particular drag/drop should be accepted. See example.

 

Returns

Method

Remarks

void

setDragType(string type)

When this control acts as a drag source, this is the type that it advertises to potential drop targets.

string

getDragType()

void

setDropTypes(BBjVector types)

When this control acts as a drop target, these are the types that it is willing to accept from another drag source. If DropTypes is not set, the control is willing to accept data of any type.

BBjVector of strings

getDropTypes()

BBjTree

Returns

Method

Remarks

void

setDragType(int nodeID, string type)

Sets the drag type for a tree node.

string

getDragType(int nodeID)

void

setDropTypes(int nodeID, BBjVector types)

Sets drop types for a tree node.

BBjVector of strings

getDropTypes(int nodeID)

BBjGrid

Returns

Method

Remarks

void

setDragType(int column, string type)

Sets the drag type for a grid column.

string

getDragType(int column)

void

setDropTypes(int column, BBjVector types)

Sets drop types for a grid column.

BBjVector of strings

getDropTypes(int column)

void

setDragType(int row, int column, string type)

Sets the drag type for a grid cell.

string

getDragType(int row, int column)

void

setDropTypes(int row, int column, BBjVector types)

Sets drop types for a grid cell.

BBjVector of strings

getDropTypes(int row, int column)

User Interface Features

As the user drags over a BBjControl, the control indicates where the data would be dropped by showing a text cursor, outlining a grid cell or listbox row, or underlining a tree node. The mouse cursor indicates what action, if any, would take place if the data were dropped. The cursors (and the modifier keys for choosing a different action) are platform-defined.

Microsoft Windows

Action

Cursor

Remarks

ACTION_MOVE

dragmove.png

The user can indicate a preference for the MOVE action by pressing SHIFT while dragging.

ACTION_COPY

dragcopy.png

The user can indicate a preference for the COPY action by pressing CTRL while dragging. In macOS, press Action (Alt) while dragging to select the COPY action.

ACTION_LINK

draglink.png

The user can indicate a preference for the LINK action by pressing CTRL+SHIFT while dragging.

ACTION_NONE

dragnone.png

This cursor indicates that the drop would not be accepted at the current location.

 

When dragging over a control that supports scrolling, the control scrolls as necessary to enable the user to drop to a point that is not initially visible. Hovering over a BBjTree node for a second causes it to expand automatically. This enables the user to drop to a node that is not initially visible.