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 );

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.

The flags argument 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.

The rect argument points to a PhRect_t structure that defines rectangle to be dragged (or "rubber-banded") on screen, and boundary represents a rectangular constraint area. The edges of the rectangle may not exceed this area. The coordinates in rect and boundary are relative to the origin of the region that initiates the drag; this region is specified by rid.

The min and max arguments point to PhDim_t structures that define the minimum and maximum size for the drag rectangle returned in the drag events. (The application receives the events in absolute coordinates.) The step argument's width (w) and height (h) members indicate the drag granularity.

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

You should set the input_group argument to the the input-group value supplied with the event in cbinfo (see example).

The ptrpos argument, if not NULL, points 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.

The cursor argument, if not NULL, defines how the cursor should look while dragging.

Returns:

0: Successful completion.
-1: An error occurred.

Examples:

drag_lower_left( PhRect_t *rect, PhRect_t *boundary, 
                 PtCallbackInfo_t *cbinfo )
{
   PhInitDrag( my_region, Ph_TRACK_LEFT | Ph_TRACK_BOTTOM,
               rect, boundary,
               cbinfo->event->input_group, 
               NULL, NULL, NULL, NULL, NULL );
}

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

PhInitDrag()

Synopsis:

Library:

Description:

Returns:

Examples:

Classification:

See also: