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