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.

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		The user can indicate a preference for the MOVE action by pressing SHIFT while dragging.
ACTION_COPY		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		The user can indicate a preference for the LINK action by pressing CTRL+SHIFT while dragging.
ACTION_NONE		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.