forked from AuroraMiddleware/gtk
50ab749f4b
2000-02-02 Damon Chaplin <damon@karuna.freeserve.co.uk>
* gdk/tmpl/*.sgml: ran make templates.
* gdk/gdk-docs.sgml: rearranged sections.
* gdk/tmpl/events.sgml: documented.
* gdk/tmpl/general.sgml: documented.
* gdk/tmpl/rgb.sgml: fixed a few '@' -> '#'.
* gdk/gdk-sections.txt: rearranged a few bits, including moving
GdkWChar and related functions from the input method section to the
font section, and GdkCapStyle etc. from Drawing Primitives to GCs.
* gdk/tmpl/images.sgml: documented.
* gdk/tmpl/drawing.sgml: updated.
* gdk/tmpl/regions.sgml: updated.
* gdk/tmpl/input_contexts.sgml: documented.
* gdk/tmpl/input_methods.sgml: documented.
* gdk/tmpl/selections.sgml: changed xref to a link since Jade says
a xref to a RefEntry is not supported.
186 lines
6.7 KiB
Plaintext
186 lines
6.7 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Selections
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
functions for transfering data via the X selection mechanism.
|
|
|
|
<!-- ##### 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).
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ENUM GdkSelection ##### -->
|
|
<para>
|
|
The #GdkSelection enumeration contains predefined
|
|
atom values for several common selections.
|
|
</para>
|
|
|
|
@GDK_SELECTION_PRIMARY: The primary X selection. Programs
|
|
typically claim this selection when the user
|
|
selects text and paste its contents in response
|
|
to a middle button press.
|
|
@GDK_SELECTION_SECONDARY: An additional X selection.
|
|
|
|
<!-- ##### ENUM GdkSelectionType ##### -->
|
|
<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>
|
|
|
|
@GDK_SELECTION_TYPE_ATOM: An atom. (format 32)
|
|
@GDK_SELECTION_TYPE_BITMAP: A bitmap ID. (format 32)
|
|
@GDK_SELECTION_TYPE_COLORMAP: A colormap ID. (format 32)
|
|
@GDK_SELECTION_TYPE_DRAWABLE: A drawable ID. (format 32)
|
|
@GDK_SELECTION_TYPE_INTEGER: An integer. (format 32)
|
|
@GDK_SELECTION_TYPE_PIXMAP: A pixmap ID. (format 32)
|
|
@GDK_SELECTION_TYPE_WINDOW: A window ID. (format 32)
|
|
@GDK_SELECTION_TYPE_STRING: A string encoded
|
|
in ISO Latin-1. (With the additional of <symbol>TAB</symbol>
|
|
and <symbol>NEWLINE</symbol>.) (format 8)
|
|
|
|
<!-- ##### ENUM 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.
|
|
</para>
|
|
|
|
@GDK_TARGET_BITMAP: A bitmap ID.
|
|
@GDK_TARGET_COLORMAP: A colormap ID.
|
|
@GDK_TARGET_DRAWABLE: A drawable ID.
|
|
@GDK_TARGET_PIXMAP: A pixmap ID.
|
|
@GDK_TARGET_STRING: A string encoded in ISO Latin-1.
|
|
(With the additional of <symbol>TAB</symbol>
|
|
and <symbol>NEWLINE</symbol>.)
|
|
|
|
<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
|
|
<para>
|
|
Set the owner of the given selection.
|
|
</para>
|
|
|
|
@owner: a #GdkWindow or NULL to indicate that the
|
|
the owner for the given should be unset.
|
|
@selection: an atom identifying a selection.
|
|
@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 succesfully
|
|
changed to @owner, otherwise %FALSE.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_selection_owner_get ##### -->
|
|
<para>
|
|
Determine the owner of the given selection.
|
|
</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.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_selection_convert ##### -->
|
|
<para>
|
|
Retrieve the contents of a selection in a given
|
|
form.
|
|
</para>
|
|
|
|
@requestor: a #GdkWindow.
|
|
@selection: an atom identifying the selection to get the
|
|
contents of.
|
|
@target: the form in which to retrieve the selection.
|
|
@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.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_selection_property_get ##### -->
|
|
<para>
|
|
Retrieve selection data that was stored by the selection
|
|
data in response to a call to gdk_selection_convert()
|
|
</para>
|
|
|
|
@requestor: the window on which the data is stored
|
|
@data: location to store a pointer to the retrieved data.
|
|
If the retrieval failed, NULL we be stored here, otherwise, it
|
|
will be non-NULL and the returned data should be freed with g_free()
|
|
when you are finished using it. The length of the
|
|
allocated memory is one more than the the length
|
|
of the returned data, and the final byte will always
|
|
be zero, to ensure null-termination of strings.
|
|
@prop_type: location to store the type of the property.
|
|
@prop_format: location to store the format of the property.
|
|
@Returns: the length of the retrieved data.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_selection_send_notify ##### -->
|
|
<para>
|
|
Send a response to SelectionRequest event.
|
|
</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.
|
|
@time: timestamp.
|
|
|
|
|