PhInitDrag()

Initiate a drag operation

Synopsis:

int PhInitDrag(
       PhRid_t rid,
       unsigned flags,
       const PhRect_t *rect,
       const PhRect_t *boundary,
       unsigned int input_group,
       const PhDim_t *min,
       const PhDim_t *max,
       const PhDim_t *step,
       const PhPoint_t *ptrpos,
       const PhCursorDescription_t *cursor );

Arguments:

rid
A PhRid_t that specifies the region that initiates the drag.
flags
Determines how the drag operation behaves. Defined values:
Ph_TRACK_LEFT
Left edge of drag rectangle tracks pointer.
Ph_TRACK_RIGHT
Right edge of drag rectangle tracks pointer.
Ph_TRACK_TOP
Top edge of drag rectangle tracks pointer.
Ph_TRACK_BOTTOM
Bottom edge of drag rectangle tracks pointer.
Ph_TRACK_DRAG
All edges of drag rectangle track pointer.
Ph_DRAG_TRACK
Emit drag events to track the drag, but don't rubber-band.
Ph_DRAG_KEY_MOTION
Emit Ph_EV_KEY, Ph_EV_PTR_MOTION_BUTTON and Ph_EV_PTR_MOTION_NOBUTTON events with the Ph_EV_DRAG subtype during the drag. These events are normally suppressed during a drag.
Ph_DRAG_NOBUTTON
Start the drag even if no buttons are held down.
rect
A pointer to a PhRect_t structure that defines the rectangle to be dragged (or “rubber-banded”) on screen. The boundary represents a rectangular constraint area beyond which the edges of rect may not extend. The coordinates in rect are relative to the origin of the region that initiates the drag, specified by rid.
boundary
A pointer to a PhRect_t structure that defines a rectangular constraint area for rect. The edges of the rectangle may not exceed this area. The coordinates in boundary are relative to the origin of the region that initiates the drag, specified by rid.
input_group
You should set the input_group argument to the the input-group value supplied with the event in cbinfo (see example).
min
A pointer to a PhDim_t structure that defines the minimum size for the drag rectangle returned in the drag events. (The application receives the events in absolute coordinates.)
max
A pointer to a PhDim_t structure that defines the maximum size for the drag rectangle returned in the drag events. (The application receives the events in absolute coordinates.)
step
A pointer to a PhDim_t structure that defines the drag granularity. This structure's width (w) and height (h) members indicate the distance a dragged object moves between drag events.
ptrpos
A pointer to a PhPoint_t structure that defines the initial cursor position for the drag. Applications should take it from the event that makes them decide to start a drag. If the cursor moves from that position by the time your PhInitDrag() reaches Photon, your drag is updated accordingly.

In other words:

cursor
A pointer to a PhCursorDescription_t structure. This is the header member of either a PhCharacterCursorDescription_t or PhBitmapCursorDescription_t that defines how the cursor should look while dragging. This member may be NULL.

Library:

ph

Description:

This function starts a drag. Normally, when the drag has completed, the application collects a Ph_EV_DRAG event that describes the results of the operation. But if the application closes the region that has initiated the drag operation, the operation completes without returning a Ph_EV_DRAG event.

Any attempt to initiate a drag operation while another is in progress in the same input group fails.

You can cancel a drag operation with PhCancelDrag().

Returns:

0
Successful completion.
-1
An error occurred.

Examples:

drag_lower_left( PhRect_t *rect, PhRect_t *boundary,
                 PtCallbackInfo_t *cbinfo )
{
   PhEvent_t *event = cbinfo->event;
   PhPointerEvent_t *ptrev = PhGetData( event );
   static const PhCharacterCursorDescription_t
       cursor = { { Ph_CURSOR_DRAG_BL, sizeof(cursor) }, Pg_RED };

   PhInitDrag( my_region, Ph_TRACK_LEFT | Ph_TRACK_BOTTOM,
               rect, boundary, event->input_group,
               NULL, NULL, NULL, &ptrev->pos, &cursor.hdr );
}


raw_callback( PtWidget_t *widget, void *data,
              PtCallbackInfo_t *cbinfo)
{
    PhRect_t *rect;
    PhDragEvent_t *drag;
...

   switch( cbinfo->event->type )
   {
       case Ph_EV_DRAG:
           drag = (PhDragEvent_t *)PhGetData( cbinfo->event );
           rect = &drag->rect;
           // drag rectangle in ABSOLUTE coordinates.
           PhTranslateRect( rect,
                            &cbinfo->event->translation );
           // rect is now relative to the region the drag
           // was initiated on.
           ...
   }
   ...
}

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PhBitmapCursorDescription_t, PhCharacterCursorDescription_t, PhCancelDrag(), PhDragEvent_t, PhEvent_t, PhGetData(), PhDim_t, PhPoint_t, PhRect_t, PhTranslateRect()

Dragging in the Events chapter of the Photon Programmer's Guide