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

<!-- ##### 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.