1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                 Copyright (C) 2002-2013, AdaCore                  -- 
  5. --                                                                   -- 
  6. -- This library is free software; you can redistribute it and/or     -- 
  7. -- modify it under the terms of the GNU General Public               -- 
  8. -- License as published by the Free Software Foundation; either      -- 
  9. -- version 2 of the License, or (at your option) any later version.  -- 
  10. --                                                                   -- 
  11. -- This library is distributed in the hope that it will be useful,   -- 
  12. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  13. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  14. -- General Public License for more details.                          -- 
  15. --                                                                   -- 
  16. -- You should have received a copy of the GNU General Public         -- 
  17. -- License along with this library; if not, write to the             -- 
  18. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  19. -- Boston, MA 02111-1307, USA.                                       -- 
  20. --                                                                   -- 
  21. -- As a special exception, if other files instantiate generics from  -- 
  22. -- this unit, or you link this unit with other files to produce an   -- 
  23. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  24. -- executable to be covered by the GNU General Public License. This  -- 
  25. -- exception does not however invalidate any other reasons why the   -- 
  26. -- executable file  might be covered by the  GNU Public License.     -- 
  27. ----------------------------------------------------------------------- 
  28.  
  29. --  <description> 
  30. --  The Gtk_Clipboard object represents a clipboard of data shared between 
  31. --  different processes or between different widgets in the same process. Each 
  32. --  clipboard is identified by a name encoded as a Gdk_Atom. (Conversion to and 
  33. --  from strings can be done with gdk.properties.atom_intern and 
  34. --  gdk.properties.atom_name().) The default clipboard corresponds to the 
  35. --  "CLIPBOARD" atom; another commonly used clipboard is the "PRIMARY" 
  36. --  clipboard, which, in X, traditionally contains the currently selected text. 
  37. -- 
  38. --  To support having a number of different formats on the clipboard at the 
  39. --  same time, the clipboard mechanism allows providing callbacks instead of 
  40. --  the actual data. When you set the contents of the clipboard, you can either 
  41. --  supply the data directly (via functions like Set_Text), or you can supply a 
  42. --  callback to be called at a later time when the data is needed (via 
  43. --  Set_With_Data or Set_With_Owner.) Providing a callback also avoids having 
  44. --  to make copies of the data when it is not needed. 
  45. -- 
  46. --  Set_With_Data and Set_With_Owner are quite similar; the choice between the 
  47. --  two depends mostly on which is more convenient in a particular situation. 
  48. --  The former is most useful when you want to have a blob of data with 
  49. --  callbacks to convert it into the various data types that you advertise. 
  50. --  When the clear_func you provided is called, you simply free the data blob. 
  51. --  The latter is more useful when the contents of clipboard reflect the 
  52. --  internal state of a GObject (As an example, for the PRIMARY clipboard, when 
  53. --  an entry widget provides the clipboard's contents the contents are simply 
  54. --  the text within the selected region.) If the contents change, the entry 
  55. --  widget can call Set_With_Owner() to update the timestamp for clipboard 
  56. --  ownership, without having to worry about clear_func being called. 
  57. -- 
  58. --  Requesting the data from the clipboard is essentially asynchronous. If the 
  59. --  contents of the clipboard are provided within the same process, then direct 
  60. --  function call will be made to retrieve the data, but if they are provided 
  61. --  by another process, then the data needs to be retrieved from the other 
  62. --  process, which may take some time. To avoid blocking the user interface, 
  63. --  the call to request the selection, Request_Contents takes a callback that 
  64. --  will be called when the contents are received (or when the request fails.) 
  65. --  If you don't want to deal with providing a separate callback, you can also 
  66. --  use Wait_For_Contents. What this does is run the GLib main loop recursively 
  67. --  waiting for the contents. This can simplify the code flow, but you still 
  68. --  have to be aware that other callbacks in your program can be called while 
  69. --  this recursive mainloop is running. 
  70. -- 
  71. --  Along with the functions to get the clipboard contents as an arbitrary data 
  72. --  chunk, there are also functions to retrieve it as text, Request_Text and 
  73. --  Wait_For_Text. These functions take care of determining which formats are 
  74. --  advertised by the clipboard provider, asking for the clipboard in the best 
  75. --  available format and converting the results into the UTF-8 encoding. (The 
  76. --  standard form for representing strings in GTK+.) 
  77. --  </description> 
  78. --  <c_version>2.8.17</c_version> 
  79. --  <group>Inter-Process communication</group> 
  80. --  <testgtk>create_clipboard.adb</testgtk> 
  81.  
  82. with Gdk.Pixbuf; 
  83. with Gdk.Types; 
  84. with Gtk.Selection; 
  85. with Gtk.Widget; 
  86. with Interfaces.C.Strings; 
  87. with System; 
  88.  
  89. package Gtk.Clipboard is 
  90.  
  91.    type Gtk_Clipboard is new Glib.C_Proxy; 
  92.  
  93.    function Get_Type return Glib.GType; 
  94.    --  Return the internal type used for clipboards 
  95.  
  96.    function Get_Clipboard 
  97.      (Widget    : access Gtk.Widget.Gtk_Widget_Record'Class; 
  98.       Selection : Gdk.Types.Gdk_Atom) 
  99.       return Gtk.Clipboard.Gtk_Clipboard; 
  100.    --  Returns the clipboard object for the given selection to be used with 
  101.    --  Widget. Widget must have a Gdk_Display associated with it, so must be 
  102.    --  attached to a toplevel window. 
  103.    -- 
  104.    --  Return value: the appropriate clipboard object. If no clipboard already 
  105.    --  exists, a new one will be created. Once a clipboard object has been 
  106.    --  created, it is persistent for all time. 
  107.  
  108.    function Get 
  109.      (Selection : Gdk.Types.Gdk_Atom := Gdk.Types.Gdk_None) 
  110.       return Gtk_Clipboard; 
  111.    --  Return the clipboard object for the given selection. Cut/copy/paste menu 
  112.    --  items and keyboard shortcuts should use the default clipboard, returned 
  113.    --  by passing Gdk_None for Selection. The currently-selected object or text 
  114.    --  should be provided on the clipboard identified by Selection_Primary. 
  115.    --  Cut/copy/paste menu items conceptually copy the contents of the 
  116.    --  Selection_Primary clipboard to the default clipboard, i.e. they copy the 
  117.    --  selection to what the user sees as the clipboard. 
  118.    -- 
  119.    --  (Passing Gdk_None is the same as using Atom_Intern ("CLIPBOARD", False). 
  120.    --  See http://standards.freedesktop.org/clipboards-spec/ for a 
  121.    --  detailed discussion of the "CLIPBOARD" vs. "PRIMARY" selections under 
  122.    --  the X window system. On Win32 the Selection_Primary clipboard is 
  123.    --  essentially ignored.) 
  124.    -- 
  125.    --  It's possible to have arbitrary named clipboards; if you do invent new 
  126.    --  clipboards, you should prefix the selection name with an underscore 
  127.    --  (because the ICCCM requires that nonstandard atoms are 
  128.    --  underscore-prefixed), and namespace it as well. For example, if your 
  129.    --  application called "Foo" has a special-purpose clipboard, you might call 
  130.    --  it "_FOO_SPECIAL_CLIPBOARD". 
  131.    -- 
  132.    --  Selection is a Gdk_Atom which identifies the clipboard to use. 
  133.    -- 
  134.    --  If no clipboard already exists, a new one will be created. Once 
  135.    --  clipboard object has been created, it is persistent for all time and 
  136.    --  cannot be freed. 
  137.  
  138.    procedure Set_Can_Store 
  139.      (Clipboard : Gtk_Clipboard; 
  140.       Targets   : Gtk.Selection.Target_Entry_Array); 
  141.    --  Hints that the clipboard data should be stored somewhere when the 
  142.    --  application exits or when Store is called. 
  143.    --  This value is reset when the clipboard owner changes. Where the 
  144.    --  clipboard data is stored is platform dependent. 
  145.    --  Targets is an array containing information about which forms should be 
  146.    --  stored, or an empty array to indicate that all forms should be stored. 
  147.  
  148.    procedure Store (Clipboard : Gtk_Clipboard); 
  149.    --  Stores the current clipboard data somewhere so that it will stay 
  150.    --  around after the application has quit. 
  151.    --  See also Gdk.Display.Supports_Clipboard_Persistence and 
  152.    --  Gdk.Display.Store_Clipboard. 
  153.  
  154.    function Get_Owner (Clipboard : Gtk_Clipboard) return Glib.Object.GObject; 
  155.    --  If the clipboard contents callbacks were set with Set_With_Owner, and 
  156.    --  the Set_With_Data or Clear has not subsequently called, returns the 
  157.    --  owner set by Set_With_Owner. 
  158.  
  159.    procedure Clear (Clipboard : Gtk_Clipboard); 
  160.    --  Clear the contents of the clipboard. 
  161.    --  Generally this should only be called between the time you call 
  162.    --  Set_With_Owner or Set_With_Data, and when the Clear_Func you supplied 
  163.    --  is called. Otherwise, the clipboard may be owned by someone else. 
  164.  
  165.    ---------- 
  166.    -- Text -- 
  167.    ---------- 
  168.  
  169.    type Gtk_Clipboard_Text_Received_Func is access 
  170.      procedure (Clipboard : Gtk_Clipboard; 
  171.                 Text      : Interfaces.C.Strings.chars_ptr; 
  172.                 Data      : System.Address); 
  173.    pragma Convention (C, Gtk_Clipboard_Text_Received_Func); 
  174.    --  Called when some text is received from the keyboard, or the retrieval 
  175.    --  fails. 
  176.    --  The Text parameter will contain the resulting text if the request 
  177.    --  succeeded, or Null_Ptr if it failed. This could happen for various 
  178.    --  reasons, in particular if the clipboard was empty or if the contents of 
  179.    --  the clipboard could not be converted into text form. 
  180.  
  181.    procedure Set_Text 
  182.      (Clipboard : Gtk_Clipboard; 
  183.       Text      : UTF8_String); 
  184.    --  Set the contents of the clipboard. 
  185.  
  186.    function Wait_For_Text (Clipboard : Gtk_Clipboard) return UTF8_String; 
  187.    --  Requests the contents of the clipboard as text and converts the result 
  188.    --  to UTF-8 if necessary. This function waits for the data to be received 
  189.    --  using the main loop, so events, timeouts, etc, may be dispatched during 
  190.    --  the wait. 
  191.    -- 
  192.    --  Return "" if retrieving the selection data failed. (This could happen 
  193.    --  for various reasons, in particular if the clipboard was empty or if the 
  194.    --  contents of the clipboard could not be converted into text form) 
  195.  
  196.    function Wait_Is_Text_Available 
  197.      (Clipboard : Gtk_Clipboard) return Boolean; 
  198.    --  Test to see if there is text available to be pasted. This function waits 
  199.    --  for the data to be received using the main loop, so events, timeouts, 
  200.    --  etc, may be dispatched during the wait. 
  201.  
  202.    procedure Request_Text 
  203.      (Clipboard : Gtk_Clipboard; 
  204.       Callback  : Gtk_Clipboard_Text_Received_Func; 
  205.       User_Data : System.Address); 
  206.    --  Requests the contents of the clipboard as text. When the text is later 
  207.    --  received, it will be converted to UTF-8 if necessary, and Callback will 
  208.    --  be called. 
  209.  
  210.    ------------ 
  211.    -- Images -- 
  212.    ------------ 
  213.  
  214.    type Gtk_Clipboard_Image_Received_Func is access 
  215.      procedure (Clipboard : Gtk_Clipboard; 
  216.                 Pixbuf    : System.Address; 
  217.                 Data      : System.Address); 
  218.    pragma Convention (C, Gtk_Clipboard_Image_Received_Func); 
  219.    --  Pixbuf will contain null if the request failed. 
  220.    --  Pixbuf must not be Unref. Pixbuf must be converted to GtkAda object 
  221.    --  using Gdk.Pixbuf.Convert. 
  222.  
  223.    procedure Set_Image 
  224.      (Clipboard : Gtk_Clipboard; 
  225.       Pixbuf    : Gdk.Pixbuf.Gdk_Pixbuf); 
  226.    --  Sets the contents of the clipboard to the given pixbuf. GTK+ will take 
  227.    --  responsibility for responding for requests for the image, and for 
  228.    --  converting the image into the requested format. 
  229.  
  230.    function Wait_For_Image 
  231.      (Clipboard : Gtk_Clipboard) 
  232.       return Gdk.Pixbuf.Gdk_Pixbuf; 
  233.    --  Requests the contents of the clipboard as image and converts the result 
  234.    --  to a pixbuf. This function waits for the data to be received using the 
  235.    --  main loop, so events, timeouts, etc, may be dispatched during the wait. 
  236.    --  The returned value must be freed with a call to Unref. 
  237.  
  238.    function Wait_Is_Image_Available (Clipboard : Gtk_Clipboard) return Boolean; 
  239.    --  Test to see if there is an image available to be pasted. This is done by 
  240.    --  requesting the TARGETS atom and checking if it contains any of the 
  241.    --  supported image targets. This function waits for the data to be received 
  242.    --  using the main loop, so events, timeouts, etc, may be dispatched during 
  243.    --  the wait. 
  244.    --  This function is a little faster than calling Wait_For_Image since it 
  245.    --  doesn't need to retrieve the actual image data. 
  246.  
  247.    procedure Request_Image 
  248.      (Clipboard : Gtk_Clipboard; 
  249.       Callback  : Gtk_Clipboard_Image_Received_Func; 
  250.       User_Data : System.Address); 
  251.    --  Requests the contents of the clipboard as image. When the image is 
  252.    --  later received, it will be converted to a pixbuf, and Callback 
  253.    --  will be called. 
  254.  
  255.    -------------------- 
  256.    -- Other contents -- 
  257.    -------------------- 
  258.  
  259.    type Gtk_Clipboard_Get_Func is access procedure 
  260.      (Clipboard          : Gtk_Clipboard; 
  261.       Selection_Data     : Gtk.Selection.Selection_Data; 
  262.       Info               : Guint; 
  263.       User_Data_Or_Owner : System.Address); 
  264.    pragma Convention (C, Gtk_Clipboard_Get_Func); 
  265.    --  Called when the actual clipboard data is requested. Selection_Data 
  266.    --  should be modified to return the data. 
  267.    --  Info describes the expected format (see Gtk.Selection.Target_Entry). 
  268.    --  If User_Data is the owner (ie when you used Set_With_Owner), you must 
  269.    --  convert it to a proper Gtk_Widget by using Gtk.Widget.Convert. 
  270.  
  271.    type Gtk_Clipboard_Clear_Func is access procedure 
  272.      (Clipboard          : Gtk_Clipboard; 
  273.       User_Data_Or_Owner : System.Address); 
  274.    pragma Convention (C, Gtk_Clipboard_Clear_Func); 
  275.    --  Called when the contents of the clipboard is overriden. Get_Func will 
  276.    --  not be called subsequently. 
  277.    --  If User_Data is the owner (ie when you used Set_With_Owner), you must 
  278.    --  convert it to a proper Gtk_Widget by using Gtk.Widget.Convert. 
  279.  
  280.    type Gtk_Clipboard_Received_Func is access procedure 
  281.      (Clipboard      : Gtk_Clipboard; 
  282.       Selection_Data : Gtk.Selection.Selection_Data; 
  283.       User_Data      : System.Address); 
  284.    pragma Convention (C, Gtk_Clipboard_Received_Func); 
  285.    --  Called when data from the clipboard is made available to the application 
  286.  
  287.    type Gtk_Clipboard_Targets_Received_Func is access procedure 
  288.      (Clipboard      : Gtk_Clipboard; 
  289.       Atoms          : Gdk.Types.Gdk_Atom_Array; 
  290.       N_Atoms        : Gint; 
  291.       User_Data      : System.Address); 
  292.    pragma Convention (C, Gtk_Clipboard_Targets_Received_Func); 
  293.    --  Called when the application has requested the list of supported targets 
  294.    --  for the current clipboard 
  295.  
  296.    function Set_With_Data 
  297.      (Clipboard  : Gtk_Clipboard; 
  298.       Targets    : Gtk.Selection.Target_Entry_Array; 
  299.       Get_Func   : Gtk_Clipboard_Get_Func; 
  300.       Clear_Func : Gtk_Clipboard_Clear_Func; 
  301.       User_Data  : System.Address) 
  302.       return Boolean; 
  303.    --  Virtually sets the contents of the specified clipboard by providing a 
  304.    --  list of supported formats for the clipboard data and a function to call 
  305.    --  to get the actual data when it is requested. No actual copy of the data 
  306.    --  is made until someones actually requests it. 
  307.    --  Targets contains information about the available forms for the clipboard 
  308.    --  data. 
  309.    --  This function returns True if setting the clipboard data succeeded. 
  310.  
  311.    function Set_With_Owner 
  312.      (Clipboard  : Gtk_Clipboard; 
  313.       Targets    : Gtk.Selection.Target_Entry_Array; 
  314.       Get_Func   : Gtk_Clipboard_Get_Func; 
  315.       Clear_Func : Gtk_Clipboard_Clear_Func; 
  316.       Owner      : access Glib.Object.GObject_Record'Class) 
  317.       return Boolean; 
  318.    --  Same as Set_With_Data, but an actual object is passed instead of a 
  319.    --  generic user_data. This takes care of referencing the object as 
  320.    --  appropriate. 
  321.  
  322.    function Wait_For_Targets 
  323.      (Clipboard : Gtk_Clipboard) return Gdk.Types.Gdk_Atom_Array; 
  324.    --  Returns a list of targets that are present on the clipboard, or an empty 
  325.    --  array if there aren't any targets available. 
  326.    --  This function waits for the data to be received using the main 
  327.    --  loop, so events, timeouts, etc, may be dispatched during the wait. 
  328.  
  329.    function Wait_For_Contents 
  330.      (Clipboard : Gtk_Clipboard; 
  331.       Target    : Gdk.Types.Gdk_Atom) 
  332.       return Gtk.Selection.Selection_Data; 
  333.    --  Requests the contents of the clipboard using the given target. This 
  334.    --  function waits for the data to be received using the main loop, so 
  335.    --  events, timeouts, etc, may be dispatched during the wait. 
  336.    --  The result must be freed. 
  337.  
  338.    function Wait_Is_Target_Available 
  339.      (Clipboard : Gtk_Clipboard; Target : Gdk.Types.Gdk_Atom) return Boolean; 
  340.    --  Checks if a clipboard supports pasting data of a given type. This 
  341.    --  function can be used to determine if a "Paste" menu item should be 
  342.    --  insensitive or not. 
  343.    --  If you want to see if there's text available on the clipboard, use 
  344.    --  Wait_Is_Text_Available instead. 
  345.    --  The value for Target is similar to the one in Gtk.Selection.Target_Entry 
  346.  
  347.    procedure Request_Contents 
  348.      (Clipboard : Gtk_Clipboard; 
  349.       Target    : Gdk.Types.Gdk_Atom; 
  350.       Callback  : Gtk_Clipboard_Received_Func; 
  351.       User_Data : System.Address); 
  352.    --  Requests the contents of clipboard as the given target. 
  353.    --  When the results of the result are later received the supplied callback 
  354.    --  will be called. 
  355.  
  356.    procedure Request_Targets 
  357.      (Clipboard : Gtk_Clipboard; 
  358.       Callback  : Gtk_Clipboard_Targets_Received_Func; 
  359.       User_Data : System.Address); 
  360.    --  Requests the contents of the clipboard as list of supported targets. 
  361.    --  When the list is later received, Callback will be called. 
  362.  
  363.    ------------- 
  364.    -- Signals -- 
  365.    ------------- 
  366.  
  367.    --  <signals> 
  368.    --  The following new signals are defined for this widget: 
  369.    -- 
  370.    --  - "owner_change" 
  371.    --    Emitted when the owner of the clipboard has changed 
  372.    -- 
  373.    --  </signals> 
  374.  
  375.    Signal_Owner_Change : constant Glib.Signal_Name := "owner_change"; 
  376.  
  377. private 
  378.    pragma Import (C, Get_Type,          "gtk_clipboard_get_type"); 
  379.    pragma Import (C, Get,               "gtk_clipboard_get"); 
  380.    pragma Import (C, Clear,             "gtk_clipboard_clear"); 
  381.    pragma Import (C, Store,             "gtk_clipboard_store"); 
  382.    pragma Import (C, Request_Text,      "gtk_clipboard_request_text"); 
  383.    pragma Import (C, Request_Image,     "gtk_clipboard_request_image"); 
  384.    pragma Import (C, Wait_For_Contents, "gtk_clipboard_wait_for_contents"); 
  385. end Gtk.Clipboard; 
  386.  
  387. --  No binding: gtk_clipboard_get_display 
  388. --  No binding: gtk_clipboard_get_for_display