1/* GTK - The GIMP Toolkit
2 * Copyright (C) 2000 Red Hat, Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 *
17 * Global clipboard abstraction.
18 */
19
20#ifndef __GTK_CLIPBOARD_H__
21#define __GTK_CLIPBOARD_H__
22
23#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
24#error "Only <gtk/gtk.h> can be included directly."
25#endif
26
27#include <gtk/gtkselection.h>
28
29G_BEGIN_DECLS
30
31#define GTK_TYPE_CLIPBOARD (gtk_clipboard_get_type ())
32#define GTK_CLIPBOARD(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_CLIPBOARD, GtkClipboard))
33#define GTK_IS_CLIPBOARD(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_CLIPBOARD))
34
35/**
36 * GtkClipboardReceivedFunc:
37 * @clipboard: the #GtkClipboard
38 * @selection_data: a #GtkSelectionData containing the data was received.
39 * If retrieving the data failed, then then length field
40 * of @selection_data will be negative.
41 * @data: (closure): the @user_data supplied to
42 * gtk_clipboard_request_contents().
43 *
44 * A function to be called when the results of gtk_clipboard_request_contents()
45 * are received, or when the request fails.
46 */
47typedef void (* GtkClipboardReceivedFunc) (GtkClipboard *clipboard,
48 GtkSelectionData *selection_data,
49 gpointer data);
50
51/**
52 * GtkClipboardTextReceivedFunc:
53 * @clipboard: the #GtkClipboard
54 * @text: (nullable): the text received, as a UTF-8 encoded string, or
55 * %NULL if retrieving the data failed.
56 * @data: (closure): the @user_data supplied to
57 * gtk_clipboard_request_text().
58 *
59 * A function to be called when the results of gtk_clipboard_request_text()
60 * are received, or when the request fails.
61 */
62typedef void (* GtkClipboardTextReceivedFunc) (GtkClipboard *clipboard,
63 const gchar *text,
64 gpointer data);
65
66/**
67 * GtkClipboardRichTextReceivedFunc:
68 * @clipboard: the #GtkClipboard
69 * @format: The format of the rich text
70 * @text: (nullable) (type utf8): the rich text received, as
71 * a UTF-8 encoded string, or %NULL if retrieving the data failed.
72 * @length: Length of the text.
73 * @data: (closure): the @user_data supplied to
74 * gtk_clipboard_request_rich_text().
75 *
76 * A function to be called when the results of
77 * gtk_clipboard_request_rich_text() are received, or when the request
78 * fails.
79 *
80 * Since: 2.10
81 */
82typedef void (* GtkClipboardRichTextReceivedFunc) (GtkClipboard *clipboard,
83 GdkAtom format,
84 const guint8 *text,
85 gsize length,
86 gpointer data);
87
88/**
89 * GtkClipboardImageReceivedFunc:
90 * @clipboard: the #GtkClipboard
91 * @pixbuf: the received image
92 * @data: (closure): the @user_data supplied to
93 * gtk_clipboard_request_image().
94 *
95 * A function to be called when the results of gtk_clipboard_request_image()
96 * are received, or when the request fails.
97 *
98 * Since: 2.6
99 */
100typedef void (* GtkClipboardImageReceivedFunc) (GtkClipboard *clipboard,
101 GdkPixbuf *pixbuf,
102 gpointer data);
103
104/**
105 * GtkClipboardURIReceivedFunc:
106 * @clipboard: the #GtkClipboard
107 * @uris: (array zero-terminated=1): the received URIs
108 * @data: (closure): the @user_data supplied to
109 * gtk_clipboard_request_uris().
110 *
111 * A function to be called when the results of
112 * gtk_clipboard_request_uris() are received, or when the request
113 * fails.
114 *
115 * Since: 2.14
116 */
117typedef void (* GtkClipboardURIReceivedFunc) (GtkClipboard *clipboard,
118 gchar **uris,
119 gpointer data);
120
121/**
122 * GtkClipboardTargetsReceivedFunc:
123 * @clipboard: the #GtkClipboard
124 * @atoms: (nullable) (array length=n_atoms): the supported targets,
125 * as array of #GdkAtom, or %NULL if retrieving the data failed.
126 * @n_atoms: the length of the @atoms array.
127 * @data: (closure): the @user_data supplied to
128 * gtk_clipboard_request_targets().
129 *
130 * A function to be called when the results of gtk_clipboard_request_targets()
131 * are received, or when the request fails.
132 *
133 * Since: 2.4
134 */
135typedef void (* GtkClipboardTargetsReceivedFunc) (GtkClipboard *clipboard,
136 GdkAtom *atoms,
137 gint n_atoms,
138 gpointer data);
139
140/* Should these functions have GtkClipboard *clipboard as the first argument?
141 * right now for ClearFunc, you may have trouble determining _which_ clipboard
142 * was cleared, if you reuse your ClearFunc for multiple clipboards.
143 */
144/**
145 * GtkClipboardGetFunc:
146 * @clipboard: the #GtkClipboard
147 * @selection_data: a #GtkSelectionData argument in which the requested
148 * data should be stored.
149 * @info: the info field corresponding to the requested target from the
150 * #GtkTargetEntry array passed to gtk_clipboard_set_with_data() or
151 * gtk_clipboard_set_with_owner().
152 * @user_data_or_owner: the @user_data argument passed to
153 * gtk_clipboard_set_with_data(), or the @owner argument passed to
154 * gtk_clipboard_set_with_owner()
155 *
156 * A function that will be called to provide the contents of the selection.
157 * If multiple types of data were advertised, the requested type can
158 * be determined from the @info parameter or by checking the target field
159 * of @selection_data. If the data could successfully be converted into
160 * then it should be stored into the @selection_data object by
161 * calling gtk_selection_data_set() (or related functions such
162 * as gtk_selection_data_set_text()). If no data is set, the requestor
163 * will be informed that the attempt to get the data failed.
164 */
165typedef void (* GtkClipboardGetFunc) (GtkClipboard *clipboard,
166 GtkSelectionData *selection_data,
167 guint info,
168 gpointer user_data_or_owner);
169
170/**
171 * GtkClipboardClearFunc:
172 * @clipboard: the #GtkClipboard
173 * @user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(),
174 * or the @owner argument passed to gtk_clipboard_set_with_owner()
175 *
176 * A function that will be called when the contents of the clipboard are changed
177 * or cleared. Once this has called, the @user_data_or_owner argument
178 * will not be used again.
179 */
180typedef void (* GtkClipboardClearFunc) (GtkClipboard *clipboard,
181 gpointer user_data_or_owner);
182
183GDK_AVAILABLE_IN_ALL
184GType gtk_clipboard_get_type (void) G_GNUC_CONST;
185
186GDK_AVAILABLE_IN_ALL
187GtkClipboard *gtk_clipboard_get_for_display (GdkDisplay *display,
188 GdkAtom selection);
189GDK_AVAILABLE_IN_ALL
190GtkClipboard *gtk_clipboard_get (GdkAtom selection);
191
192GDK_AVAILABLE_IN_3_16
193GtkClipboard *gtk_clipboard_get_default (GdkDisplay *display);
194
195GDK_AVAILABLE_IN_ALL
196GdkDisplay *gtk_clipboard_get_display (GtkClipboard *clipboard);
197
198
199GDK_AVAILABLE_IN_ALL
200gboolean gtk_clipboard_set_with_data (GtkClipboard *clipboard,
201 const GtkTargetEntry *targets,
202 guint n_targets,
203 GtkClipboardGetFunc get_func,
204 GtkClipboardClearFunc clear_func,
205 gpointer user_data);
206GDK_AVAILABLE_IN_ALL
207gboolean gtk_clipboard_set_with_owner (GtkClipboard *clipboard,
208 const GtkTargetEntry *targets,
209 guint n_targets,
210 GtkClipboardGetFunc get_func,
211 GtkClipboardClearFunc clear_func,
212 GObject *owner);
213GDK_AVAILABLE_IN_ALL
214GObject *gtk_clipboard_get_owner (GtkClipboard *clipboard);
215GDK_AVAILABLE_IN_ALL
216void gtk_clipboard_clear (GtkClipboard *clipboard);
217GDK_AVAILABLE_IN_ALL
218void gtk_clipboard_set_text (GtkClipboard *clipboard,
219 const gchar *text,
220 gint len);
221GDK_AVAILABLE_IN_ALL
222void gtk_clipboard_set_image (GtkClipboard *clipboard,
223 GdkPixbuf *pixbuf);
224
225GDK_AVAILABLE_IN_ALL
226void gtk_clipboard_request_contents (GtkClipboard *clipboard,
227 GdkAtom target,
228 GtkClipboardReceivedFunc callback,
229 gpointer user_data);
230GDK_AVAILABLE_IN_ALL
231void gtk_clipboard_request_text (GtkClipboard *clipboard,
232 GtkClipboardTextReceivedFunc callback,
233 gpointer user_data);
234GDK_AVAILABLE_IN_ALL
235void gtk_clipboard_request_rich_text (GtkClipboard *clipboard,
236 GtkTextBuffer *buffer,
237 GtkClipboardRichTextReceivedFunc callback,
238 gpointer user_data);
239GDK_AVAILABLE_IN_ALL
240void gtk_clipboard_request_image (GtkClipboard *clipboard,
241 GtkClipboardImageReceivedFunc callback,
242 gpointer user_data);
243GDK_AVAILABLE_IN_ALL
244void gtk_clipboard_request_uris (GtkClipboard *clipboard,
245 GtkClipboardURIReceivedFunc callback,
246 gpointer user_data);
247GDK_AVAILABLE_IN_ALL
248void gtk_clipboard_request_targets (GtkClipboard *clipboard,
249 GtkClipboardTargetsReceivedFunc callback,
250 gpointer user_data);
251
252GDK_AVAILABLE_IN_ALL
253GtkSelectionData *gtk_clipboard_wait_for_contents (GtkClipboard *clipboard,
254 GdkAtom target);
255GDK_AVAILABLE_IN_ALL
256gchar * gtk_clipboard_wait_for_text (GtkClipboard *clipboard);
257GDK_AVAILABLE_IN_ALL
258guint8 * gtk_clipboard_wait_for_rich_text (GtkClipboard *clipboard,
259 GtkTextBuffer *buffer,
260 GdkAtom *format,
261 gsize *length);
262GDK_AVAILABLE_IN_ALL
263GdkPixbuf * gtk_clipboard_wait_for_image (GtkClipboard *clipboard);
264GDK_AVAILABLE_IN_ALL
265gchar ** gtk_clipboard_wait_for_uris (GtkClipboard *clipboard);
266GDK_AVAILABLE_IN_ALL
267gboolean gtk_clipboard_wait_for_targets (GtkClipboard *clipboard,
268 GdkAtom **targets,
269 gint *n_targets);
270
271GDK_AVAILABLE_IN_ALL
272gboolean gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard);
273GDK_AVAILABLE_IN_ALL
274gboolean gtk_clipboard_wait_is_rich_text_available (GtkClipboard *clipboard,
275 GtkTextBuffer *buffer);
276GDK_AVAILABLE_IN_ALL
277gboolean gtk_clipboard_wait_is_image_available (GtkClipboard *clipboard);
278GDK_AVAILABLE_IN_ALL
279gboolean gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard);
280GDK_AVAILABLE_IN_ALL
281gboolean gtk_clipboard_wait_is_target_available (GtkClipboard *clipboard,
282 GdkAtom target);
283
284
285GDK_AVAILABLE_IN_ALL
286void gtk_clipboard_set_can_store (GtkClipboard *clipboard,
287 const GtkTargetEntry *targets,
288 gint n_targets);
289
290GDK_AVAILABLE_IN_ALL
291void gtk_clipboard_store (GtkClipboard *clipboard);
292
293GDK_AVAILABLE_IN_3_22
294GdkAtom gtk_clipboard_get_selection (GtkClipboard *clipboard);
295
296G_END_DECLS
297
298#endif /* __GTK_CLIPBOARD_H__ */
299