libs/gtkmm2/gtk/gtkmm/clipboard.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_CLIPBOARD_H
   4 #define _GTKMM_CLIPBOARD_H
   5
   6
   7 #include <glibmm.h>
   8
   9 /* $Id$ */
  10
  11 /* clipboard.h
  12  *
  13  * Copyright (C) 2002 The gtkmm Development Team
  14  *
  15  * This library is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU Library General Public
  17  * License as published by the Free Software Foundation; either
  18  * version 2 of the License, or (at your option) any later version.
  19  *
  20  * This library is distributed in the hope that it will be useful,
  21  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  22  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  23  * Library General Public License for more details.
  24  *
  25  * You should have received a copy of the GNU Library General Public
  26  * License along with this library; if not, write to the Free
  27  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  28  */
  29
  30 #include <gdkmm/display.h>
  31 #include <gdkmm/pixbuf.h>
  32 #include <gtkmm/targetentry.h>
  33 #include <gtkmm/selectiondata.h>
  34 #include <glibmm/object.h>
  35 #include <glibmm/containers.h>
  36
  37
  38 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  39 typedef struct _GtkClipboard GtkClipboard;
  40 typedef struct _GtkClipboardClass GtkClipboardClass;
  41 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  42
  43
  44 namespace Gtk
  45 { class Clipboard_Class; } // namespace Gtk
  46 namespace Gtk
  47 {
  48
  49 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  50 class TextBuffer;
  51 #endif //DOXYGEN_SHOULD_SKIP_THIS
  52
  53 /** The Clipboard object represents a clipboard of data shared between different processes or between
  54  * different widgets in the same process. Each clipboard is identified by a name encoded as a GdkAtom. *
  55  * (Conversion to and from strings can be done with gdk_atom_intern() and gdk_atom_name().) The default
  56  * clipboard corresponds to the "CLIPBOARD" atom; another commonly used clipboard is the "PRIMARY" clipboard,
  57  * which, in X, traditionally contains the currently selected text.
  58  *
  59  * To support having a number of different formats on the clipboard at the same time, the clipboard mechanism
  60  * allows providing callbacks instead of the actual data. When you set the contents of the clipboard, you can
  61  * either supply the data directly (via functions like set_text()), or you can supply a callback
  62  * to be called at a later time when the data is needed (via set().) Providing a callback also avoids having to
  63  * make copies of the data when it is not needed.
  64  *
  65  * Requesting the data from the clipboard is essentially asynchronous. If the contents of the clipboard are
  66  * provided within the same process, then a direct function call will be made to retrieve the data, but if they
  67  * are provided by another process, then the data needs to be retrieved from the other process, which may take
  68  * some time. To avoid blocking the user interface, the call to request the selection, request_contents() takes
  69  * a callback that will be called when the contents are received (or when the request fails.) If you don't want
  70  * to deal with providing a separate callback, you can also use wait_for_contents(). This runs the
  71  * GLib main loop recursively waiting for the contents. This can simplify the code flow, but you still have to
  72  * be aware that other callbacks in your program can be called while this recursive mainloop is running.
  73  *
  74  * Along with the functions to get the clipboard contents as an arbitrary data chunk, there are also functions
  75  * to retrieve it as text, request_text() and wait_for_text(). These functions take
  76  * care of determining which formats are advertised by the clipboard provider, asking for the clipboard in the
  77  * best available format and converting the results into the UTF-8 encoding.
  78  */
  79
  80 class Clipboard : public Glib::Object
  81 {
  82
  83 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  84
  85 public:
  86   typedef Clipboard CppObjectType;
  87   typedef Clipboard_Class CppClassType;
  88   typedef GtkClipboard BaseObjectType;
  89   typedef GtkClipboardClass BaseClassType;
  90
  91 private:  friend class Clipboard_Class;
  92   static CppClassType clipboard_class_;
  93
  94 private:
  95   // noncopyable
  96   Clipboard(const Clipboard&);
  97   Clipboard& operator=(const Clipboard&);
  98
  99 protected:
 100   explicit Clipboard(const Glib::ConstructParams& construct_params);
 101   explicit Clipboard(GtkClipboard* castitem);
 102
 103 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 104
 105 public:
 106   virtual ~Clipboard();
 107
 108 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 109   static GType get_type()      G_GNUC_CONST;
 110   static GType get_base_type() G_GNUC_CONST;
 111 #endif
 112
 113   ///Provides access to the underlying C GObject.
 114   GtkClipboard*       gobj()       { return reinterpret_cast<GtkClipboard*>(gobject_); }
 115
 116   ///Provides access to the underlying C GObject.
 117   const GtkClipboard* gobj() const { return reinterpret_cast<GtkClipboard*>(gobject_); }
 118
 119   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 120   GtkClipboard* gobj_copy();
 121
 122 private:
 123
 124 public:
 125
 126
 127   /** Return value: the appropriate clipboard object. If no
 128    * @param selection A Gdk::Atom which identifies the clipboard
 129    * to use.
 130    * @return The appropriate clipboard object. If no
 131    * clipboard already exists, a new one will
 132    * be created. Once a clipboard object has
 133    * been created, it is persistent and, since
 134    * it is owned by GTK+, must not be freed or
 135    * unrefd.
 136    */
 137   static Glib::RefPtr<Clipboard> get(GdkAtom selection = GDK_SELECTION_CLIPBOARD);
 138
 139   /** Return value: the appropriate clipboard object. If no
 140    * @param display The display for which the clipboard is to be retrieved or created.
 141    * @param selection A Gdk::Atom which identifies the clipboard
 142    * to use.
 143    * @return The appropriate clipboard object. If no
 144    * clipboard already exists, a new one will
 145    * be created. Once a clipboard object has
 146    * been created, it is persistent and, since
 147    * it is owned by GTK+, must not be freed or
 148    * unrefd.
 149    *
 150    * @newin2p2.
 151    */
 152   static Glib::RefPtr<Clipboard> get_for_display(const Glib::RefPtr<Gdk::Display>& display, GdkAtom selection = GDK_SELECTION_CLIPBOARD);
 153
 154
 155   /** Gets the Gdk::Display associated with @a clipboard
 156    * @return The Gdk::Display associated with @a clipboard
 157    *
 158    * @newin2p2.
 159    */
 160   Glib::RefPtr<Gdk::Display> get_display();
 161
 162   /** Gets the Gdk::Display associated with @a clipboard
 163    * @return The Gdk::Display associated with @a clipboard
 164    *
 165    * @newin2p2.
 166    */
 167   Glib::RefPtr<const Gdk::Display> get_display() const;
 168
 169   /// For instance: void on_get(Gtk::SelectionData& selection_data, guint info);
 170   typedef sigc::slot<void, SelectionData&, guint> SlotGet;
 171
 172   /// For instance: void on_clear();
 173   typedef sigc::slot<void> SlotClear;
 174
 175  /** Virtually sets the contents of the specified clipboard by providing
 176   * a list of supported formats for the clipboard data and a function
 177   * to call to get the actual data when it is requested.
 178   *
 179   * @param targets Information about the available forms for the clipboard data.
 180   * @param slot_get method to call to get the actual clipboard data.
 181   * @param slot_clear When the clipboard contents are set again, this method will
 182   *              be called, and slot_get will not be subsequently called.
 183   *
 184   * @return true if setting the clipboard data succeeded. If setting
 185   *               the clipboard data failed then the provided callback methods
 186   *               will be ignored.
 187   */
 188   bool set(const ArrayHandle_TargetEntry& targets, const SlotGet& slot_get, const SlotClear& slot_clear);
 189
 190
 191   /** If the clipboard contents callbacks were set with
 192    * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
 193    * gtk_clipboard_clear() has not subsequently called, returns the owner set
 194    * by gtk_clipboard_set_with_owner().
 195    * @return The owner of the clipboard, if any; otherwise <tt>0</tt>.
 196    */
 197   Glib::RefPtr<Glib::Object> get_owner();
 198
 199   /** If the clipboard contents callbacks were set with
 200    * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or
 201    * gtk_clipboard_clear() has not subsequently called, returns the owner set
 202    * by gtk_clipboard_set_with_owner().
 203    * @return The owner of the clipboard, if any; otherwise <tt>0</tt>.
 204    */
 205   Glib::RefPtr<const Glib::Object> get_owner() const;
 206
 207   /**
 208    * Clears the contents of the clipboard. Generally this should only
 209    * be called between the time you call set()
 210    * and when the slot_clear you supplied is called. Otherwise, the
 211    * clipboard may be owned by someone else.
 212    */
 213
 214   /** Clears the contents of the clipboard. Generally this should only
 215    * be called between the time you call gtk_clipboard_set_with_owner()
 216    * or gtk_clipboard_set_with_data(),
 217    * and when the @a clear_func  you supplied is called. Otherwise, the
 218    * clipboard may be owned by someone else.
 219    */
 220   void clear();
 221
 222   /**
 223    * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
 224    * make a copy of the text and take responsibility for responding
 225    * for requests for the text, and for converting the text into
 226    * the requested format.
 227    *
 228    * @param text  A UTF-8 string.
 229    *
 230    */
 231   void set_text(const Glib::ustring& text);
 232
 233
 234   /** Sets the contents of the clipboard to the given Gdk::Pixbuf.
 235    * GTK+ will take responsibility for responding for requests
 236    * for the image, and for converting the image into the
 237    * requested format.
 238    *
 239    * @newin2p6
 240    * @param pixbuf A Gdk::Pixbuf.
 241    */
 242   void set_image(const Glib::RefPtr<Gdk::Pixbuf>& pixbuf);
 243
 244   /// For instance: void on_received(const SelectionData& selection_data);
 245   typedef sigc::slot<void, const SelectionData&> SlotReceived;
 246
 247   /** Requests the contents of clipboard as the given target.
 248    * When the results of the result are later received the supplied callback
 249    * will be called.
 250    *
 251    * @param target The form into which the clipboard
 252    *             owner should convert the selection.
 253    * @param slot  A function to call when the results are received
 254    *             (or the retrieval fails). If the retrieval fails
 255    *             the length field of selection_data will be
 256    *             negative.
 257    **/
 258   void request_contents(const Glib::ustring& target, const SlotReceived& slot);
 259
 260
 261   /// For instance: void on_text_received(const Glib::ustring& text);
 262   typedef sigc::slot<void, const Glib::ustring&> SlotTextReceived;
 263
 264   /** Requests the contents of the clipboard as text. When the text is
 265    * later received, it will be converted to UTF-8 if necessary, and
 266    * slot will be called.
 267    *
 268    * The text parameter to slot will contain the resulting text if
 269    * the request succeeded, or will be empty if it failed. This could happen for
 270    * various reasons, in particular if the clipboard was empty or if the
 271    * contents of the clipboard could not be converted into text form.
 272    *
 273    * @param slot:  a function to call when the text is received,
 274    *             or the retrieval fails. (It will always be called
 275    *             one way or the other.)
 276    */
 277   void request_text(const SlotTextReceived& slot);
 278
 279
 280   /// For instance: void on_rich_text_received(const Glib::ustring& format, const std::string& text);
 281   typedef sigc::slot<void, const Glib::ustring& , const std::string&> SlotRichTextReceived;
 282
 283   /** Requests the contents of the clipboard as rich text. When the rich text is later received,
 284    * callback will be called.
 285    *
 286    * The text parameter to the callback will contain the resulting rich text if the request succeeded, or
 287    * an empty string if it failed. This function can fail for various reasons, in particular if the
 288    * clipboard was empty or if the contents of the clipboard could not be converted into rich text form.
 289    *
 290    *
 291    * @param slot:  a function to call when the text is received,
 292    *             or the retrieval fails. (It will always be called
 293    *             one way or the other.)
 294    */
 295   void request_rich_text(const Glib::RefPtr<TextBuffer>& buffer, const SlotRichTextReceived& slot);
 296
 297
 298   /// For instance: void on_image_received(const Glib::RefPtr<Gdk::Pixbuf>& text);
 299   typedef sigc::slot<void, const Glib::RefPtr<Gdk::Pixbuf>&> SlotImageReceived;
 300
 301   /** Requests the contents of the clipboard as image. When the image is
 302    * later received, it will be converted to a Gdk::Pixbuf.
 303    * This function waits for
 304    * the data to be received using the main loop, so events,
 305    * timeouts, etc, may be dispatched during the wait.
 306    *
 307    * The pixbuf parameter to slot will contain the resulting pixbuf if
 308    * the request succeeded, or will be empty if it failed. This could happen for
 309    * various reasons, in particular if the clipboard was empty or if the
 310    * contents of the clipboard could not be converted into image form.
 311    *
 312    * @param slot:  a function to call when the text is received,
 313    *             or the retrieval fails. (It will always be called
 314    *             one way or the other.)
 315    */
 316   void request_image(const SlotImageReceived& slot);
 317
 318
 319   /// For instance: void on_targetsreceived(const Glib::StringArrayHandle& targets);
 320   typedef sigc::slot<void, const Glib::StringArrayHandle&> SlotTargetsReceived;
 321
 322   /** Requests the contents of the clipboard as list of supported targets.
 323    * When the list is later received, callback will be called.
 324    *
 325    * The targets parameter to slot will contain the resulting targets if
 326    * the request succeeded.
 327    *
 328    * @param slot a function to call when the targets are received,
 329    *             or the retrieval fails. (It will always be called
 330    *             one way or the other.) Remember that Glib::StringArrayHandle
 331    *             is an intermediate type, so you should convert it to a
 332    *             standard C++ container.
 333    *
 334    * @newin2p4
 335    */
 336   void request_targets(const SlotTargetsReceived& slot);
 337
 338
 339   /**
 340    * Requests the contents of the clipboard using the given target.
 341    * This function waits for the data to be received using the main
 342    * loop, so events, timeouts, etc, may be dispatched during the wait.
 343    *
 344    * @param target The form into which the clipboard owner should convert the selection.
 345    *
 346    * @return A SelectionData object, which will be invalid if retrieving the given target failed.
 347    */
 348   SelectionData wait_for_contents(const Glib::ustring& target) const;
 349
 350
 351   /** Requests the contents of the clipboard as text and converts
 352    * the result to UTF-8 if necessary. This function waits for
 353    * the data to be received using the main loop, so events,
 354    * timeouts, etc, may be dispatched during the wait.
 355    * @return A UTF-8 string, which is empty if retrieving
 356    * the selection data failed. (This could happen
 357    * for various reasons, in particular if the
 358    * clipboard was empty or if the contents of the
 359    * clipboard could not be converted into text form.).
 360    */
 361   Glib::ustring wait_for_text() const;
 362
 363   std::string wait_for_rich_text(const Glib::RefPtr<TextBuffer>& buffer, std::string& format);
 364
 365
 366   //Maybe the result should be const, but constness is not so clear-cut here. murrayc
 367
 368   /** Requests the contents of the clipboard as image and converts
 369    * the result to a Gdk::Pixbuf. This function waits for
 370    * the data to be received using the main loop, so events,
 371    * timeouts, etc, may be dispatched during the wait.
 372    * @return A newly-allocated Gdk::Pixbuf object which must
 373    * be disposed with Glib::object_unref(), or <tt>0</tt> if
 374    * retrieving the selection data failed. (This
 375    * could happen for various reasons, in particular
 376    * if the clipboard was empty or if the contents of
 377    * the clipboard could not be converted into an image.)
 378    *
 379    * @newin2p6.
 380    */
 381   Glib::RefPtr<Gdk::Pixbuf> wait_for_image() const;
 382
 383
 384   /** Test to see if there is text available to be pasted
 385    * This is done by requesting the TARGETS atom and checking
 386    * if it contains any of the supported text targets. This function
 387    * waits for the data to be received using the main loop, so events,
 388    * timeouts, etc, may be dispatched during the wait.
 389    *
 390    * This function is a little faster than calling
 391    * gtk_clipboard_wait_for_text() since it doesn't need to retrieve
 392    * the actual text.
 393    * @return <tt>true</tt> is there is text available, <tt>false</tt> otherwise.
 394    */
 395   bool wait_is_text_available() const;
 396
 397   /** Test to see if there is rich text available to be pasted
 398    * This is done by requesting the TARGETS atom and checking
 399    * if it contains any of the supported rich text targets. This function
 400    * waits for the data to be received using the main loop, so events,
 401    * timeouts, etc, may be dispatched during the wait.
 402    *
 403    * This function is a little faster than calling
 404    * gtk_clipboard_wait_for_rich_text() since it doesn't need to retrieve
 405    * the actual text.
 406    * @param buffer A Gtk::TextBuffer.
 407    * @return <tt>true</tt> is there is rich text available, <tt>false</tt> otherwise.
 408    *
 409    * @newin2p10.
 410    */
 411   bool wait_is_rich_text_available(const Glib::RefPtr<TextBuffer>& buffer) const;
 412
 413   /** Test to see if there is an image available to be pasted
 414    * This is done by requesting the TARGETS atom and checking
 415    * if it contains any of the supported image targets. This function
 416    * waits for the data to be received using the main loop, so events,
 417    * timeouts, etc, may be dispatched during the wait.
 418    *
 419    * This function is a little faster than calling
 420    * gtk_clipboard_wait_for_image() since it doesn't need to retrieve
 421    * the actual image data.
 422    * @return <tt>true</tt> is there is an image available, <tt>false</tt> otherwise.
 423    *
 424    * @newin2p6.
 425    */
 426   bool wait_is_image_available() const;
 427
 428   /** Checks if a clipboard supports pasting data of a given type. This
 429    * function can be used to determine if a "Paste" menu item should be
 430    * insensitive or not.
 431    *
 432    * If you want to see if there's text available on the clipboard, use
 433    * gtk_clipboard_wait_is_text_available() instead.
 434    * @param target A Gdk::Atom indicating which target to look for.
 435    * @return <tt>true</tt> if the target is available, <tt>false</tt> otherwise.
 436    *
 437    * @newin2p6.
 438    */
 439   bool wait_is_target_available(const Glib::ustring& target);
 440
 441   /** Returns a list of targets that are present on the clipboard.
 442    * This function waits for the data to be received using the main
 443    * loop, so events, timeouts, etc, may be dispatched during the wait.
 444    *
 445    * @result targets: The targets.
 446    *
 447    * @newin2p4
 448    */
 449   Glib::StringArrayHandle wait_for_targets() const;
 450
 451
 452   /** Hints that the clipboard data should be stored somewhere when the application exits or when store()
 453    * is called.
 454    *
 455    * This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform
 456    * dependent, see Gdk::Display::store_clipboard() for more information.
 457    *
 458    * @param targets Array containing information about which forms should be stored.
 459    */
 460   void set_can_store(const ArrayHandle_TargetEntry& targets);
 461
 462   /** Hints that all forms of clipboard data should be stored somewhere when the application exits or when store()
 463    * is called.
 464    *
 465    * This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform
 466    * dependent, see Gdk::Display::store_clipboard() for more information.
 467    */
 468   void set_can_store();
 469
 470
 471   /** Stores the current clipboard data somewhere so that it will stay
 472    * around after the application has quit.
 473    *
 474    * @newin2p6
 475    */
 476   void store();
 477
 478   //We use no_default_handler because this signal was added and we don't want to break the ABI by adding a virtual function.
 479
 480   /**
 481    * @par Prototype:
 482    * <tt>void on_my_%owner_change(GdkEventOwnerChange* event)</tt>
 483    */
 484
 485   Glib::SignalProxy1< void,GdkEventOwnerChange* > signal_owner_change();
 486
 487
 488 public:
 489
 490 public:
 491   //C++ methods used to invoke GTK+ virtual functions:
 492 #ifdef GLIBMM_VFUNCS_ENABLED
 493 #endif //GLIBMM_VFUNCS_ENABLED
 494
 495 protected:
 496   //GTK+ Virtual Functions (override these to change behaviour):
 497 #ifdef GLIBMM_VFUNCS_ENABLED
 498 #endif //GLIBMM_VFUNCS_ENABLED
 499
 500   //Default Signal Handlers::
 501 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 502 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 503
 504
 505 };
 506
 507 } /* namespace Gtk */
 508
 509
 510 namespace Glib
 511 {
 512   /** A Glib::wrap() method for this object.
 513    *
 514    * @param object The C instance.
 515    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 516    * @result A C++ instance that wraps this C instance.
 517    *
 518    * @relates Gtk::Clipboard
 519    */
 520   Glib::RefPtr<Gtk::Clipboard> wrap(GtkClipboard* object, bool take_copy = false);
 521 }
 522
 523
 524 #endif /* _GTKMM_CLIPBOARD_H */
 525