gtkclipboard.h 12.2 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
2 3 4 5 6 7 8 9 10 11 12 13 14
 * Copyright (C) 2000 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16
 *
17
 * Global clipboard abstraction.
18 19
 */

20 21 22
#ifndef __GTK_CLIPBOARD_H__
#define __GTK_CLIPBOARD_H__

23
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
24 25 26
#error "Only <gtk/gtk.h> can be included directly."
#endif

27 28
#include <gtk/gtkselection.h>

29 30
G_BEGIN_DECLS

31
#define GTK_TYPE_CLIPBOARD            (gtk_clipboard_get_type ())
Manish Singh's avatar
Manish Singh committed
32 33
#define GTK_CLIPBOARD(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_CLIPBOARD, GtkClipboard))
#define GTK_IS_CLIPBOARD(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_CLIPBOARD))
34

35 36 37 38 39 40
/**
 * GtkClipboardReceivedFunc:
 * @clipboard: the #GtkClipboard
 * @selection_data: a #GtkSelectionData containing the data was received.
 *   If retrieving the data failed, then then length field
 *   of @selection_data will be negative.
41 42
 * @data: (closure): the @user_data supplied to
 *   gtk_clipboard_request_contents().
43 44 45 46
 *
 * A function to be called when the results of gtk_clipboard_request_contents()
 * are received, or when the request fails.
 */
47 48 49
typedef void (* GtkClipboardReceivedFunc)         (GtkClipboard     *clipboard,
					           GtkSelectionData *selection_data,
					           gpointer          data);
50 51 52 53

/**
 * GtkClipboardTextReceivedFunc:
 * @clipboard: the #GtkClipboard
54 55 56 57
 * @text: (nullable): the text received, as a UTF-8 encoded string, or
 *   %NULL if retrieving the data failed.
 * @data: (closure): the @user_data supplied to
 *   gtk_clipboard_request_text().
58 59 60 61
 *
 * A function to be called when the results of gtk_clipboard_request_text()
 * are received, or when the request fails.
 */
62 63 64
typedef void (* GtkClipboardTextReceivedFunc)     (GtkClipboard     *clipboard,
					           const gchar      *text,
					           gpointer          data);
65

66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
/**
 * GtkClipboardRichTextReceivedFunc:
 * @clipboard: the #GtkClipboard
 * @format: The format of the rich text
 * @text: (nullable) (type utf8): the rich text received, as
 *   a UTF-8 encoded string, or %NULL if retrieving the data failed.
 * @length: Length of the text.
 * @data: (closure): the @user_data supplied to
 *   gtk_clipboard_request_rich_text().
 *
 * A function to be called when the results of
 * gtk_clipboard_request_rich_text() are received, or when the request
 * fails.
 *
 * Since: 2.10
 */
82 83 84 85 86
typedef void (* GtkClipboardRichTextReceivedFunc) (GtkClipboard     *clipboard,
                                                   GdkAtom           format,
					           const guint8     *text,
                                                   gsize             length,
					           gpointer          data);
87 88 89 90 91

/**
 * GtkClipboardImageReceivedFunc:
 * @clipboard: the #GtkClipboard
 * @pixbuf: the received image
92 93
 * @data: (closure): the @user_data supplied to
 *   gtk_clipboard_request_image().
94 95 96 97 98 99
 *
 * A function to be called when the results of gtk_clipboard_request_image()
 * are received, or when the request fails.
 *
 * Since: 2.6
 */
100 101 102
typedef void (* GtkClipboardImageReceivedFunc)    (GtkClipboard     *clipboard,
						   GdkPixbuf        *pixbuf,
						   gpointer          data);
103

104 105 106 107 108 109 110 111 112 113 114 115 116
/**
 * GtkClipboardURIReceivedFunc:
 * @clipboard: the #GtkClipboard
 * @uris: (array zero-terminated=1): the received URIs
 * @data: (closure): the @user_data supplied to
 *   gtk_clipboard_request_uris().
 *
 * A function to be called when the results of
 * gtk_clipboard_request_uris() are received, or when the request
 * fails.
 *
 * Since: 2.14
 */
117 118 119
typedef void (* GtkClipboardURIReceivedFunc)      (GtkClipboard     *clipboard,
						   gchar           **uris,
						   gpointer          data);
120 121 122 123

