The Clipboard 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 Atom. (Conversion to and from strings can be done with
intern and 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.
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
set_text), or you can supply a callback to be called at a later time when the
data is needed (via set_with_data or
set_with_owner.) Providing a callback also avoids having to make copies of
the data when it is not needed.
set_with_data and
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 Object (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
set_with_owner to update the timestamp for clipboard ownership, without having to worry about clear_func being called.
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,
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
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.
Along with the functions to get the clipboard contents as an arbitrary data chunk, there are also functions to retrieve it as text,
request_text and
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+.)
- public void clear ()
Clears the contents of the clipboard.
- public unowned Display get_display ()
Gets the Display associated with
this
- public unowned Object? get_owner ()
- public Atom get_selection ()
Gets the selection that this clipboard is for.
- public void request_contents (Atom target, ClipboardReceivedFunc callback)
Requests the contents of clipboard as the given target.
- public void request_image (ClipboardImageReceivedFunc callback)
Requests the contents of the clipboard as image.
- public void request_rich_text (TextBuffer buffer, ClipboardRichTextReceivedFunc callback)
Requests the contents of the clipboard as rich text.
- public void request_targets (ClipboardTargetsReceivedFunc callback)
Requests the contents of the clipboard as list of supported targets.
- public void request_text (ClipboardTextReceivedFunc callback)
Requests the contents of the clipboard as text.
- public void request_uris (ClipboardURIReceivedFunc callback)
Requests the contents of the clipboard as URIs.
- public void set_can_store (TargetEntry[]? targets)
Hints that the clipboard data should be stored somewhere when the
application exits or when gtk_clipboard_store () is called.
- public void set_image (Pixbuf pixbuf)
Sets the contents of the clipboard to the given
Pixbuf.
- public void set_text (string text, int len)
Sets the contents of the clipboard to the given UTF-8 string.
- public bool set_with_data (TargetEntry[] targets, ClipboardGetFunc get_func, ClipboardClearFunc clear_func, void* user_data)
Virtually sets the contents of the specified clipboard by providing a
list of supported formats for the clipboard data and a function to call to get the actual data when it is requested.
- public bool set_with_owner (TargetEntry[] targets, ClipboardGetFunc get_func, ClipboardClearFunc clear_func, Object owner)
Virtually sets the contents of the specified clipboard by providing a
list of supported formats for the clipboard data and a function to call to get the actual data when it is requested.
- public void store ()
Stores the current clipboard data somewhere so that it will stay
around after the application has quit.
- public SelectionData? wait_for_contents (Atom target)
Requests the contents of the clipboard using the given target.
- public Pixbuf? wait_for_image ()
Requests the contents of the clipboard as image and converts the
result to a Pixbuf.
- public uint8[]? wait_for_rich_text (TextBuffer buffer, out Atom format)
Requests the contents of the clipboard as rich text.
- public bool wait_for_targets (out Atom[] targets)
Returns a list of targets that are present on the clipboard, or
null if there aren’t any targets available.
- public string? wait_for_text ()
Requests the contents of the clipboard as text and converts the result
to UTF-8 if necessary.
- public string[]? wait_for_uris ()
Requests the contents of the clipboard as URIs.
- public bool wait_is_image_available ()
Test to see if there is an image available to be pasted This is done
by requesting the TARGETS atom and checking if it contains any of the supported image targets.
- public bool wait_is_rich_text_available (TextBuffer buffer)
Test to see if there is rich text available to be pasted This is done
by requesting the TARGETS atom and checking if it contains any of the supported rich text targets.
- public bool wait_is_target_available (Atom target)
Checks if a clipboard supports pasting data of a given type.
- public bool wait_is_text_available ()
Test to see if there is text available to be pasted This is done by
requesting the TARGETS atom and checking if it contains any of the supported text targets.
- public bool wait_is_uris_available ()
Test to see if there is a list of URIs available to be pasted This is
done by requesting the TARGETS atom and checking if it contains the URI targets.