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

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.

The flags argument determines how the drag operation will behave. 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 represents a 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 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 will fail.

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

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

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.
           PtTranslateRect( rect,
                            &cbinfo->event->translation );
           // rect is now relative to the region the drag
           // was initiated on.
           ...
   }
   ...
}

Classification:

Photon

See also:

PhEvent_t, PhGetData(), PtTranslateRect()

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