/**
 * GtkClipboardTargetsReceivedFunc:
 * @clipboard: the #GtkClipboard
124 125
 * @atoms: (nullable) (array length=n_atoms): the supported targets,
 *   as array of #GdkAtom, or %NULL if retrieving the data failed.
126
 * @n_atoms: the length of the @atoms array.
127 128
 * @data: (closure): the @user_data supplied to
 *   gtk_clipboard_request_targets().
129 130 131 132 133 134
 *
 * A function to be called when the results of gtk_clipboard_request_targets()
 * are received, or when the request fails.
 *
 * Since: 2.4
 */
135 136 137 138
typedef void (* GtkClipboardTargetsReceivedFunc)  (GtkClipboard     *clipboard,
					           GdkAtom          *atoms,
						   gint              n_atoms,
					           gpointer          data);
139 140 141 142 143

/* Should these functions have GtkClipboard *clipboard as the first argument?
 * right now for ClearFunc, you may have trouble determining _which_ clipboard
 * was cleared, if you reuse your ClearFunc for multiple clipboards.
 */
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
/**
 * GtkClipboardGetFunc:
 * @clipboard: the #GtkClipboard
 * @selection_data: a #GtkSelectionData argument in which the requested
 *   data should be stored.
 * @info: the info field corresponding to the requested target from the
 *   #GtkTargetEntry array passed to gtk_clipboard_set_with_data() or
 *   gtk_clipboard_set_with_owner().
 * @user_data_or_owner: the @user_data argument passed to
 *   gtk_clipboard_set_with_data(), or the @owner argument passed to
 *   gtk_clipboard_set_with_owner()
 *
 * A function that will be called to provide the contents of the selection.
 * If multiple types of data were advertised, the requested type can
 * be determined from the @info parameter or by checking the target field
 * of @selection_data. If the data could successfully be converted into
 * then it should be stored into the @selection_data object by
 * calling gtk_selection_data_set() (or related functions such
 * as gtk_selection_data_set_text()). If no data is set, the requestor
 * will be informed that the attempt to get the data failed.
 */
165 166 167 168
typedef void (* GtkClipboardGetFunc)          (GtkClipboard     *clipboard,
					       GtkSelectionData *selection_data,
					       guint             info,
					       gpointer          user_data_or_owner);
169 170 171 172 173 174 175 176 177 178 179

/**
 * GtkClipboardClearFunc:
 * @clipboard: the #GtkClipboard
 * @user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(),
 *   or the @owner argument passed to gtk_clipboard_set_with_owner()
 *
 * A function that will be called when the contents of the clipboard are changed
 * or cleared. Once this has called, the @user_data_or_owner argument
 * will not be used again.
 */
180 181
typedef void (* GtkClipboardClearFunc)        (GtkClipboard     *clipboard,
					       gpointer          user_data_or_owner);
182

183
GDK_AVAILABLE_IN_ALL
Matthias Clasen's avatar
Matthias Clasen committed
184
GType         gtk_clipboard_get_type (void) G_GNUC_CONST;
185

186
GDK_AVAILABLE_IN_ALL
187 188
GtkClipboard *gtk_clipboard_get_for_display (GdkDisplay   *display,
					     GdkAtom       selection);
189
GDK_AVAILABLE_IN_ALL
190 191
GtkClipboard *gtk_clipboard_get             (GdkAtom       selection);

192 193 194
GDK_AVAILABLE_IN_3_16
GtkClipboard *gtk_clipboard_get_default     (GdkDisplay    *display);

195
GDK_AVAILABLE_IN_ALL
196 197
GdkDisplay   *gtk_clipboard_get_display     (GtkClipboard *clipboard);

198

199
GDK_AVAILABLE_IN_ALL
200 201 202 203 204 205
gboolean gtk_clipboard_set_with_data  (GtkClipboard          *clipboard,
				       const GtkTargetEntry  *targets,
				       guint                  n_targets,
				       GtkClipboardGetFunc    get_func,
				       GtkClipboardClearFunc  clear_func,
				       gpointer               user_data);
206
GDK_AVAILABLE_IN_ALL
207 208 209 210 211 212
gboolean gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
				       const GtkTargetEntry  *targets,
				       guint                  n_targets,
				       GtkClipboardGetFunc    get_func,
				       GtkClipboardClearFunc  clear_func,
				       GObject               *owner);
213
GDK_AVAILABLE_IN_ALL
214
GObject *gtk_clipboard_get_owner      (GtkClipboard          *clipboard);
215
GDK_AVAILABLE_IN_ALL
216
void     gtk_clipboard_clear          (GtkClipboard          *clipboard);
217
GDK_AVAILABLE_IN_ALL
218 219 220
void     gtk_clipboard_set_text       (GtkClipboard          *clipboard,
				       const gchar           *text,
				       gint                   len);
