1 2@c %start of fragment 3 4@node Clipboards 5@chapter Clipboards 6Storing data on clipboards 7 8@section Overview 9The @code{<gtk-clipboard>} object represents a clipboard of data shared between 10different processes or between different widgets in the same process. Each 11clipboard is identified by a name encoded as a @code{<gdk-atom>}. (Conversion to 12and from strings can be done with @code{gdk-atom-intern} and 13@code{gdk-atom-name}.) The default clipboard corresponds to the "CLIPBOARD" 14atom; another commonly used clipboard is the "PRIMARY" clipboard, which, in X, 15traditionally contains the currently selected text. 16 17To support having a number of different formats on the clipboard at the same 18time, the clipboard mechanism allows providing callbacks instead of the actual 19data. When you set the contents of the clipboard, you can either supply the data 20directly (via functions like @code{gtk-clipboard-set-text}), or you can supply a 21callback to be called at a later time when the data is needed (via 22@code{gtk-clipboard-set-with-data} or @code{gtk-clipboard-set-with-owner}.) 23Providing a callback also avoids having to make copies of the data when it is 24not needed. 25 26@code{gtk-clipboard-set-with-data} and @code{gtk-clipboard-set-with-owner} are 27quite similar; the choice between the two depends mostly on which is more 28convenient in a particular situation. The former is most useful when you want to 29have a blob of data with callbacks to convert it into the various data types 30that you advertise. When the @var{clear-func} you provided is called, you simply 31free the data blob. The latter is more useful when the contents of clipboard 32reflect the internal state of a @code{<gobject>} (As an example, for the PRIMARY 33clipboard, when an entry widget provides the clipboard's contents the contents 34are simply the text within the selected region.) If the contents change, the 35entry widget can call @code{gtk-clipboard-set-with-owner} to update the 36timestamp for clipboard ownership, without having to worry about 37@var{clear-func} being called. 38 39Requesting the data from the clipboard is essentially asynchronous. If the 40contents of the clipboard are provided within the same process, then a direct 41function call will be made to retrieve the data, but if they are provided by 42another process, then the data needs to be retrieved from the other process, 43which may take some time. To avoid blocking the user interface, the call to 44request the selection, @code{gtk-clipboard-request-contents} takes a callback 45that will be called when the contents are received (or when the request fails.) 46If you don't want to deal with providing a separate callback, you can also use 47@code{gtk-clipboard-wait-for-contents}. What this does is run the GLib main loop 48recursively waiting for the contents. This can simplify the code flow, but you 49still have to be aware that other callbacks in your program can be called while 50this recursive mainloop is running. 51 52Along with the functions to get the clipboard contents as an arbitrary data 53chunk, there are also functions to retrieve it as text, 54@code{gtk-clipboard-request-text} and @code{gtk-clipboard-wait-for-text}. These 55functions take care of determining which formats are advertised by the clipboard 56provider, asking for the clipboard in the best available format and converting 57the results into the UTF-8 encoding. (The standard form for representing strings 58in GTK+.) 59 60@section Usage 61@include defuns-gtkclipboard.xml.texi 62 63@c %end of fragment 64