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