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