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:

• Photon “virtually” moves the cursor back to the location indicated by ptrpos, then starts the drag, and then “virtually” drags the cursor back to where it really is.

  Or:

• Photon makes the drag behave as if it started from where you thought the cursor was rather than from where Photon thought it was a few moments later.

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

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