|
|
|
|
@ -12778,24 +12778,25 @@ int main( int argc,
|
|
|
|
|
|
|
|
|
|
<!-- ***************************************************************** -->
|
|
|
|
|
<chapter id="ch-DragAngDrop">
|
|
|
|
|
<title>Drag and Drop (DND)</title>
|
|
|
|
|
<title>Drag-and-drop (DND)</title>
|
|
|
|
|
|
|
|
|
|
<para>GTK+ has a high level set of functions for doing inter-window
|
|
|
|
|
communication using the drag and drop system on top of the low level
|
|
|
|
|
Xdnd and Motif protocols.</para>
|
|
|
|
|
<para>GTK+ has a high level set of functions for doing inter-process
|
|
|
|
|
communication via the drag-and-drop system. GTK+ can perform
|
|
|
|
|
drag-and-drop on top of the low level Xdnd and Motif drag-and-drop
|
|
|
|
|
protocols.</para>
|
|
|
|
|
|
|
|
|
|
<!-- ----------------------------------------------------------------- -->
|
|
|
|
|
<sect1 id="sec-DragAndDropOverview">
|
|
|
|
|
<title>Overview</title>
|
|
|
|
|
|
|
|
|
|
<para>An application capable of GTK+ drag and drop first defines and sets up
|
|
|
|
|
the GTK+ widget(s) for drag and drop. Each widget can be a source
|
|
|
|
|
and/or destination for drag and drop. Note that these GTK+ widgets must have
|
|
|
|
|
an associated X Window, check using GTK_WIDGET_NO_WINDOW(wid)).</para>
|
|
|
|
|
<para>An application capable of GTK+ drag-and-drop first defines and sets up
|
|
|
|
|
the GTK+ widget(s) for drag-and-drop. Each widget can be a source
|
|
|
|
|
and/or destination for drag-and-drop. Note that these GTK+ widgets must have
|
|
|
|
|
an associated X Window, check using GTK_WIDGET_NO_WINDOW(widget)).</para>
|
|
|
|
|
|
|
|
|
|
<para>Source widgets can send out drag data, thus allowing the user to drag
|
|
|
|
|
things off of them, while destination widgets can receive drag data.
|
|
|
|
|
Drag and drop destinations can limit who they accept drag data from,
|
|
|
|
|
Drag-and-drop destinations can limit who they accept drag data from,
|
|
|
|
|
e.g. the same application or any application (including itself).</para>
|
|
|
|
|
|
|
|
|
|
<para>Sending and receiving drop data makes use of GTK+ signals.
|
|
|
|
|
@ -12803,7 +12804,7 @@ Dropping an item to a destination widget requires both a data
|
|
|
|
|
request (for the source widget) and data received signal handler (for
|
|
|
|
|
the target widget). Additional signal handers can be connected if you
|
|
|
|
|
want to know when a drag begins (at the very instant it starts), to
|
|
|
|
|
when a drop is made, and when the entire drag and drop procedure has
|
|
|
|
|
when a drop is made, and when the entire drag-and-drop procedure has
|
|
|
|
|
ended (successfully or not).</para>
|
|
|
|
|
|
|
|
|
|
<para>Your application will need to provide data for source widgets when
|
|
|
|
|
@ -12811,7 +12812,7 @@ requested, that involves having a drag data request signal handler. For
|
|
|
|
|
destination widgets they will need a drop data received signal
|
|
|
|
|
handler. </para>
|
|
|
|
|
|
|
|
|
|
<para>So a typical drag and drop cycle would look as follows:</para>
|
|
|
|
|
<para>So a typical drag-and-drop cycle would look as follows:</para>
|
|
|
|
|
<orderedlist>
|
|
|
|
|
<listitem><simpara> Drag begins.</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
@ -12822,7 +12823,7 @@ application).</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara> Drag data delete (if the drag was a move).</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara> Drag and drop procedure done.</simpara>
|
|
|
|
|
<listitem><simpara> Drag-and-drop procedure done.</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
</orderedlist>
|
|
|
|
|
|
|
|
|
|
@ -12841,8 +12842,7 @@ will get into detail about that later.</para>
|
|
|
|
|
<listitem><simpara> Drag action type (ie GDK_ACTION_COPY, GDK_ACTION_MOVE).</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><simpara> Client specified arbitrary drag and drop type (a
|
|
|
|
|
gchar *name and a gint info id number pair).</simpara>
|
|
|
|
|
<listitem><simpara> Client specified arbitrary drag-and-drop type (a name and number pair).</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
|
|
<listitem><simpara> Sent and received data format type.</simpara>
|
|
|
|
|
@ -12851,17 +12851,17 @@ gchar *name and a gint info id number pair).</simpara>
|
|
|
|
|
|
|
|
|
|
<para>Drag actions are quite obvious, they specify if the widget can
|
|
|
|
|
drag with the specified action(s), e.g. GDK_ACTION_COPY and/or
|
|
|
|
|
GDK_ACTION_MOVE. A GDK_ACTION_COPY would be a typical drag and drop
|
|
|
|
|
GDK_ACTION_MOVE. A GDK_ACTION_COPY would be a typical drag-and-drop
|
|
|
|
|
without the source data being deleted while GDK_ACTION_MOVE would be
|
|
|
|
|
just like GDK_ACTION_COPY but the source data will be 'suggested' to be
|
|
|
|
|
deleted after the received signal handler is called. There are
|
|
|
|
|
additional drag actions including GDK_ACTION_LINK which you may want to
|
|
|
|
|
look into when you get to more advanced levels of drag and drop.</para>
|
|
|
|
|
look into when you get to more advanced levels of drag-and-drop.</para>
|
|
|
|
|
|
|
|
|
|
<para>The client specified arbitrary drag and drop type is much more
|
|
|
|
|
<para>The client specified arbitrary drag-and-drop type is much more
|
|
|
|
|
flexible, because your application will be defining and checking for
|
|
|
|
|
that specifically. You will need to set up your destination widgets to
|
|
|
|
|
receive certain drag and drop types by specifying a name and/or number.
|
|
|
|
|
receive certain drag-and-drop types by specifying a name and/or number.
|
|
|
|
|
It would be more reliable to use a name since another application may
|
|
|
|
|
just happen to use the same number for an entirely different
|
|
|
|
|
meaning.</para>
|
|
|
|
|
@ -12884,18 +12884,66 @@ received.</para>
|
|
|
|
|
<sect1 id="sec-DragAndDropFunctions">
|
|
|
|
|
<title>Functions</title>
|
|
|
|
|
|
|
|
|
|
<para>Setting up source widget:</para>
|
|
|
|
|
<sect2 id="sec-DNDSourceWidgets">
|
|
|
|
|
<title>Setting up the source widget</title>
|
|
|
|
|
|
|
|
|
|
<para>The function <literal>gtk_drag_source_set()</literal> specifies a
|
|
|
|
|
set of target types for a drag operation on a widget.</para>
|
|
|
|
|
|
|
|
|
|
<programlisting role="C">
|
|
|
|
|
void gtk_drag_source_set( GtkWidget *widget,
|
|
|
|
|
GdkModifierType start_button_mask,
|
|
|
|
|
const GtkTargetEntry *targets,
|
|
|
|
|
gint n_targets,
|
|
|
|
|
GdkDragAction actions );
|
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
|
|
<para>The parameters signify the following:</para>
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><simpara> <literal>gtk_drag_source_set()</literal> specifies a
|
|
|
|
|
set of target types for a drag operation on a widget.</simpara>
|
|
|
|
|
<listitem><simpara><literal>widget</literal> specifies the drag source
|
|
|
|
|
widget</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara><literal>start_button_mask</literal> specifies a
|
|
|
|
|
bitmask of buttons that can start the drag (e.g. GDK_BUTTON1_MASK)</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara><literal>targets</literal> specifies a table of
|
|
|
|
|
target data types the drag will support</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara><literal>n_targets</literal> specifies the number of
|
|
|
|
|
targets above</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara><literal>actions</literal> specifies a bitmask of
|
|
|
|
|
possible actions for a drag from this window</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
<listitem><simpara> <literal>gtk_drag_source_unset()</literal> specifies
|
|
|
|
|
that the widget is to no longer perform drag operations.</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
|
|
<para>Signals on the source widget:</para>
|
|
|
|
|
<para>The <literal>targets</literal> parameter is an array of the
|
|
|
|
|
following structure:</para>
|
|
|
|
|
|
|
|
|
|
<programlisting role="C">
|
|
|
|
|
struct GtkTargetEntry {
|
|
|
|
|
gchar *target;
|
|
|
|
|
guint flags;
|
|
|
|
|
guint info;
|
|
|
|
|
};
|
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
|
|
<para>The fields specify a string representing the drag type, optional
|
|
|
|
|
flags and application assigned integer identifier.</para>
|
|
|
|
|
|
|
|
|
|
<para>If a widget is no longer required to act as a source for
|
|
|
|
|
drag-and-drop operations, the function
|
|
|
|
|
<literal>gtk_drag_source_unset()</literal> can be used to remove a set
|
|
|
|
|
of drag-and-drop target types.</para>
|
|
|
|
|
|
|
|
|
|
<programlisting role="C">
|
|
|
|
|
void gtk_drag_source_unset( GtkWidget *widget );
|
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
<sect2 id="sec-SignalsOnSourceWidgets">
|
|
|
|
|
<title>Signals on the source widget:</title>
|
|
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><simpara> drag_begin - prototype: void (*drag_begin)(GtkWidget
|
|
|
|
|
@ -12922,7 +12970,10 @@ that the widget is to no longer perform drag operations.</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
|
|
<para>Setting up destination widget:</para>
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
<sect2 id="sec-DNDDestWidgets">
|
|
|
|
|
<title>Setting up a destination widget:</title>
|
|
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><simpara> <literal> gtk_drag_dest_set()</literal> specifies
|
|
|
|
|
@ -12935,7 +12986,10 @@ that the widget can no longer recieve drops.</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
|
|
<para>Signals on the destination widget:</para>
|
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
|
|
<sect2 id="sec-SignalsOnDestWidgets">
|
|
|
|
|
<title>Signals on the destination widget:</title>
|
|
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
|
<listitem><simpara> drag_data_received - prototype: void (*drag_data_received)(GtkWidget *widget, GdkDragContext
|
|
|
|
|
@ -12943,6 +12997,7 @@ that the widget can no longer recieve drops.</simpara>
|
|
|
|
|
</listitem>
|
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
|
|
</sect2>
|
|
|
|
|
</sect1>
|
|
|
|
|
</chapter>
|
|
|
|
|
|
|
|
|
|
|
GMT 2000 Tony Gale