Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkclipboard.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Clipboards
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Storing data on Clipboards.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8   <para>
   9     The #GtkClipboard object represents a clipboard of data shared
  10     between different processes or between different widgets in
  11     the same process. Each clipboard is identified by a name encoded as a
  12     #GdkAtom. (Conversion to and from strings can be done with
  13     gdk_atom_intern() and gdk_atom_name().) The default clipboard
  14     corresponds to the CLIPBOARD atom; another commonly used clipboard
  15     is the PRIMARY clipboard, which, in X, traditionally contains
  16     the currently selected text.
  17   </para>
  18   <para>
  19     To support having a number of different formats on the clipboard
  20     at the same time, the clipboard mechanism allows providing
  21     callbacks instead of the actual data.  When you set the contents
  22     of the clipboard, you can either supply the data directly (via
  23     functions like gtk_clipboard_set_text()), or you can supply a
  24     callback to be called at a later time when the data is needed (via
  25     gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().)
  26     Providing a callback also avoids having to make copies of the data
  27     when it is not needed.
  28   </para>
  29   <para>
  30     gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner()
  31     are quite similar; the choice between the two depends mostly on
  32     which is more convenient in a particular situation.
  33     The former is most useful when you want to have a blob of data
  34     with callbacks to convert it into the various data types that you
  35     advertise. When the @clear_func you provided is called, you
  36     simply free the data blob. The latter is more useful when the
  37     contents of clipboard reflect the internal state of a @GObject
  38     (As an example, for the PRIMARY clipboard, when an entry widget
  39     provides the clipboard's contents the contents are simply the
  40     text within the selected region.) If the contents change, the
  41     entry widget can call gtk_clipboard_set_with_owner() to update
  42     the timestamp for clipboard ownership, without having to worry
  43     about @clear_func being called.
  44   </para>
  45   <para>
  46     Requesting the data from the clipboard is essentially
  47     asynchronous. If the contents of the clipboard are provided within
  48     the same process, then a direct function call will be made to
  49     retrieve the data, but if they are provided by another process,
  50     then the data needs to be retrieved from the other process, which
  51     may take some time. To avoid blocking the user interface, the call
  52     to request the selection, gtk_clipboard_request_contents() takes a
  53     callback that will be called when the contents are received (or
  54     when the request fails.) If you don't want to deal with providing
  55     a separate callback, you can also use gtk_clipboard_wait_for_contents().
  56     What this does is run the Glib main loop recursively waiting for
  57     the contents. This can simplify the code flow, but you still have
  58     to be aware that other callbacks in your program can be called
  59     while this recursive mainloop is running.
  60   </para>
  61   <para>
  62     Along with the functions to get the clipboard contents as an
  63     arbitrary data chunk, there are also functions to retrieve
  64     it as text, gtk_clipboard_request_text() and
  65     gtk_clipboard_wait_for_text(). These functions take care of
  66     determining which formats are advertised by the clipboard
  67     provider, asking for the clipboard in the best available format
  68     and converting the results into the UTF-8 encoding. (The standard
  69     form for representing strings in GTK+.)
  70   </para>
  71
  72 <!-- ##### SECTION See_Also ##### -->
  73 <para>
  74 <variablelist>
  75
  76 <varlistentry>
  77 <term>#GtkSelection</term>
  78 <listitem><para>@GtkClipboard provides a high-level wrapper around the
  79             lower level routines that deal with X selections. It is
  80             also possibly to directly manipulate the X selections,
  81             though it is seldom necessary to do so.</para></listitem>
  82 </varlistentry>
  83
  84 </variablelist>
  85 </para>
  86
  87 <!-- ##### STRUCT GtkClipboard ##### -->
  88 <para>
  89
  90 </para>
  91
  92
  93 <!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
  94 <para>
  95     A function to be called when the results of gtk_clipboard_request_text()
  96     are received, or when the request fails.
  97 </para>
  98
  99 @clipboard: the #GtkClipboard
 100 @selection_data: a #GtkSelectionData containing the data was received.
 101                  If retrieving the data failed, then then length field
 102                  of @selection_data will be negative.
 103 @data: the @user_data supplied to gtk_clipboard_request_contents().
 104
 105
 106 <!-- ##### USER_FUNCTION GtkClipboardTextReceivedFunc ##### -->
 107 <para>
 108     A function to be called when the results of gtk_clipboard_request_text()
 109     are received, or when the request fails.
 110 </para>
 111
 112 @clipboard: the #GtkClipboard
 113 @text: the text received, as a UTF-8 encoded string, or %NULL
 114             if retrieving the data failed.
 115 @data: the @user_data supplied to gtk_clipboard_request_text().
 116
 117
 118 <!-- ##### USER_FUNCTION GtkClipboardGetFunc ##### -->
 119 <para>
 120 A function that will be called to provide the contents of the selection.
 121 If multiple types of data were advertised, the requested type can
 122 be determined from the @info parameter or by checking the target field
 123 of @selection_data. If the data could succesfully be converted into
 124 then it should be stored into the @selection_data object by
 125 calling gtk_selection_data_set() (or related functions such
 126 as gtk_seletion_data_get().) If no data is set, the requestor
 127 will be informed that the attempt to get the data failed.
 128 </para>
 129
 130 @clipboard: the #GtkClipboard
 131 @selection_data: a #GtkSelectionData argument in which the requested
 132                      data should be stored.
 133 @info: the info field corresponding to the requested
 134                      target from the #GtkTargetEntry array passed to
 135                      gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner().
 136 @user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(), or
 137                      the @owner argument passed to gtk_clipboard_set_owner()
 138
 139
 140 <!-- ##### USER_FUNCTION GtkClipboardClearFunc ##### -->
 141 <para>
 142 A function that will be called when the contents of the clipboard are changed
 143 or cleared. Once this has called, the @user_data_or_owner argument
 144 will not be used again.
 145 </para>
 146
 147 @clipboard: the #GtkClipboard
 148 @user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(), or
 149                      the @owner argument passed to gtk_clipboard_set_owner()
 150
 151
 152 <!-- ##### FUNCTION gtk_clipboard_get ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @selection:
 158 @Returns:
 159
 160
 161 <!-- ##### FUNCTION gtk_clipboard_set_with_data ##### -->
 162 <para>
 163
 164 </para>
 165
 166 @clipboard:
 167 @targets:
 168 @n_targets:
 169 @get_func:
 170 @clear_func:
 171 @user_data:
 172 @Returns:
 173
 174
 175 <!-- ##### FUNCTION gtk_clipboard_set_with_owner ##### -->
 176 <para>
 177
 178 </para>
 179
 180 @clipboard:
 181 @targets:
 182 @n_targets:
 183 @get_func:
 184 @clear_func:
 185 @owner:
 186 @Returns:
 187
 188
 189 <!-- ##### FUNCTION gtk_clipboard_get_owner ##### -->
 190 <para>
 191
 192 </para>
 193
 194 @clipboard:
 195 @Returns:
 196
 197
 198 <!-- ##### FUNCTION gtk_clipboard_clear ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @clipboard:
 204
 205
 206 <!-- ##### FUNCTION gtk_clipboard_set_text ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @clipboard:
 212 @text:
 213 @len:
 214
 215
 216 <!-- ##### FUNCTION gtk_clipboard_request_contents ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @clipboard:
 222 @target:
 223 @callback:
 224 @user_data:
 225
 226
 227 <!-- ##### FUNCTION gtk_clipboard_request_text ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @clipboard:
 233 @callback:
 234 @user_data:
 235
 236
 237 <!-- ##### FUNCTION gtk_clipboard_wait_for_contents ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @clipboard:
 243 @target:
 244 @Returns:
 245
 246
 247 <!-- ##### FUNCTION gtk_clipboard_wait_for_text ##### -->
 248 <para>
 249
 250 </para>
 251
 252 @clipboard:
 253 @Returns:
 254 <!--
 255 Local variables:
 256 mode: sgml
 257 sgml-parent-document: ("../gtk-docs.sgml" "book" "refsect2" "")
 258 End:
 259 -->
 260
 261