callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DND updates

Browse Source 
Wed Nov 29 13:39:19 GMT 2000  Tony Gale <gale@gtk.org>

	* docs/tutorial/gtk-tut.sgml: DND updates
This commit is contained in:
GMT 2000 Tony Gale
2000-11-29 13:41:51 +00:00
committed by Tony Gale
parent 92bc6d4175
commit 696d0bc1b0
8 changed files with 110 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/tutorial/gtk-tut.sgml
View File

@ -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>