forked from AuroraMiddleware/gtk
459 lines
10 KiB
Plaintext
459 lines
10 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Clipboards
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
Storing data on clipboards
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
The #GtkClipboard object represents a clipboard of data shared
|
|
between different processes or between different widgets in
|
|
the same process. Each clipboard is identified by a name encoded as a
|
|
#GdkAtom. (Conversion to and from strings can be done with
|
|
gdk_atom_intern() and gdk_atom_name().) The default clipboard
|
|
corresponds to the "CLIPBOARD" atom; another commonly used clipboard
|
|
is the "PRIMARY" clipboard, which, in X, traditionally contains
|
|
the currently selected text.
|
|
</para>
|
|
<para>
|
|
To support having a number of different formats on the clipboard
|
|
at the same time, the clipboard mechanism allows providing
|
|
callbacks instead of the actual data. When you set the contents
|
|
of the clipboard, you can either supply the data directly (via
|
|
functions like gtk_clipboard_set_text()), or you can supply a
|
|
callback to be called at a later time when the data is needed (via
|
|
gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().)
|
|
Providing a callback also avoids having to make copies of the data
|
|
when it is not needed.
|
|
</para>
|
|
<para>
|
|
gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner()
|
|
are quite similar; the choice between the two depends mostly on
|
|
which is more convenient in a particular situation.
|
|
The former is most useful when you want to have a blob of data
|
|
with callbacks to convert it into the various data types that you
|
|
advertise. When the @clear_func you provided is called, you
|
|
simply free the data blob. The latter is more useful when the
|
|
contents of clipboard reflect the internal state of a #GObject
|
|
(As an example, for the PRIMARY clipboard, when an entry widget
|
|
provides the clipboard's contents the contents are simply the
|
|
text within the selected region.) If the contents change, the
|
|
entry widget can call gtk_clipboard_set_with_owner() to update
|
|
the timestamp for clipboard ownership, without having to worry
|
|
about @clear_func being called.
|
|
</para>
|
|
<para>
|
|
Requesting the data from the clipboard is essentially
|
|
asynchronous. If the contents of the clipboard are provided within
|
|
the same process, then a direct function call will be made to
|
|
retrieve the data, but if they are provided by another process,
|
|
then the data needs to be retrieved from the other process, which
|
|
may take some time. To avoid blocking the user interface, the call
|
|
to request the selection, gtk_clipboard_request_contents() takes a
|
|
callback that will be called when the contents are received (or
|
|
when the request fails.) If you don't want to deal with providing
|
|
a separate callback, you can also use gtk_clipboard_wait_for_contents().
|
|
What this does is run the GLib main loop recursively waiting for
|
|
the contents. This can simplify the code flow, but you still have
|
|
to be aware that other callbacks in your program can be called
|
|
while this recursive mainloop is running.
|
|
</para>
|
|
<para>
|
|
Along with the functions to get the clipboard contents as an
|
|
arbitrary data chunk, there are also functions to retrieve
|
|
it as text, gtk_clipboard_request_text() and
|
|
gtk_clipboard_wait_for_text(). These functions take care of
|
|
determining which formats are advertised by the clipboard
|
|
provider, asking for the clipboard in the best available format
|
|
and converting the results into the UTF-8 encoding. (The standard
|
|
form for representing strings in GTK+.)
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>#GtkSelection</term>
|
|
<listitem><para>#GtkClipboard provides a high-level wrapper around the
|
|
lower level routines that deal with X selections. It is
|
|
also possibly to directly manipulate the X selections,
|
|
though it is seldom necessary to do so.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GtkClipboard ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SIGNAL GtkClipboard::owner-change ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard: the object which received the signal.
|
|
@event:
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
|
|
<para>
|
|
A function to be called when the results of gtk_clipboard_request_contents()
|
|
are received, or when the request fails.
|
|
</para>
|
|
|
|
@clipboard: the #GtkClipboard
|
|
@selection_data: a #GtkSelectionData containing the data was received.
|
|
If retrieving the data failed, then then length field
|
|
of @selection_data will be negative.
|
|
@data: the @user_data supplied to gtk_clipboard_request_contents().
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardTextReceivedFunc ##### -->
|
|
<para>
|
|
A function to be called when the results of gtk_clipboard_request_text()
|
|
are received, or when the request fails.
|
|
</para>
|
|
|
|
@clipboard: the #GtkClipboard
|
|
@text: the text received, as a UTF-8 encoded string, or %NULL
|
|
if retrieving the data failed.
|
|
@data: the @user_data supplied to gtk_clipboard_request_text().
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardImageReceivedFunc ##### -->
|
|
<para>
|
|
A function to be called when the results of gtk_clipboard_request_image()
|
|
are received, or when the request fails.
|
|
</para>
|
|
|
|
@clipboard: the #GtkClipboard
|
|
@pixbuf: the received image
|
|
@data: the @user_data supplied to gtk_clipboard_request_image().
|
|
@Since: 2.6
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardTargetsReceivedFunc ##### -->
|
|
<para>
|
|
A function to be called when the results of gtk_clipboard_request_targets()
|
|
are received, or when the request fails.
|
|
</para>
|
|
|
|
@clipboard: the #GtkClipboard
|
|
@atoms: the supported targets, as array of #GdkAtom, or %NULL
|
|
if retrieving the data failed.
|
|
@n_atoms: the length of the @atoms array.
|
|
@data: the @user_data supplied to gtk_clipboard_request_targets().
|
|
@Since: 2.4
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardRichTextReceivedFunc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@format:
|
|
@text:
|
|
@length:
|
|
@data:
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardGetFunc ##### -->
|
|
<para>
|
|
A function that will be called to provide the contents of the selection.
|
|
If multiple types of data were advertised, the requested type can
|
|
be determined from the @info parameter or by checking the target field
|
|
of @selection_data. If the data could successfully be converted into
|
|
then it should be stored into the @selection_data object by
|
|
calling gtk_selection_data_set() (or related functions such
|
|
as gtk_selection_data_set_text()). If no data is set, the requestor
|
|
will be informed that the attempt to get the data failed.
|
|
</para>
|
|
|
|
@clipboard: the #GtkClipboard
|
|
@selection_data: a #GtkSelectionData argument in which the requested
|
|
data should be stored.
|
|
@info: the info field corresponding to the requested
|
|
target from the #GtkTargetEntry array passed to
|
|
gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().
|
|
@user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(), or
|
|
the @owner argument passed to gtk_clipboard_set_with_owner()
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GtkClipboardClearFunc ##### -->
|
|
<para>
|
|
A function that will be called when the contents of the clipboard are changed
|
|
or cleared. Once this has called, the @user_data_or_owner argument
|
|
will not be used again.
|
|
</para>
|
|
|
|
@clipboard: the #GtkClipboard
|
|
@user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(), or
|
|
the @owner argument passed to gtk_clipboard_set_with_owner()
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_get ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@selection:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_get_for_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@display:
|
|
@selection:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_get_display ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_set_with_data ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@targets:
|
|
@n_targets:
|
|
@get_func:
|
|
@clear_func:
|
|
@user_data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_set_with_owner ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@targets:
|
|
@n_targets:
|
|
@get_func:
|
|
@clear_func:
|
|
@owner:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_get_owner ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_clear ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_set_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@text:
|
|
@len:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_set_image ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@pixbuf:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_request_contents ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@target:
|
|
@callback:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_request_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@callback:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_request_image ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@callback:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_request_targets ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@callback:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_request_rich_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@buffer:
|
|
@callback:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_for_contents ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@target:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_for_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_for_image ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_for_rich_text ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@buffer:
|
|
@format:
|
|
@length:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_is_text_available ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_is_image_available ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_is_rich_text_available ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@buffer:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_for_targets ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@targets:
|
|
@n_targets:
|
|
@Returns:
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("../gtk-docs.sgml" "book" "refsect2" "")
|
|
End:
|
|
-->
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_wait_is_target_available ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@target:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_set_can_store ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
@targets:
|
|
@n_targets:
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_clipboard_store ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@clipboard:
|
|
|
|
|