PtInitDnd()

Initiate a drag-and-drop operation

Synopsis:

int PtInitDnd( PtTransportCtrl_t *ctrl,
               PtWidget_t *widget,
               PhEvent_t *event,
               PhDndCursors_t *cursors,
               int unsigned flags );

Arguments:

ctrl

A pointer to a PtTransportCtrl_t structure which contains the data that the function uses to initiate a drag-and-drop operation.

widget

A pointer to a PtWidget_t sturcture which specifies the widget on whose behalf the drag-and-drop operation is being started. It's this widget that receives all drag-and-drop progress-notification events and callbacks.

event

A pointer to a PhEvent_t structure that describes the event that was used to precipitate the operation. This may be a pointer event (Ph_EV_PTR_MOTION_*) or drag event (Ph_EV_DRAG). If the event isn't of one of these types, the function will fail.

---

If the drag event's subtype isn't Ph_EV_DRAG_COMPLETE, you'll have to cancel the drag first, using PhCancelDrag().

---

cursors

A pointer to a PhDndCursors_t structure which, if provided, is used instead of the default drag-and-drop cursors (accept, reject, unknown... app not responding) if the destination doesn't override them.

PhDndCursors_t contains three members, all pointers to PhCursorDescription_t, which describe the cursor's appearance when performing a drag-and-drop operation:

typedef struct Ph_ev_dndrop_cursors {
    const PhCursorDescription_t *active, *inactive, *unknown;
} PhDndCursors_t;

• active — NULL or a cursor to display over a region that has declared that it wants the drop (and hasn't provided a different cursor).
• inactive — NULL or a cursor to display over a region that has declared that it doesn't want the drop (and hasn't provided a different cursor).
• unknown — NULL or a cursor to display over a region while we're still waiting for a response from it.

flags

A combination of the following bits:

Pt_DND_SILENT

Don't notify the initiator of drag-and-drop progress (valid only if no requestable data types were added to the PtTransportCtrl_t structure).

Pt_DND_LOCAL

Restrict the drop so that it can occur only within the context of the application that initiated the drag-and-drop. That is to say that the user can't drop the data on any other application. This is very useful for allowing the dragging and dropping of private data or pointer references that are meaningful only within a single application's context.

Library:

ph

Description:

This function initiates a drag-and-drop operation with the data previously added to the PtTransportCtrl_t structure pointed to by ctrl. Before calling PtInitDnd(), your application must create this structure by calling PtCreateTransportCtrl() and populate it via calls to PtTransportType() and PtTransportRequestable().

The structure pointed to by ctrl is automatically released at the end of the drag-and-drop operation.

Returns:

0

Success.

-1

An error occurred.

Examples:

int cb_outbound (PtWidget_t *widget, void *data,
                 PtCallbackInfo_t *cbinfo);
{
    PtTransportCtrl_t *tctrl = PtCreateTransportCtrl();
    PtTransportType( tctrl, "text", "simple sentence",
                     0, Ph_TRANSPORT_INLINE, "string",
                     "This is my inlined data.", 0, 0 );
    PtInitDnd( tctrl, widget, cbinfo->event, NULL,
               Pt_DND_LOCAL | Pt_DND_SILENT );
    return Pt_CONTINUE;
}

Classification:

Photon

See also:

PhCursorDescription_t, PhCancelDrag(), PhEvent_t, PtCancelDnd(), PtCreateTransportCtrl(), PtDndFetch_t, PtDndSelect(), PtTransportCtrl_t, PtTransportType()

Drag and Drop chapter of the Photon Programmer's Guide