Updates for new functions
Thu Sep 14 12:38:33 2000 Owen Taylor <otaylor@redhat.com> * docs/reference/gdk/: Updates for new functions * docs/reference/gdk/tmpl/gtkclipboard.sgml docs/reference/gdk/tmpl/gtkselection.sgml: Updates and new information.
This commit is contained in:
Owen Taylor
260
docs/reference/gtk/tmpl/gtkclipboard.sgml
Normal file
260
docs/reference/gtk/tmpl/gtkclipboard.sgml
Normal file
@ -0,0 +1,260 @@
|
||||
<!-- ##### 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>
|
||||
|
||||
<!-- ##### STRUCT GtkClipboard ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_clipboard_get ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@selection:
|
||||
@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:
|
||||
|
||||
|
||||
<!-- ##### 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 succesfully 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_seletion_data_get().) 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_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_owner()
|
||||
|
||||
|
||||
<!-- ##### 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_request_contents ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@clipboard:
|
||||
@target:
|
||||
@callback:
|
||||
@user_data:
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
|
||||
<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
|
||||
@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().
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_clipboard_request_text ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@clipboard:
|
||||
@callback:
|
||||
@user_data:
|
||||
|
||||
|
||||
<!-- ##### 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().
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_clipboard_wait_for_contents ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@clipboard:
|
||||
@target:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_clipboard_wait_for_text ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@clipboard:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!--
|
||||
Local variables:
|
||||
mode: sgml
|
||||
sgml-parent-document: ("../gtk-docs.sgml" "book" "refsect2" "")
|
||||
End:
|
||||
-->
|
||||
@ -7,12 +7,37 @@ Functions for handling inter-process communication via selections.
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
|
||||
<para>
|
||||
See the documentation for #GtkWidget for descriptions
|
||||
of the "selection_get" and "selection_received" signals.
|
||||
The selection mechanism provides the basis for different types
|
||||
of IPC between processes. In particular, drag and drop and
|
||||
#GtkClipboard work via selections. You will very seldom or
|
||||
never need to use most of the functions in this section directly;
|
||||
#GtkClipboard provides a nicer interface to the same functionality.
|
||||
</para>
|
||||
<para>
|
||||
Some of the datatypes defined this section are used in
|
||||
the #GtkClipboard and drag-and-drop API's as well. The
|
||||
#GtkTargetEntry structure and #GtkTargetList objects represent
|
||||
lists of data types that are supported when sending or
|
||||
receiving data. The #GtkSelectionData object is used to
|
||||
store a chunk of data along with the data type and other
|
||||
associated information.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>#GtkWidget</term>
|
||||
<listitem><para>Much of the operation of selections happens via
|
||||
signals for #GtkWidget. In particular, if you are
|
||||
using the functions in this section, you may need
|
||||
to pay attention to ::selection_get,
|
||||
::selection_received, and :selection_clear_event
|
||||
signals.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</para>
|
||||
|
||||
@ -159,6 +184,15 @@ for a given widget and selection.
|
||||
@ntargets: number of entries in @targets
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_clear_targets ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@widget:
|
||||
@selection:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_convert ##### -->
|
||||
<para>
|
||||
Request the contents of a selection. When received,
|
||||
@ -175,6 +209,29 @@ a "selection_received" signal will be generated.
|
||||
this widget).
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_remove_all ##### -->
|
||||
<para>
|
||||
Removes all handlers and unsets ownership of all
|
||||
selections for a widget. Called when widget is being
|
||||
destroyed. This function will not generally be
|
||||
called by applications.
|
||||
</para>
|
||||
|
||||
@widget: a #GtkWidget
|
||||
|
||||
|
||||
<!-- ##### STRUCT GtkSelectionData ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@selection:
|
||||
@target:
|
||||
@type:
|
||||
@format:
|
||||
@data:
|
||||
@length:
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_data_set ##### -->
|
||||
<para>
|
||||
Store new data into a GtkSelectionData object. Should
|
||||
@ -189,15 +246,23 @@ Null terminates the stored data.
|
||||
@length: length of the data
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_remove_all ##### -->
|
||||
<!-- ##### FUNCTION gtk_selection_data_set_text ##### -->
|
||||
<para>
|
||||
Removes all handlers and unsets ownership of all
|
||||
selections for a widget. Called when widget is being
|
||||
destroyed. This function will not generally be
|
||||
called by applications.
|
||||
|
||||
</para>
|
||||
|
||||
@widget: a #GtkWidget
|
||||
@selection_data:
|
||||
@str:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_data_get_text ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@selection_data:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_selection_data_copy ##### -->
|
||||
|
||||
Reference in New Issue
Block a user