libs/gtkmm2/gtk/src/clipboard.hg

   1 /* $Id: clipboard.hg,v 1.17 2006/06/13 17:16:26 murrayc Exp $ */
   2
   3 /* clipboard.h
   4  *
   5  * Copyright (C) 2002 The gtkmm Development Team
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the Free
  19  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20  */
  21
  22 #include <gdkmm/display.h>
  23 #include <gdkmm/pixbuf.h>
  24 #include <gtkmm/targetentry.h>
  25 #include <gtkmm/selectiondata.h>
  26 #include <glibmm/object.h>
  27 #include <glibmm/containers.h>
  28
  29 _DEFS(gtkmm,gtk)
  30 _PINCLUDE(glibmm/private/object_p.h)
  31
  32
  33 namespace Gtk
  34 {
  35
  36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  37 class TextBuffer;
  38 #endif //DOXYGEN_SHOULD_SKIP_THIS
  39
  40 /** The Clipboard object represents a clipboard of data shared between different processes or between
  41  * different widgets in the same process. Each clipboard is identified by a name encoded as a GdkAtom. *
  42  * (Conversion to and from strings can be done with gdk_atom_intern() and gdk_atom_name().) The default
  43  * clipboard corresponds to the "CLIPBOARD" atom; another commonly used clipboard is the "PRIMARY" clipboard,
  44  * which, in X, traditionally contains the currently selected text.
  45  *
  46  * To support having a number of different formats on the clipboard at the same time, the clipboard mechanism
  47  * allows providing callbacks instead of the actual data. When you set the contents of the clipboard, you can
  48  * either supply the data directly (via functions like set_text()), or you can supply a callback
  49  * to be called at a later time when the data is needed (via set().) Providing a callback also avoids having to
  50  * make copies of the data when it is not needed.
  51  *
  52  * Requesting the data from the clipboard is essentially asynchronous. If the contents of the clipboard are
  53  * provided within the same process, then a direct function call will be made to retrieve the data, but if they
  54  * are provided by another process, then the data needs to be retrieved from the other process, which may take
  55  * some time. To avoid blocking the user interface, the call to request the selection, request_contents() takes
  56  * a callback that will be called when the contents are received (or when the request fails.) If you don't want
  57  * to deal with providing a separate callback, you can also use wait_for_contents(). This runs the
  58  * GLib main loop recursively waiting for the contents. This can simplify the code flow, but you still have to
  59  * be aware that other callbacks in your program can be called while this recursive mainloop is running.
  60  *
  61  * Along with the functions to get the clipboard contents as an arbitrary data chunk, there are also functions
  62  * to retrieve it as text, request_text() and wait_for_text(). These functions take
  63  * care of determining which formats are advertised by the clipboard provider, asking for the clipboard in the
  64  * best available format and converting the results into the UTF-8 encoding.
  65  */
  66 class Clipboard : public Glib::Object
  67 {
  68    _CLASS_GOBJECT(Clipboard, GtkClipboard, GTK_CLIPBOARD, Glib::Object, GObject)
  69 public:
  70
  71   _WRAP_METHOD(static Glib::RefPtr<Clipboard> get(GdkAtom selection = GDK_SELECTION_CLIPBOARD), gtk_clipboard_get, refreturn)
  72   _WRAP_METHOD(static Glib::RefPtr<Clipboard> get_for_display(const Glib::RefPtr<Gdk::Display>& display, GdkAtom selection = GDK_SELECTION_CLIPBOARD), gtk_clipboard_get_for_display, refreturn)
  73
  74   _WRAP_METHOD(Glib::RefPtr<Gdk::Display> get_display(), gtk_clipboard_get_display, refreturn)
  75   _WRAP_METHOD(Glib::RefPtr<const Gdk::Display> get_display() const, gtk_clipboard_get_display, refreturn, constversion)
  76
  77   /// For instance: void on_get(Gtk::SelectionData& selection_data, guint info);
  78   typedef sigc::slot<void, SelectionData&, guint> SlotGet;
  79
  80   /// For instance: void on_clear();
  81   typedef sigc::slot<void> SlotClear;
  82
  83  /** Virtually sets the contents of the specified clipboard by providing
  84   * a list of supported formats for the clipboard data and a function
  85   * to call to get the actual data when it is requested.
  86   *
  87   * @param targets Information about the available forms for the clipboard data.
  88   * @param slot_get method to call to get the actual clipboard data.
  89   * @param slot_clear When the clipboard contents are set again, this method will
  90   *              be called, and slot_get will not be subsequently called.
  91   *
  92   * @return true if setting the clipboard data succeeded. If setting
  93   *               the clipboard data failed then the provided callback methods
  94   *               will be ignored.
  95   */
  96   bool set(const ArrayHandle_TargetEntry& targets, const SlotGet& slot_get, const SlotClear& slot_clear);
  97   _IGNORE(gtk_clipboard_set_with_owner, gtk_clipboard_set_with_data)
  98
  99   _WRAP_METHOD(Glib::RefPtr<Glib::Object> get_owner(), gtk_clipboard_get_owner, refreturn)
 100   _WRAP_METHOD(Glib::RefPtr<const Glib::Object> get_owner() const, gtk_clipboard_get_owner, refreturn, constversion)
 101
 102   /**
 103    * Clears the contents of the clipboard. Generally this should only
 104    * be called between the time you call set()
 105    * and when the slot_clear you supplied is called. Otherwise, the
 106    * clipboard may be owned by someone else.
 107    */
 108   _WRAP_METHOD(void clear(), gtk_clipboard_clear)
 109
 110   /**
 111    * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
 112    * make a copy of the text and take responsibility for responding
 113    * for requests for the text, and for converting the text into
 114    * the requested format.
 115    *
 116    * @param text  A UTF-8 string.
 117    *
 118    */
 119   void set_text(const Glib::ustring& text);
 120   _IGNORE(gtk_clipboard_set_text)
 121
 122   _WRAP_METHOD(void set_image(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf), gtk_clipboard_set_image)
 123
 124   /// For instance: void on_received(const SelectionData& selection_data);
 125   typedef sigc::slot<void, const SelectionData&> SlotReceived;
 126
 127   /** Requests the contents of clipboard as the given target.
 128    * When the results of the result are later received the supplied callback
 129    * will be called.
 130    *
 131    * @param target The form into which the clipboard
 132    *             owner should convert the selection.
 133    * @param slot  A function to call when the results are received
 134    *             (or the retrieval fails). If the retrieval fails
 135    *             the length field of selection_data will be
 136    *             negative.
 137    **/
 138   void request_contents(const Glib::ustring& target, const SlotReceived& slot);
 139   _IGNORE(gtk_clipboard_request_contents)
 140
 141   /// For instance: void on_text_received(const Glib::ustring& text);
 142   typedef sigc::slot<void, const Glib::ustring&> SlotTextReceived;
 143
 144   /** Requests the contents of the clipboard as text. When the text is
 145    * later received, it will be converted to UTF-8 if necessary, and
 146    * slot will be called.
 147    *
 148    * The text parameter to slot will contain the resulting text if
 149    * the request succeeded, or will be empty if it failed. This could happen for
 150    * various reasons, in particular if the clipboard was empty or if the
 151    * contents of the clipboard could not be converted into text form.
 152    *
 153    * @param slot:  a function to call when the text is received,
 154    *             or the retrieval fails. (It will always be called
 155    *             one way or the other.)
 156    */
 157   void request_text(const SlotTextReceived& slot);
 158   _IGNORE(gtk_clipboard_request_text)
 159
 160   /// For instance: void on_rich_text_received(const Glib::ustring& format, const std::string& text);
 161   typedef sigc::slot<void, const Glib::ustring& , const std::string&> SlotRichTextReceived;
 162
 163   /** Requests the contents of the clipboard as rich text. When the rich text is later received,
 164    * callback will be called.
 165    *
 166    * The text parameter to the callback will contain the resulting rich text if the request succeeded, or
 167    * an empty string if it failed. This function can fail for various reasons, in particular if the
 168    * clipboard was empty or if the contents of the clipboard could not be converted into rich text form.
 169    *
 170    *
 171    * @param slot:  a function to call when the text is received,
 172    *             or the retrieval fails. (It will always be called
 173    *             one way or the other.)
 174    */
 175   void request_rich_text(const Glib::RefPtr<TextBuffer>& buffer, const SlotRichTextReceived& slot);
 176   _IGNORE(gtk_clipboard_request_rich_text)
 177
 178
 179   /// For instance: void on_image_received(const Glib::RefPtr<Gdk::Pixbuf>& text);
 180   typedef sigc::slot<void, const Glib::RefPtr<Gdk::Pixbuf>&> SlotImageReceived;
 181
 182   /** Requests the contents of the clipboard as image. When the image is
 183    * later received, it will be converted to a Gdk::Pixbuf.
 184    * This function waits for
 185    * the data to be received using the main loop, so events,
 186    * timeouts, etc, may be dispatched during the wait.
 187    *
 188    * The pixbuf parameter to slot will contain the resulting pixbuf if
 189    * the request succeeded, or will be empty if it failed. This could happen for
 190    * various reasons, in particular if the clipboard was empty or if the
 191    * contents of the clipboard could not be converted into image form.
 192    *
 193    * @param slot:  a function to call when the text is received,
 194    *             or the retrieval fails. (It will always be called
 195    *             one way or the other.)
 196    */
 197   void request_image(const SlotImageReceived& slot);
 198   _IGNORE(gtk_clipboard_request_image)
 199
 200   /// For instance: void on_targetsreceived(const Glib::StringArrayHandle& targets);
 201   typedef sigc::slot<void, const Glib::StringArrayHandle&> SlotTargetsReceived;
 202
 203   /** Requests the contents of the clipboard as list of supported targets.
 204    * When the list is later received, callback will be called.
 205    *
 206    * The targets parameter to slot will contain the resulting targets if
 207    * the request succeeded.
 208    *
 209    * @param slot a function to call when the targets are received,
 210    *             or the retrieval fails. (It will always be called
 211    *             one way or the other.) Remember that Glib::StringArrayHandle
 212    *             is an intermediate type, so you should convert it to a
 213    *             standard C++ container.
 214    *
 215    * @newin2p4
 216    */
 217   void request_targets(const SlotTargetsReceived& slot);
 218   _IGNORE(gtk_clipboard_request_targets)
 219
 220   /**
 221    * Requests the contents of the clipboard using the given target.
 222    * This function waits for the data to be received using the main
 223    * loop, so events, timeouts, etc, may be dispatched during the wait.
 224    *
 225    * @param target The form into which the clipboard owner should convert the selection.
 226    *
 227    * @return A SelectionData object, which will be invalid if retrieving the given target failed.
 228    */
 229   SelectionData wait_for_contents(const Glib::ustring& target) const;
 230   _IGNORE(gtk_clipboard_wait_for_contents)
 231
 232   _WRAP_METHOD(Glib::ustring wait_for_text() const, gtk_clipboard_wait_for_text)
 233
 234   std::string wait_for_rich_text(const Glib::RefPtr<TextBuffer>& buffer, std::string& format);
 235   _IGNORE(gtk_clipboard_wait_for_rich_text)
 236
 237   //Maybe the result should be const, but constness is not so clear-cut here. murrayc
 238   _WRAP_METHOD(Glib::RefPtr<Gdk::Pixbuf> wait_for_image() const, gtk_clipboard_wait_for_image)
 239
 240   _WRAP_METHOD(bool wait_is_text_available() const, gtk_clipboard_wait_is_text_available)
 241   _WRAP_METHOD(bool wait_is_rich_text_available(const Glib::RefPtr<TextBuffer>& buffer) const, gtk_clipboard_wait_is_rich_text_available)
 242   _WRAP_METHOD(bool wait_is_image_available() const, gtk_clipboard_wait_is_image_available)
 243   _WRAP_METHOD(bool wait_is_target_available(const Glib::ustring& target), gtk_clipboard_wait_is_target_available)
 244
 245   /** Returns a list of targets that are present on the clipboard.
 246    * This function waits for the data to be received using the main
 247    * loop, so events, timeouts, etc, may be dispatched during the wait.
 248    *
 249    * @result targets: The targets.
 250    *
 251    * @newin2p4
 252    */
 253   Glib::StringArrayHandle wait_for_targets() const;
 254   _IGNORE(gtk_clipboard_wait_for_targets)
 255
 256   /** Hints that the clipboard data should be stored somewhere when the application exits or when store()
 257    * is called.
 258    *
 259    * This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform
 260    * dependent, see Gdk::Display::store_clipboard() for more information.
 261    *
 262    * @param targets Array containing information about which forms should be stored.
 263    */
 264   void set_can_store(const ArrayHandle_TargetEntry& targets);
 265
 266   /** Hints that all forms of clipboard data should be stored somewhere when the application exits or when store()
 267    * is called.
 268    *
 269    * This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform
 270    * dependent, see Gdk::Display::store_clipboard() for more information.
 271    */
 272   void set_can_store();
 273   _IGNORE(void gtk_clipboard_set_can_store)
 274
 275   _WRAP_METHOD(void store(), gtk_clipboard_store)
 276
 277   //We use no_default_handler because this signal was added and we don't want to break the ABI by adding a virtual function.
 278   _WRAP_SIGNAL(void owner_change(GdkEventOwnerChange* event), "owner_change", no_default_handler)
 279
 280 };
 281
 282 } /* namespace Gtk */
 283