221
GDK_AVAILABLE_IN_ALL
222 223
void     gtk_clipboard_set_image      (GtkClipboard          *clipboard,
				       GdkPixbuf             *pixbuf);
224

225
GDK_AVAILABLE_IN_ALL
226 227 228 229
void gtk_clipboard_request_contents  (GtkClipboard                     *clipboard,
                                      GdkAtom                           target,
                                      GtkClipboardReceivedFunc          callback,
                                      gpointer                          user_data);
230
GDK_AVAILABLE_IN_ALL
231 232 233
void gtk_clipboard_request_text      (GtkClipboard                     *clipboard,
                                      GtkClipboardTextReceivedFunc      callback,
                                      gpointer                          user_data);
234
GDK_AVAILABLE_IN_ALL
235 236 237 238
void gtk_clipboard_request_rich_text (GtkClipboard                     *clipboard,
                                      GtkTextBuffer                    *buffer,
                                      GtkClipboardRichTextReceivedFunc  callback,
                                      gpointer                          user_data);
239
GDK_AVAILABLE_IN_ALL
240 241 242
void gtk_clipboard_request_image     (GtkClipboard                     *clipboard,
                                      GtkClipboardImageReceivedFunc     callback,
                                      gpointer                          user_data);
243
GDK_AVAILABLE_IN_ALL
244 245 246
void gtk_clipboard_request_uris      (GtkClipboard                     *clipboard,
                                      GtkClipboardURIReceivedFunc       callback,
                                      gpointer                          user_data);
247
GDK_AVAILABLE_IN_ALL
248 249 250 251
void gtk_clipboard_request_targets   (GtkClipboard                     *clipboard,
                                      GtkClipboardTargetsReceivedFunc   callback,
                                      gpointer                          user_data);

252
GDK_AVAILABLE_IN_ALL
253 254
GtkSelectionData *gtk_clipboard_wait_for_contents  (GtkClipboard  *clipboard,
                                                    GdkAtom        target);
255
GDK_AVAILABLE_IN_ALL
256
gchar *           gtk_clipboard_wait_for_text      (GtkClipboard  *clipboard);
257
GDK_AVAILABLE_IN_ALL
258 259 260
guint8 *          gtk_clipboard_wait_for_rich_text (GtkClipboard  *clipboard,
                                                    GtkTextBuffer *buffer,
                                                    GdkAtom       *format,
261
                                                    gsize         *length);
262
GDK_AVAILABLE_IN_ALL
263
GdkPixbuf *       gtk_clipboard_wait_for_image     (GtkClipboard  *clipboard);
264
GDK_AVAILABLE_IN_ALL
265
gchar **          gtk_clipboard_wait_for_uris      (GtkClipboard  *clipboard);
266
GDK_AVAILABLE_IN_ALL
267 268 269 270
gboolean          gtk_clipboard_wait_for_targets   (GtkClipboard  *clipboard,
                                                    GdkAtom      **targets,
                                                    gint          *n_targets);

271
GDK_AVAILABLE_IN_ALL
272
gboolean gtk_clipboard_wait_is_text_available      (GtkClipboard  *clipboard);
273
GDK_AVAILABLE_IN_ALL
274 275
gboolean gtk_clipboard_wait_is_rich_text_available (GtkClipboard  *clipboard,
                                                    GtkTextBuffer *buffer);
276
GDK_AVAILABLE_IN_ALL
277
gboolean gtk_clipboard_wait_is_image_available     (GtkClipboard  *clipboard);
278
GDK_AVAILABLE_IN_ALL
279
gboolean gtk_clipboard_wait_is_uris_available      (GtkClipboard  *clipboard);
280
GDK_AVAILABLE_IN_ALL
281 282
gboolean gtk_clipboard_wait_is_target_available    (GtkClipboard  *clipboard,
                                                    GdkAtom        target);
283

284

285
GDK_AVAILABLE_IN_ALL
Anders Carlsson's avatar
Anders Carlsson committed
286 287 288
void gtk_clipboard_set_can_store (GtkClipboard         *clipboard,
				  const GtkTargetEntry *targets,
				  gint                  n_targets);
289

290
GDK_AVAILABLE_IN_ALL
291
void gtk_clipboard_store         (GtkClipboard   *clipboard);
292

293 294 295
/* private */
void     _gtk_clipboard_handle_event    (GdkEventOwnerChange *event);

296
void     _gtk_clipboard_store_all       (void);
297

298
G_END_DECLS
299

300
#endif /* __GTK_CLIPBOARD_H__ */