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