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