Pileus Git - ~andy/gtk/blob - gtk/gtkclipboard.h

   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
  29 G_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: the @user_data supplied to gtk_clipboard_request_contents().
  42  *
  43  * A function to be called when the results of gtk_clipboard_request_contents()
  44  * are received, or when the request fails.
  45  */
  46 typedef void (* GtkClipboardReceivedFunc)         (GtkClipboard     *clipboard,
  47                                                    GtkSelectionData *selection_data,
  48                                                    gpointer          data);
  49
  50 /**
  51  * GtkClipboardTextReceivedFunc:
  52  * @clipboard: the #GtkClipboard
  53  * @text: the text received, as a UTF-8 encoded string, or %NULL
  54  *   if retrieving the data failed.
  55  * @data: the @user_data supplied to gtk_clipboard_request_text().
  56  *
  57  * A function to be called when the results of gtk_clipboard_request_text()
  58  * are received, or when the request fails.
  59  */
  60 typedef void (* GtkClipboardTextReceivedFunc)     (GtkClipboard     *clipboard,
  61                                                    const gchar      *text,
  62                                                    gpointer          data);
  63
  64 typedef void (* GtkClipboardRichTextReceivedFunc) (GtkClipboard     *clipboard,
  65                                                    GdkAtom           format,
  66                                                    const guint8     *text,
  67                                                    gsize             length,
  68                                                    gpointer          data);
  69
  70 /**
  71  * GtkClipboardImageReceivedFunc:
  72  * @clipboard: the #GtkClipboard
  73  * @pixbuf: the received image
  74  * @data: the @user_data supplied to gtk_clipboard_request_image().
  75  *
  76  * A function to be called when the results of gtk_clipboard_request_image()
  77  * are received, or when the request fails.
  78  *
  79  * Since: 2.6
  80  */
  81 typedef void (* GtkClipboardImageReceivedFunc)    (GtkClipboard     *clipboard,
  82                                                    GdkPixbuf        *pixbuf,
  83                                                    gpointer          data);
  84
  85 typedef void (* GtkClipboardURIReceivedFunc)      (GtkClipboard     *clipboard,
  86                                                    gchar           **uris,
  87                                                    gpointer          data);
  88
  89 /**
  90  * GtkClipboardTargetsReceivedFunc:
  91  * @clipboard: the #GtkClipboard
  92  * @atoms: the supported targets, as array of #GdkAtom, or %NULL
  93  *   if retrieving the data failed.
  94  * @n_atoms: the length of the @atoms array.
  95  * @data: the @user_data supplied to gtk_clipboard_request_targets().
  96  *
  97  * A function to be called when the results of gtk_clipboard_request_targets()
  98  * are received, or when the request fails.
  99  *
 100  * Since: 2.4
 101  */
 102 typedef void (* GtkClipboardTargetsReceivedFunc)  (GtkClipboard     *clipboard,
 103                                                    GdkAtom          *atoms,
 104                                                    gint              n_atoms,
 105                                                    gpointer          data);
 106
 107 /* Should these functions have GtkClipboard *clipboard as the first argument?
 108  * right now for ClearFunc, you may have trouble determining _which_ clipboard
 109  * was cleared, if you reuse your ClearFunc for multiple clipboards.
 110  */
 111 /**
 112  * GtkClipboardGetFunc:
 113  * @clipboard: the #GtkClipboard
 114  * @selection_data: a #GtkSelectionData argument in which the requested
 115  *   data should be stored.
 116  * @info: the info field corresponding to the requested target from the
 117  *   #GtkTargetEntry array passed to gtk_clipboard_set_with_data() or
 118  *   gtk_clipboard_set_with_owner().
 119  * @user_data_or_owner: the @user_data argument passed to
 120  *   gtk_clipboard_set_with_data(), or the @owner argument passed to
 121  *   gtk_clipboard_set_with_owner()
 122  *
 123  * A function that will be called to provide the contents of the selection.
 124  * If multiple types of data were advertised, the requested type can
 125  * be determined from the @info parameter or by checking the target field
 126  * of @selection_data. If the data could successfully be converted into
 127  * then it should be stored into the @selection_data object by
 128  * calling gtk_selection_data_set() (or related functions such
 129  * as gtk_selection_data_set_text()). If no data is set, the requestor
 130  * will be informed that the attempt to get the data failed.
 131  */
 132 typedef void (* GtkClipboardGetFunc)          (GtkClipboard     *clipboard,
 133                                                GtkSelectionData *selection_data,
 134                                                guint             info,
 135                                                gpointer          user_data_or_owner);
 136
 137 /**
 138  * GtkClipboardClearFunc:
 139  * @clipboard: the #GtkClipboard
 140  * @user_data_or_owner: the @user_data argument passed to gtk_clipboard_set_with_data(),
 141  *   or the @owner argument passed to gtk_clipboard_set_with_owner()
 142  *
 143  * A function that will be called when the contents of the clipboard are changed
 144  * or cleared. Once this has called, the @user_data_or_owner argument
 145  * will not be used again.
 146  */
 147 typedef void (* GtkClipboardClearFunc)        (GtkClipboard     *clipboard,
 148                                                gpointer          user_data_or_owner);
 149
 150 GType         gtk_clipboard_get_type (void) G_GNUC_CONST;
 151
 152 GtkClipboard *gtk_clipboard_get_for_display (GdkDisplay   *display,
 153                                              GdkAtom       selection);
 154 #ifndef GDK_MULTIHEAD_SAFE
 155 GtkClipboard *gtk_clipboard_get             (GdkAtom       selection);
 156 #endif
 157
 158 GdkDisplay   *gtk_clipboard_get_display     (GtkClipboard *clipboard);
 159
 160
 161 gboolean gtk_clipboard_set_with_data  (GtkClipboard          *clipboard,
 162                                        const GtkTargetEntry  *targets,
 163                                        guint                  n_targets,
 164                                        GtkClipboardGetFunc    get_func,
 165                                        GtkClipboardClearFunc  clear_func,
 166                                        gpointer               user_data);
 167 gboolean gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
 168                                        const GtkTargetEntry  *targets,
 169                                        guint                  n_targets,
 170                                        GtkClipboardGetFunc    get_func,
 171                                        GtkClipboardClearFunc  clear_func,
 172                                        GObject               *owner);
 173 GObject *gtk_clipboard_get_owner      (GtkClipboard          *clipboard);
 174 void     gtk_clipboard_clear          (GtkClipboard          *clipboard);
 175 void     gtk_clipboard_set_text       (GtkClipboard          *clipboard,
 176                                        const gchar           *text,
 177                                        gint                   len);
 178 void     gtk_clipboard_set_image      (GtkClipboard          *clipboard,
 179                                        GdkPixbuf             *pixbuf);
 180
 181 void gtk_clipboard_request_contents  (GtkClipboard                     *clipboard,
 182                                       GdkAtom                           target,
 183                                       GtkClipboardReceivedFunc          callback,
 184                                       gpointer                          user_data);
 185 void gtk_clipboard_request_text      (GtkClipboard                     *clipboard,
 186                                       GtkClipboardTextReceivedFunc      callback,
 187                                       gpointer                          user_data);
 188 void gtk_clipboard_request_rich_text (GtkClipboard                     *clipboard,
 189                                       GtkTextBuffer                    *buffer,
 190                                       GtkClipboardRichTextReceivedFunc  callback,
 191                                       gpointer                          user_data);
 192 void gtk_clipboard_request_image     (GtkClipboard                     *clipboard,
 193                                       GtkClipboardImageReceivedFunc     callback,
 194                                       gpointer                          user_data);
 195 void gtk_clipboard_request_uris      (GtkClipboard                     *clipboard,
 196                                       GtkClipboardURIReceivedFunc       callback,
 197                                       gpointer                          user_data);
 198 void gtk_clipboard_request_targets   (GtkClipboard                     *clipboard,
 199                                       GtkClipboardTargetsReceivedFunc   callback,
 200                                       gpointer                          user_data);
 201
 202 GtkSelectionData *gtk_clipboard_wait_for_contents  (GtkClipboard  *clipboard,
 203                                                     GdkAtom        target);
 204 gchar *           gtk_clipboard_wait_for_text      (GtkClipboard  *clipboard);
 205 guint8 *          gtk_clipboard_wait_for_rich_text (GtkClipboard  *clipboard,
 206                                                     GtkTextBuffer *buffer,
 207                                                     GdkAtom       *format,
 208                                                     gsize         *length);
 209 GdkPixbuf *       gtk_clipboard_wait_for_image     (GtkClipboard  *clipboard);
 210 gchar **          gtk_clipboard_wait_for_uris      (GtkClipboard  *clipboard);
 211 gboolean          gtk_clipboard_wait_for_targets   (GtkClipboard  *clipboard,
 212                                                     GdkAtom      **targets,
 213                                                     gint          *n_targets);
 214
 215 gboolean gtk_clipboard_wait_is_text_available      (GtkClipboard  *clipboard);
 216 gboolean gtk_clipboard_wait_is_rich_text_available (GtkClipboard  *clipboard,
 217                                                     GtkTextBuffer *buffer);
 218 gboolean gtk_clipboard_wait_is_image_available     (GtkClipboard  *clipboard);
 219 gboolean gtk_clipboard_wait_is_uris_available      (GtkClipboard  *clipboard);
 220 gboolean gtk_clipboard_wait_is_target_available    (GtkClipboard  *clipboard,
 221                                                     GdkAtom        target);
 222
 223
 224 void gtk_clipboard_set_can_store (GtkClipboard         *clipboard,
 225                                   const GtkTargetEntry *targets,
 226                                   gint                  n_targets);
 227
 228 void gtk_clipboard_store         (GtkClipboard   *clipboard);
 229
 230 /* private */
 231 void     _gtk_clipboard_handle_event    (GdkEventOwnerChange *event);
 232
 233 void     _gtk_clipboard_store_all       (void);
 234
 235 G_END_DECLS
 236
 237 #endif /* __GTK_CLIPBOARD_H__ */