gtk2/docs/reference/gdk/tmpl/selections.sgml

307 lines
7.6 KiB
Plaintext
Raw Normal View History

1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Title ##### -->
Selections
<!-- ##### SECTION Short_Description ##### -->
Functions for transfering data via the X selection mechanism
1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Long_Description ##### -->
<para>
The X selection mechanism provides a way to transfer
arbitrary chunks of data between programs.
A <firstterm>selection</firstterm> is a essentially
a named clipboard, identified by a string interned
as a #GdkAtom. By claiming ownership of a selection,
an application indicates that it will be responsible
for supplying its contents. The most common
selections are <literal>PRIMARY</literal> and
<literal>CLIPBOARD</literal>.
</para>
<para>
The contents of a selection can be represented in
a number of formats, called <firstterm>targets</firstterm>.
Each target is identified by an atom. A list of
all possible targets supported by the selection owner
can be retrieved by requesting the special target
<literal>TARGETS</literal>. When a selection is
retrieved, the data is accompanied by a type
(an atom), and a format (an integer, representing
the number of bits per item).
See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
for more information.
</para>
<para>
The functions in this section only contain the lowlevel
parts of the selection protocol. A considerably more
complicated implementation is needed on top of this.
GTK+ contains such an implementation in the functions
in <literal>gtkselection.h</literal> and programmers
should use those functions instead of the ones presented
here. If you plan to implement selection handling
directly on top of the functions here, you should refer
to the X Inter-client Communication Conventions Manual
(ICCCM).
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
2005-06-20 22:06:27 +00:00
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### TYPEDEF GdkSelection ##### -->
1999-08-16 18:51:52 +00:00
<para>
The #GdkSelection enumeration contains predefined
atom values for several common selections.
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### TYPEDEF GdkSelectionType ##### -->
1999-08-16 18:51:52 +00:00
<para>
The #GdkSelectionType enumeration contains predefined
atom values used to represent the types of data transferred
in response to a request for a target. See the
ICCCM for details about what data should be transferred
for each of these types. Other atoms can be used,
and the recommended practice for GTK+ is to to use mime
types for this purpose. However, supporting these types
may be useful for compatibility with older programs.
</para>
1999-08-16 18:51:52 +00:00
<!-- ##### TYPEDEF GdkTarget ##### -->
<para>
The #GdkTarget enumeration contains predefined atom values which are
used to describe possible targets for a selection. Other atoms can be
used, and the recommended practice for GTK+ is to to use mime types
for this purpose. However, supporting these types may be useful for
compatibility with older programs.
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### MACRO GDK_SELECTION_PRIMARY ##### -->
<para>
A #GdkAtom representing the <literal>PRIMARY</literal> selection.
</para>
<!-- ##### MACRO GDK_SELECTION_SECONDARY ##### -->
<para>
A #GdkAtom representing the <literal>SECONDARY</literal> selection.
</para>
<!-- ##### MACRO GDK_SELECTION_CLIPBOARD ##### -->
<para>
A #GdkAtom representing the <literal>CLIPBOARD</literal> selection.
</para>
<!-- ##### MACRO GDK_TARGET_BITMAP ##### -->
<para>
A #GdkAtom representing the <literal>BITMAP</literal> selection target.
</para>
<!-- ##### MACRO GDK_TARGET_COLORMAP ##### -->
<para>
A #GdkAtom representing the <literal>COLORMAP</literal> selection target.
</para>
<!-- ##### MACRO GDK_TARGET_DRAWABLE ##### -->
<para>
A #GdkAtom representing the <literal>DRAWABLE</literal> selection target.
</para>
<!-- ##### MACRO GDK_TARGET_PIXMAP ##### -->
<para>
A #GdkAtom representing the <literal>PIXMAP</literal> selection target.
</para>
<!-- ##### MACRO GDK_TARGET_STRING ##### -->
<para>
A #GdkAtom representing the <literal>STRING</literal> selection target.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_ATOM ##### -->
<para>
A #GdkAtom representing the <literal>ATOM</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_BITMAP ##### -->
<para>
A #GdkAtom representing the <literal>BITMAP</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_COLORMAP ##### -->
<para>
A #GdkAtom representing the <literal>COLORMAP</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_DRAWABLE ##### -->
<para>
A #GdkAtom representing the <literal>DRAWABLE</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_INTEGER ##### -->
<para>
A #GdkAtom representing the <literal>INTEGER</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_PIXMAP ##### -->
<para>
A #GdkAtom representing the <literal>PIXMAP</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_WINDOW ##### -->
<para>
A #GdkAtom representing the <literal>WINDOW</literal> selection type.
</para>
<!-- ##### MACRO GDK_SELECTION_TYPE_STRING ##### -->
<para>
A #GdkAtom representing the <literal>STRING</literal> selection type.
</para>
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
<para>
Sets the owner of the given selection.
1999-08-16 18:51:52 +00:00
</para>
@owner: a #GdkWindow or %NULL to indicate that the
the owner for the given should be unset.
@selection: an atom identifying a selection.
docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml Fri Nov 8 20:14:52 2002 Soeren Sandmann <sandmann@daimi.au.dk> * docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml docs/reference/gdk/tmpl/gdk-unused.sgml docs/reference/gdk/tmpl/gdkdisplay.sgml docs/reference/gdk/tmpl/general.sgml docs/reference/gdk/tmpl/input_devices.sgml docs/reference/gdk/tmpl/selections.sgml docs/reference/gtk/tmpl/gtkcellrenderer.sgml docs/reference/gtk/tmpl/gtkcurve.sgml docs/reference/gtk/tmpl/gtkdnd.sgml docs/reference/gtk/tmpl/gtkitemfactory.sgml docs/reference/gtk/tmpl/gtkmenu.sgml docs/reference/gtk/tmpl/gtkoldeditable.sgml docs/reference/gtk/tmpl/gtkoptionmenu.sgml docs/reference/gtk/tmpl/gtkpreview.sgml docs/reference/gtk/tmpl/gtkselection.sgml docs/reference/gtk/tmpl/gtksocket.sgml docs/reference/gtk/tmpl/gtkstyle.sgml docs/reference/gtk/tmpl/gtktextbuffer.sgml docs/reference/gtk/tmpl/gtktreemodel.sgml docs/reference/gtk/tmpl/gtkwidget.sgml gdk/gdk.h gdk/gdkdisplay.c gdk/gdkdisplay.h gdk/gdkdnd.h gdk/gdkdraw.c gdk/gdkdrawable.h gdk/gdkinput.h gdk/gdkselection.h gdk/x11/gdkdisplay-x11.c gdk/x11/gdkdnd-x11.c gdk/x11/gdkselection-x11.c gtk/gtkcurve.h gtk/gtkdnd.h gtk/gtkitemfactory.c gtk/gtkitemfactory.h gtk/gtkmenu.h gtk/gtkoldeditable.c gtk/gtkoldeditable.h gtk/gtkoptionmenu.h gtk/gtkplug.c gtk/gtkplug.h gtk/gtkpreview.h gtk/gtkrange.h gtk/gtkselection.c gtk/gtkselection.h gtk/gtksocket.c gtk/gtksocket.h gtk/gtkstyle.c gtk/gtkstyle.h gtk/gtktextlayout.c gtk/gtktextlayout.h gtk/gtktreemodel.c gtk/gtktreemodel.h gtk/gtkwidget.h Trivial s/foo/foo_/ fixes to make gtk.h includable with -Wshadow without warnings. (#91680)
2002-11-08 19:41:50 +00:00
@time_: timestamp to use when setting the selection.
If this is older than the timestamp given last
time the owner was set for the given selection, the
request will be ignored.
@send_event: if %TRUE, and the new owner is different
from the current owner, the current owner
will be sent a SelectionClear event.
@Returns: %TRUE if the selection owner was successfully
changed to @owner, otherwise %FALSE.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_owner_set_for_display ##### -->
<para>
</para>
@display:
@owner:
@selection:
docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml Fri Nov 8 20:14:52 2002 Soeren Sandmann <sandmann@daimi.au.dk> * docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml docs/reference/gdk/tmpl/gdk-unused.sgml docs/reference/gdk/tmpl/gdkdisplay.sgml docs/reference/gdk/tmpl/general.sgml docs/reference/gdk/tmpl/input_devices.sgml docs/reference/gdk/tmpl/selections.sgml docs/reference/gtk/tmpl/gtkcellrenderer.sgml docs/reference/gtk/tmpl/gtkcurve.sgml docs/reference/gtk/tmpl/gtkdnd.sgml docs/reference/gtk/tmpl/gtkitemfactory.sgml docs/reference/gtk/tmpl/gtkmenu.sgml docs/reference/gtk/tmpl/gtkoldeditable.sgml docs/reference/gtk/tmpl/gtkoptionmenu.sgml docs/reference/gtk/tmpl/gtkpreview.sgml docs/reference/gtk/tmpl/gtkselection.sgml docs/reference/gtk/tmpl/gtksocket.sgml docs/reference/gtk/tmpl/gtkstyle.sgml docs/reference/gtk/tmpl/gtktextbuffer.sgml docs/reference/gtk/tmpl/gtktreemodel.sgml docs/reference/gtk/tmpl/gtkwidget.sgml gdk/gdk.h gdk/gdkdisplay.c gdk/gdkdisplay.h gdk/gdkdnd.h gdk/gdkdraw.c gdk/gdkdrawable.h gdk/gdkinput.h gdk/gdkselection.h gdk/x11/gdkdisplay-x11.c gdk/x11/gdkdnd-x11.c gdk/x11/gdkselection-x11.c gtk/gtkcurve.h gtk/gtkdnd.h gtk/gtkitemfactory.c gtk/gtkitemfactory.h gtk/gtkmenu.h gtk/gtkoldeditable.c gtk/gtkoldeditable.h gtk/gtkoptionmenu.h gtk/gtkplug.c gtk/gtkplug.h gtk/gtkpreview.h gtk/gtkrange.h gtk/gtkselection.c gtk/gtkselection.h gtk/gtksocket.c gtk/gtksocket.h gtk/gtkstyle.c gtk/gtkstyle.h gtk/gtktextlayout.c gtk/gtktextlayout.h gtk/gtktreemodel.c gtk/gtktreemodel.h gtk/gtkwidget.h Trivial s/foo/foo_/ fixes to make gtk.h includable with -Wshadow without warnings. (#91680)
2002-11-08 19:41:50 +00:00
@time_:
@send_event:
@Returns:
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_owner_get ##### -->
<para>
Determines the owner of the given selection.
1999-08-16 18:51:52 +00:00
</para>
@selection: an atom indentifying a selection.
@Returns: if there is a selection owner for this window,
and it is a window known to the current process,
the #GdkWindow that owns the selection, otherwise
%NULL. Note that the return value may be owned
by a different process if a foreign window
was previously created for that window, but
a new foreign window will never be created by
this call.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_owner_get_for_display ##### -->
<para>
</para>
@display:
@selection:
@Returns:
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_convert ##### -->
<para>
Retrieves the contents of a selection in a given
form.
1999-08-16 18:51:52 +00:00
</para>
@requestor: a #GdkWindow.
@selection: an atom identifying the selection to get the
contents of.
@target: the form in which to retrieve the selection.
docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml Fri Nov 8 20:14:52 2002 Soeren Sandmann <sandmann@daimi.au.dk> * docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml docs/reference/gdk/tmpl/gdk-unused.sgml docs/reference/gdk/tmpl/gdkdisplay.sgml docs/reference/gdk/tmpl/general.sgml docs/reference/gdk/tmpl/input_devices.sgml docs/reference/gdk/tmpl/selections.sgml docs/reference/gtk/tmpl/gtkcellrenderer.sgml docs/reference/gtk/tmpl/gtkcurve.sgml docs/reference/gtk/tmpl/gtkdnd.sgml docs/reference/gtk/tmpl/gtkitemfactory.sgml docs/reference/gtk/tmpl/gtkmenu.sgml docs/reference/gtk/tmpl/gtkoldeditable.sgml docs/reference/gtk/tmpl/gtkoptionmenu.sgml docs/reference/gtk/tmpl/gtkpreview.sgml docs/reference/gtk/tmpl/gtkselection.sgml docs/reference/gtk/tmpl/gtksocket.sgml docs/reference/gtk/tmpl/gtkstyle.sgml docs/reference/gtk/tmpl/gtktextbuffer.sgml docs/reference/gtk/tmpl/gtktreemodel.sgml docs/reference/gtk/tmpl/gtkwidget.sgml gdk/gdk.h gdk/gdkdisplay.c gdk/gdkdisplay.h gdk/gdkdnd.h gdk/gdkdraw.c gdk/gdkdrawable.h gdk/gdkinput.h gdk/gdkselection.h gdk/x11/gdkdisplay-x11.c gdk/x11/gdkdnd-x11.c gdk/x11/gdkselection-x11.c gtk/gtkcurve.h gtk/gtkdnd.h gtk/gtkitemfactory.c gtk/gtkitemfactory.h gtk/gtkmenu.h gtk/gtkoldeditable.c gtk/gtkoldeditable.h gtk/gtkoptionmenu.h gtk/gtkplug.c gtk/gtkplug.h gtk/gtkpreview.h gtk/gtkrange.h gtk/gtkselection.c gtk/gtkselection.h gtk/gtksocket.c gtk/gtksocket.h gtk/gtkstyle.c gtk/gtkstyle.h gtk/gtktextlayout.c gtk/gtktextlayout.h gtk/gtktreemodel.c gtk/gtktreemodel.h gtk/gtkwidget.h Trivial s/foo/foo_/ fixes to make gtk.h includable with -Wshadow without warnings. (#91680)
2002-11-08 19:41:50 +00:00
@time_: the timestamp to use when retrieving the
selection. The selection owner may refuse the
request if it did not own the selection at
the time indicated by the timestamp.
1999-08-16 18:51:52 +00:00
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_property_get ##### -->
<para>
</para>
Start implementing display/screen closing scheme; keep a flag for whether Thu Aug 1 11:26:03 2002 Owen Taylor <otaylor@redhat.com> * gdk/gdkdisplay.[ch] gdk/gdkscreen.[ch] gdkinternals.h: Start implementing display/screen closing scheme; keep a flag for whether displays and screens are closed, call g_object_run_dispose(). Remove public gdk_screen_close(). * gdk/x11/gdkdisplay-x11.c gdk/x11/gdkscreen-x11.c: Add dispose() methods; move appropriate parts of the finalize there. * gdk/x11/gdkcolor-x11.c gdk/x11/gdkimage-x11.c gdk/x11/gdkmain-x11.c gdk/x11/gdkpango-x11.c gdk/x11/gdkpixmap-x11.c gdk/x11/gdkproperty-x11.c gdk/x11/gdkselection-x11.c gdk/x11/gdkwindow-x11.c: Start of making everything correctly ignore operations when a display has been closed. * gdk/x11/gdkwindow-x11.c (gdk_window_get_decorations): Handle decorations == NULL. * gdk/x11/gdkcolor-x11.c (gdk_colormap_remove): Remove unnecessary hash table creation. * gdk/x11/gdkinput.c gdk/x11/gdkinput-x11.c gdk/win32/gdkinput.c Fix up gdk_device_get_history - handle events, n_events == NULL, etc. * gdk/x11/gdkproperty-x11.c (gdk_property_get): Handle failure better. * gdk/x11/gdkselection-x11.c (gdk_selection_property_get): Handle failure better, handle data == NULL, move docs here, remove an excess round trip by asking for all selection data at once. * gdk/gdkselection.c gdk/win32/{x11,win32}/gdkselection-{x11,win32}.c gdk/{x11,win32}/gdkmain-{x11,win32}.c gdk/gdkdisplay.c: Move gdk_text_property_to_text_list(), gdk_string_to_compound_text(), gdk_display_set_sm_client_id() to display-independent part of GDK. * gdk/Makefile.am (gdk_c_sources): Sort gdkdisplay/screen.[ch] into the right place.
2002-08-01 15:28:40 +00:00
@requestor:
@data:
@prop_type:
@prop_format:
@Returns:
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_send_notify ##### -->
<para>
Sends a response to SelectionRequest event.
1999-08-16 18:51:52 +00:00
</para>
@requestor: window to which to deliver response.
@selection: selection that was requested.
@target: target that was selected.
@property: property in which the selection owner stored the
data, or %GDK_NONE to indicate that the request
was rejected.
docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml Fri Nov 8 20:14:52 2002 Soeren Sandmann <sandmann@daimi.au.dk> * docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml docs/reference/gdk/tmpl/gdk-unused.sgml docs/reference/gdk/tmpl/gdkdisplay.sgml docs/reference/gdk/tmpl/general.sgml docs/reference/gdk/tmpl/input_devices.sgml docs/reference/gdk/tmpl/selections.sgml docs/reference/gtk/tmpl/gtkcellrenderer.sgml docs/reference/gtk/tmpl/gtkcurve.sgml docs/reference/gtk/tmpl/gtkdnd.sgml docs/reference/gtk/tmpl/gtkitemfactory.sgml docs/reference/gtk/tmpl/gtkmenu.sgml docs/reference/gtk/tmpl/gtkoldeditable.sgml docs/reference/gtk/tmpl/gtkoptionmenu.sgml docs/reference/gtk/tmpl/gtkpreview.sgml docs/reference/gtk/tmpl/gtkselection.sgml docs/reference/gtk/tmpl/gtksocket.sgml docs/reference/gtk/tmpl/gtkstyle.sgml docs/reference/gtk/tmpl/gtktextbuffer.sgml docs/reference/gtk/tmpl/gtktreemodel.sgml docs/reference/gtk/tmpl/gtkwidget.sgml gdk/gdk.h gdk/gdkdisplay.c gdk/gdkdisplay.h gdk/gdkdnd.h gdk/gdkdraw.c gdk/gdkdrawable.h gdk/gdkinput.h gdk/gdkselection.h gdk/x11/gdkdisplay-x11.c gdk/x11/gdkdnd-x11.c gdk/x11/gdkselection-x11.c gtk/gtkcurve.h gtk/gtkdnd.h gtk/gtkitemfactory.c gtk/gtkitemfactory.h gtk/gtkmenu.h gtk/gtkoldeditable.c gtk/gtkoldeditable.h gtk/gtkoptionmenu.h gtk/gtkplug.c gtk/gtkplug.h gtk/gtkpreview.h gtk/gtkrange.h gtk/gtkselection.c gtk/gtkselection.h gtk/gtksocket.c gtk/gtksocket.h gtk/gtkstyle.c gtk/gtkstyle.h gtk/gtktextlayout.c gtk/gtktextlayout.h gtk/gtktreemodel.c gtk/gtktreemodel.h gtk/gtkwidget.h Trivial s/foo/foo_/ fixes to make gtk.h includable with -Wshadow without warnings. (#91680)
2002-11-08 19:41:50 +00:00
@time_: timestamp.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gdk_selection_send_notify_for_display ##### -->
<para>
</para>
@display:
@requestor:
@selection:
@target:
@property:
docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml Fri Nov 8 20:14:52 2002 Soeren Sandmann <sandmann@daimi.au.dk> * docs/reference/gdk/tmpl/dnd.sgml docs/reference/gdk/tmpl/drawing.sgml docs/reference/gdk/tmpl/gdk-unused.sgml docs/reference/gdk/tmpl/gdkdisplay.sgml docs/reference/gdk/tmpl/general.sgml docs/reference/gdk/tmpl/input_devices.sgml docs/reference/gdk/tmpl/selections.sgml docs/reference/gtk/tmpl/gtkcellrenderer.sgml docs/reference/gtk/tmpl/gtkcurve.sgml docs/reference/gtk/tmpl/gtkdnd.sgml docs/reference/gtk/tmpl/gtkitemfactory.sgml docs/reference/gtk/tmpl/gtkmenu.sgml docs/reference/gtk/tmpl/gtkoldeditable.sgml docs/reference/gtk/tmpl/gtkoptionmenu.sgml docs/reference/gtk/tmpl/gtkpreview.sgml docs/reference/gtk/tmpl/gtkselection.sgml docs/reference/gtk/tmpl/gtksocket.sgml docs/reference/gtk/tmpl/gtkstyle.sgml docs/reference/gtk/tmpl/gtktextbuffer.sgml docs/reference/gtk/tmpl/gtktreemodel.sgml docs/reference/gtk/tmpl/gtkwidget.sgml gdk/gdk.h gdk/gdkdisplay.c gdk/gdkdisplay.h gdk/gdkdnd.h gdk/gdkdraw.c gdk/gdkdrawable.h gdk/gdkinput.h gdk/gdkselection.h gdk/x11/gdkdisplay-x11.c gdk/x11/gdkdnd-x11.c gdk/x11/gdkselection-x11.c gtk/gtkcurve.h gtk/gtkdnd.h gtk/gtkitemfactory.c gtk/gtkitemfactory.h gtk/gtkmenu.h gtk/gtkoldeditable.c gtk/gtkoldeditable.h gtk/gtkoptionmenu.h gtk/gtkplug.c gtk/gtkplug.h gtk/gtkpreview.h gtk/gtkrange.h gtk/gtkselection.c gtk/gtkselection.h gtk/gtksocket.c gtk/gtksocket.h gtk/gtkstyle.c gtk/gtkstyle.h gtk/gtktextlayout.c gtk/gtktextlayout.h gtk/gtktreemodel.c gtk/gtktreemodel.h gtk/gtkwidget.h Trivial s/foo/foo_/ fixes to make gtk.h includable with -Wshadow without warnings. (#91680)
2002-11-08 19:41:50 +00:00
@time_: