1 2@c %start of fragment 3 4@deftp Class <gtk-clipboard> 5Derives from @code{<gobject>}. 6 7This class defines no direct slots. 8 9@end deftp 10 11@defop Signal <gtk-clipboard> owner-change (arg0@tie{}@code{<gdk-event>}) 12@end defop 13 14@deffn Function gtk-clipboard-get (selection@tie{}@code{<gdk-atom>}) @result{}@tie{} (ret@tie{}@code{<gtk-clipboard>}) 15Returns the clipboard object for the given selection. See 16@code{gtk-clipboard-get-for-display} for complete details. 17 18@table @var 19@item selection 20a @code{<gdk-atom>} which identifies the clipboard to use. 21 22@item ret 23the appropriate clipboard object. If no clipboard already exists, a new one will 24be created. Once a clipboard object has been created, it is persistent and, 25since it is owned by GTK+, must not be freed or unrefd. 26 27@end table 28 29@end deffn 30 31@deffn Function gtk-clipboard-get-for-display (display@tie{}@code{<gdk-display>}) (selection@tie{}@code{<gdk-atom>}) @result{}@tie{} (ret@tie{}@code{<gtk-clipboard>}) 32Returns the clipboard object for the given selection. Cut/copy/paste menu items 33and keyboard shortcuts should use the default clipboard, returned by passing 34@samp{GDK_SELECTION_CLIPBOARD} for @var{selection}. (@samp{GDK_NONE} is 35supported as a synonym for GDK_SELECTION_CLIPBOARD for backwards compatibility 36reasons.) The currently-selected object or text should be provided on the 37clipboard identified by @code{<gdk-selection-primary>}. Cut/copy/paste menu 38items conceptually copy the contents of the @code{<gdk-selection-primary>} 39clipboard to the default clipboard, i.e. they copy the selection to what the 40user sees as the clipboard. 41 42(Passing @code{<gdk-none>} is the same as using @samp{gdk_atom_intern 43("CLIPBOARD", FALSE)}. See 44@uref{http://www.freedesktop.org/Standards/clipboards-spec, 45http://www.freedesktop.org/Standards/clipboards-spec} for a detailed discussion 46of the "CLIPBOARD" vs. "PRIMARY" selections under the X window system. On Win32 47the @code{<gdk-selection-primary>} clipboard is essentially ignored.) 48 49It's possible to have arbitrary named clipboards; if you do invent new 50clipboards, you should prefix the selection name with an underscore (because the 51ICCCM requires that nonstandard atoms are underscore-prefixed), and namespace it 52as well. For example, if your application called "Foo" has a special-purpose 53clipboard, you might call it "_FOO_SPECIAL_CLIPBOARD". 54 55@table @var 56@item display 57the display for which the clipboard is to be retrieved or created 58 59@item selection 60a @code{<gdk-atom>} which identifies the clipboard to use. 61 62@item ret 63the appropriate clipboard object. If no clipboard already exists, a new one will 64be created. Once a clipboard object has been created, it is persistent and, 65since it is owned by GTK+, must not be freed or unrefd. 66 67@end table 68 69Since 2.2 70 71@end deffn 72 73@deffn Function gtk-clipboard-get-display (self@tie{}@code{<gtk-clipboard>}) @result{}@tie{} (ret@tie{}@code{<gdk-display>}) 74@deffnx Method get-display 75Gets the @code{<gdk-display>} associated with @var{clipboard} 76 77@table @var 78@item clipboard 79a @code{<gtk-clipboard>} 80 81@item ret 82the @code{<gdk-display>} associated with @var{clipboard} 83 84@end table 85 86Since 2.2 87 88@end deffn 89 90@deffn Function gtk-clipboard-get-owner (self@tie{}@code{<gtk-clipboard>}) @result{}@tie{} (ret@tie{}@code{<gobject>}) 91@deffnx Method get-owner 92If the clipboard contents callbacks were set with 93@code{gtk-clipboard-set-with-owner}, and the @code{gtk-clipboard-set-with-data} 94or @code{gtk-clipboard-clear} has not subsequently called, returns the owner set 95by @code{gtk-clipboard-set-with-owner}. 96 97@table @var 98@item clipboard 99a @code{<gtk-clipboard>} 100 101@item ret 102the owner of the clipboard, if any; otherwise @samp{@code{#f}}. 103 104@end table 105 106@end deffn 107 108@deffn Function gtk-clipboard-clear (self@tie{}@code{<gtk-clipboard>}) 109@deffnx Method clear 110Clears the contents of the clipboard. Generally this should only be called 111between the time you call @code{gtk-clipboard-set-with-owner} or 112@code{gtk-clipboard-set-with-data}, and when the @var{clear-func} you supplied 113is called. Otherwise, the clipboard may be owned by someone else. 114 115@table @var 116@item clipboard 117a @code{<gtk-clipboard>} 118 119@end table 120 121@end deffn 122 123@deffn Function gtk-clipboard-set-text (self@tie{}@code{<gtk-clipboard>}) (text@tie{}@code{mchars}) 124@deffnx Method set-text 125Sets the contents of the clipboard to the given UTF-8 string. GTK+ will make a 126copy of the text and take responsibility for responding for requests for the 127text, and for converting the text into the requested format. 128 129@table @var 130@item clipboard 131a @code{<gtk-clipboard>} object 132 133@item text 134a UTF-8 string. 135 136@item len 137length of @var{text}, in bytes, or -1, in which case the length will be 138determined with @code{@code{strlen}}. 139 140@end table 141 142@end deffn 143 144@deffn Function gtk-clipboard-set-image (self@tie{}@code{<gtk-clipboard>}) (pixbuf@tie{}@code{<gdk-pixbuf>}) 145@deffnx Method set-image 146Sets the contents of the clipboard to the given @code{<gdk-pixbuf>}. GTK+ will 147take responsibility for responding for requests for the image, and for 148converting the image into the requested format. 149 150@table @var 151@item clipboard 152a @code{<gtk-clipboard>} object 153 154@item pixbuf 155a @code{<gdk-pixbuf>} 156 157@end table 158 159Since 2.6 160 161@end deffn 162 163@deffn Function gtk-clipboard-wait-for-contents (self@tie{}@code{<gtk-clipboard>}) (target@tie{}@code{<gdk-atom>}) @result{}@tie{} (ret@tie{}@code{<gtk-selection-data>}) 164@deffnx Method wait-for-contents 165Requests the contents of the clipboard using the given target. This function 166waits for the data to be received using the main loop, so events, timeouts, etc, 167may be dispatched during the wait. 168 169@table @var 170@item clipboard 171a @code{<gtk-clipboard>} 172 173@item target 174an atom representing the form into which the clipboard owner should convert the 175selection. 176 177@item ret 178a newly-allocated @code{<gtk-selection-data>} object or @samp{@code{#f}} if 179retrieving the given target failed. If non-@samp{@code{#f}}, this value must be 180freed with @code{gtk-selection-data-free} when you are finished with it. 181 182@end table 183 184@end deffn 185 186@deffn Function gtk-clipboard-wait-for-text (self@tie{}@code{<gtk-clipboard>}) @result{}@tie{} (ret@tie{}@code{mchars}) 187@deffnx Method wait-for-text 188Requests the contents of the clipboard as text and converts the result to UTF-8 189if necessary. This function waits for the data to be received using the main 190loop, so events, timeouts, etc, may be dispatched during the wait. 191 192@table @var 193@item clipboard 194a @code{<gtk-clipboard>} 195 196@item ret 197a newly-allocated UTF-8 string which must be freed with @code{g-free}, or 198@samp{@code{#f}} if retrieving the selection data failed. (This could happen for 199various reasons, in particular if the clipboard was empty or if the contents of 200the clipboard could not be converted into text form.) 201 202@end table 203 204@end deffn 205 206@deffn Function gtk-clipboard-wait-for-image (self@tie{}@code{<gtk-clipboard>}) @result{}@tie{} (ret@tie{}@code{<gdk-pixbuf>}) 207@deffnx Method wait-for-image 208Requests the contents of the clipboard as image and converts the result to a 209@code{<gdk-pixbuf>}. This function waits for the data to be received using the 210main loop, so events, timeouts, etc, may be dispatched during the wait. 211 212@table @var 213@item clipboard 214a @code{<gtk-clipboard>} 215 216@item ret 217a newly-allocated @code{<gdk-pixbuf>} object which must be disposed with 218@code{g-object-unref}, or @samp{@code{#f}} if retrieving the selection data 219failed. (This could happen for various reasons, in particular if the clipboard 220was empty or if the contents of the clipboard could not be converted into an 221image.) 222 223@end table 224 225Since 2.6 226 227@end deffn 228 229@deffn Function gtk-clipboard-store (self@tie{}@code{<gtk-clipboard>}) 230@deffnx Method store 231Stores the current clipboard data somewhere so that it will stay around after 232the application has quit. 233 234@table @var 235@item clipboard 236a @code{<gtk-clipboard>} 237 238@end table 239 240Since 2.6 241 242@end deffn 243 244 245@c %end of fragment 246