Drag

Description

Starts or ends the dragging of a control.

Applies to

All controls except drawing objects (Lines, Ovals, Rectangles, and Rounded Rectangles)

Syntax

control.Drag ( dragmode )

Argument

Description

control

The name of the control you want to drag or stop dragging

dragmode

A value of the DragMode datatype indicating the action you want to take on control:

  • Begin! -- Put control in drag mode

  • Cancel! -- Stop dragging control but do not cause a DragDrop event

  • End! -- Stop dragging control and if control is over a target object, cause a DragDrop event


Return value

Integer.

For all controls except OLE controls, returns 1 if it succeeds and -1 if you try to nest drag events or try to cancel the drag when control is not in drag mode. The return value is usually not used.

For OLE controls, returns the following values:

2 -- Object was moved

1 -- Drag was canceled

0 -- Drag succeeded

-1 -- Control is empty

-9 -- Unspecified error

If any argument's value is null, Drag returns null.

Usage

To see the list of draggable controls, open the Browser. All the objects in the hierarchy below dragobject are draggable.

If you set the control's DragAuto property to true, PowerBuilder automatically puts the control in drag mode when the user clicks it. The user must hold the mouse button down to drag.

When you use Drag(Begin!) in a control's Clicked event to manually put the control in drag mode, the user can drag the control by moving the mouse without holding down the mouse button. Clicking the left mouse button ends the drag. CANCEL! and END! are required only if you want to end the drag without requiring the user to click the left mouse button.

Dragging DataWindow controls

The Clicked event of a DataWindow control occurs when the user presses the mouse button, not when the mouse button is released. If you place Drag(Begin!) in a DataWindow control's Clicked event, releasing the mouse button ends the drag. To achieve the same behavior as with other controls, define a user-defined event for the DataWindow control called lbuttonup and map it to the pbm_lbuttonup event ID. Then place the following code in the lbuttonup event script (ib_dragflag is a boolean instance variable):

IF NOT ib_dragflag THEN
   this.Drag(Begin!)
   ib_dragflag = TRUE
ELSE
   ib_dragflag = FALSE
END IF

To make something happen when the user drags a control onto a target object, write scripts for one or more of the target's drag events (DragDrop, DragEnter, DragLeave, and DragWithin).

Examples

This statement puts sle_emp into drag mode:

sle_emp.Drag(Begin!)

See also

DraggedObject (obsolete)