1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  Gtk.Recent_Manager.Gtk_Recent_Manager provides a facility for adding, 
  26. --  removing and looking up recently used files. Each recently used file is 
  27. --  identified by its URI, and has meta-data associated to it, like the names 
  28. --  and command lines of the applications that have registered it, the number 
  29. --  of time each application has registered the same file, the mime type of the 
  30. --  file and whether the file should be displayed only by the applications that 
  31. --  have registered it. 
  32. -- 
  33. --  Note: 
  34. -- 
  35. --  The recently used files list is per user. 
  36. -- 
  37. --  The Gtk.Recent_Manager.Gtk_Recent_Manager acts like a database of all the 
  38. --  recently used files. You can create new 
  39. --  Gtk.Recent_Manager.Gtk_Recent_Manager objects, but it is more efficient to 
  40. --  use the default manager created by GTK+. 
  41. -- 
  42. --  Adding a new recently used file is as simple as: 
  43. -- 
  44. --  |[ GtkRecentManager *manager; 
  45. -- 
  46. --  manager = gtk_recent_manager_get_default (); gtk_recent_manager_add_item 
  47. --  (manager, file_uri); ]| 
  48. -- 
  49. --  The Gtk.Recent_Manager.Gtk_Recent_Manager will try to gather all the 
  50. --  needed information from the file itself through GIO. 
  51. -- 
  52. --  Looking up the meta-data associated with a recently used file given its 
  53. --  URI requires calling Gtk.Recent_Manager.Lookup_Item: 
  54. -- 
  55. --  |[ GtkRecentManager *manager; GtkRecentInfo *info; GError *error = NULL; 
  56. -- 
  57. --  manager = gtk_recent_manager_get_default (); info = 
  58. --  gtk_recent_manager_lookup_item (manager, file_uri, &amp;error); if (error) 
  59. --  { g_warning ("Could not find the file: %s", error->message); g_error_free 
  60. --  (error); } else { /* Use the info object */ gtk_recent_info_unref (info); } 
  61. --  ]| 
  62. -- 
  63. --  In order to retrieve the list of recently used files, you can use 
  64. --  Gtk.Recent_Manager.Get_Items, which returns a list of 
  65. --  Gtk.Recent_Info.Gtk_Recent_Info structures. 
  66. -- 
  67. --  A Gtk.Recent_Manager.Gtk_Recent_Manager is the model used to populate the 
  68. --  contents of one, or more Gtk.Recent_Chooser.Gtk_Recent_Chooser 
  69. --  implementations. 
  70. -- 
  71. --  Note: 
  72. -- 
  73. --  The maximum age of the recently used files list is controllable through 
  74. --  the Gtk.Settings.Gtk_Settings:gtk-recent-files-max-age property. 
  75. -- 
  76. --  Recently used files are supported since GTK+ 2.10. 
  77. -- 
  78. --  </description> 
  79. --  <description> 
  80. --  In case the default screen is being used, adding a new recently used file 
  81. --  is as simple as: 
  82. -- 
  83. --  
  84. --      declare 
  85. --         Manager : constant Gtk_Recent_Manager := Get_Default; 
  86. --      begin 
  87. --         Add_Item (Manager, File_URI); 
  88. --      end; 
  89. -- 
  90. --  While looking up a recently used file is as simple as using: 
  91. -- 
  92. --  
  93. --      declare 
  94. --         Manager : constant Gtk_Recent_Manager := Get_Default; 
  95. --         Info    : Gtk_Recent_Info; 
  96. --         Error   : Glib.Error.GError; 
  97. --      begin 
  98. --         Lookup_Item (Info, Manager, File_URI, Error); 
  99. --         if Error /= null then 
  100. --            --  Use the info object 
  101. --            Unref (Info); 
  102. --         else 
  103. --            Put_Line 
  104. --              ("Could not find the file: " & Glib.Error.Get_Message (Error)); 
  105. --            Glib.Error.Error_Free (Error); 
  106. --         end if; 
  107. --      end; 
  108. --       
  109. -- 
  110. --  </description> 
  111. pragma Ada_2005; 
  112.  
  113. pragma Warnings (Off, "*is already use-visible*"); 
  114. with GNAT.Strings;         use GNAT.Strings; 
  115. with Glib;                 use Glib; 
  116. with Glib.Glist;           use Glib.Glist; 
  117. with Glib.Object;          use Glib.Object; 
  118. with Glib.Properties;      use Glib.Properties; 
  119. with Gtk.Recent_Info;      use Gtk.Recent_Info; 
  120. with Interfaces.C.Strings; use Interfaces.C.Strings; 
  121.  
  122. package Gtk.Recent_Manager is 
  123.  
  124.    type Gtk_Recent_Manager_Record is new GObject_Record with null record; 
  125.    type Gtk_Recent_Manager is access all Gtk_Recent_Manager_Record'Class; 
  126.  
  127.    type Gtk_Recent_Data is record 
  128.       Display_Name : Interfaces.C.Strings.chars_ptr; 
  129.       Description : Interfaces.C.Strings.chars_ptr; 
  130.       Mime_Type : Interfaces.C.Strings.chars_ptr; 
  131.       App_Name : Interfaces.C.Strings.chars_ptr; 
  132.       App_Exec : Interfaces.C.Strings.chars_ptr; 
  133.       Groups : Interfaces.C.Strings.char_array_access; 
  134.       Is_Private : Boolean; 
  135.    end record; 
  136.    pragma Convention (C, Gtk_Recent_Data); 
  137.  
  138.    function From_Object_Free (B : access Gtk_Recent_Data) return Gtk_Recent_Data; 
  139.    pragma Inline (From_Object_Free); 
  140.    --  Meta-data to be passed to gtk_recent_manager_add_full when registering 
  141.    --  a recently used resource. 
  142.  
  143.    function Convert (R : Gtk.Recent_Info.Gtk_Recent_Info) return System.Address; 
  144.    function Convert (R : System.Address) return Gtk.Recent_Info.Gtk_Recent_Info; 
  145.    package Gtk_Recent_Info_List is new Generic_List (Gtk.Recent_Info.Gtk_Recent_Info); 
  146.  
  147.    ------------------ 
  148.    -- Constructors -- 
  149.    ------------------ 
  150.  
  151.    procedure Gtk_New (Self : out Gtk_Recent_Manager); 
  152.    procedure Initialize 
  153.       (Self : not null access Gtk_Recent_Manager_Record'Class); 
  154.    --  Creates a new recent manager object. Recent manager objects are used to 
  155.    --  handle the list of recently used resources. A 
  156.    --  Gtk.Recent_Manager.Gtk_Recent_Manager object monitors the recently used 
  157.    --  resources list, and emits the "changed" signal each time something 
  158.    --  inside the list changes. 
  159.    --  Gtk.Recent_Manager.Gtk_Recent_Manager objects are expensive: be sure to 
  160.    --  create them only when needed. You should use 
  161.    --  Gtk.Recent_Manager.Get_Default instead. 
  162.    --  Since: gtk+ 2.10 
  163.  
  164.    function Gtk_Recent_Manager_New return Gtk_Recent_Manager; 
  165.    --  Creates a new recent manager object. Recent manager objects are used to 
  166.    --  handle the list of recently used resources. A 
  167.    --  Gtk.Recent_Manager.Gtk_Recent_Manager object monitors the recently used 
  168.    --  resources list, and emits the "changed" signal each time something 
  169.    --  inside the list changes. 
  170.    --  Gtk.Recent_Manager.Gtk_Recent_Manager objects are expensive: be sure to 
  171.    --  create them only when needed. You should use 
  172.    --  Gtk.Recent_Manager.Get_Default instead. 
  173.    --  Since: gtk+ 2.10 
  174.  
  175.    function Get_Type return Glib.GType; 
  176.    pragma Import (C, Get_Type, "gtk_recent_manager_get_type"); 
  177.  
  178.    ------------- 
  179.    -- Methods -- 
  180.    ------------- 
  181.  
  182.    function Add_Item 
  183.       (Self : not null access Gtk_Recent_Manager_Record; 
  184.        URI  : UTF8_String) return Boolean; 
  185.    --  Adds a new resource, pointed by Uri, into the recently used resources 
  186.    --  list. 
  187.    --  This function automatically retrieves some of the needed metadata and 
  188.    --  setting other metadata to common default values; it then feeds the data 
  189.    --  to gtk_recent_manager_add_full. 
  190.    --  See gtk_recent_manager_add_full if you want to explicitly define the 
  191.    --  metadata for the resource pointed by Uri. 
  192.    --  Since: gtk+ 2.10 
  193.    --  "uri": a valid URI 
  194.  
  195.    function Get_Items 
  196.       (Self : not null access Gtk_Recent_Manager_Record) 
  197.        return Gtk_Recent_Info_List.Glist; 
  198.    --  Gets the list of recently used resources. 
  199.    --  Since: gtk+ 2.10 
  200.  
  201.    function Has_Item 
  202.       (Self : not null access Gtk_Recent_Manager_Record; 
  203.        URI  : UTF8_String) return Boolean; 
  204.    --  Checks whether there is a recently used resource registered with Uri 
  205.    --  inside the recent manager. 
  206.    --  Since: gtk+ 2.10 
  207.    --  "uri": a URI 
  208.  
  209.    function Lookup_Item 
  210.       (Self : not null access Gtk_Recent_Manager_Record; 
  211.        URI  : UTF8_String) return Gtk.Recent_Info.Gtk_Recent_Info; 
  212.    --  Searches for a URI inside the recently used resources list, and returns 
  213.    --  a structure containing informations about the resource like its MIME 
  214.    --  type, or its display name. 
  215.    --  Since: gtk+ 2.10 
  216.    --  "uri": a URI 
  217.  
  218.    function Move_Item 
  219.       (Self    : not null access Gtk_Recent_Manager_Record; 
  220.        URI     : UTF8_String; 
  221.        New_Uri : UTF8_String := "") return Boolean; 
  222.    --  Changes the location of a recently used resource from Uri to New_Uri. 
  223.    --  Please note that this function will not affect the resource pointed by 
  224.    --  the URIs, but only the URI used in the recently used resources list. 
  225.    --  Since: gtk+ 2.10 
  226.    --  "uri": the URI of a recently used resource 
  227.    --  "new_uri": the new URI of the recently used resource, or null to remove 
  228.    --  the item pointed by Uri in the list 
  229.  
  230.    function Purge_Items 
  231.       (Self : not null access Gtk_Recent_Manager_Record) return Gint; 
  232.    --  Purges every item from the recently used resources list. 
  233.    --  Since: gtk+ 2.10 
  234.  
  235.    function Remove_Item 
  236.       (Self : not null access Gtk_Recent_Manager_Record; 
  237.        URI  : UTF8_String) return Boolean; 
  238.    --  Removes a resource pointed by Uri from the recently used resources list 
  239.    --  handled by a recent manager. 
  240.    --  Since: gtk+ 2.10 
  241.    --  "uri": the URI of the item you wish to remove 
  242.  
  243.    ---------------------- 
  244.    -- GtkAda additions -- 
  245.    ---------------------- 
  246.  
  247.    function Add_Full 
  248.      (Manager      : access Gtk_Recent_Manager_Record; 
  249.       Uri          : UTF8_String; 
  250.       Display_Name : UTF8_String := ""; 
  251.       Description  : UTF8_String := ""; 
  252.       Mime_Type    : UTF8_String; 
  253.       App_Name     : UTF8_String; 
  254.       App_Exec     : UTF8_String; 
  255.       Groups       : GNAT.Strings.String_List; 
  256.       Is_Private   : Boolean) 
  257.    return Boolean; 
  258.    --  Manager      : the Gtk_Recent_Manager on which to operate 
  259.    --  Uri          : pointer to resource 
  260.    --  Display_Name : a UTF-8 encoded string, containing the name of the 
  261.    --                 recently used resource to be displayed, or "". 
  262.    --  Description  : a UTF-8 encoded string, containing a short description 
  263.    --                 of the resource, or "". 
  264.    --  Mime_Type    : the MIME type of the resource. 
  265.    --  App_Name     : the name of the application that is registering this 
  266.    --                 recently used resource. 
  267.    --  App_Exec     : command line used to launch this resource; may contain 
  268.    --                 the "%f" and "%u" escape characters which will be 
  269.    --                 expanded to the resource file path and URI, respectively, 
  270.    --                 when the command line is retrieved. 
  271.    --  Groups       : a vector of strings containing groups names. 
  272.    --  Is_Private   : whether this resource should be displayed only by the 
  273.    --                 applications that have registered it or not. 
  274.    -- 
  275.    --  Adds a new resource, pointed by Uri, into the recently used 
  276.    --  resources list, using the metadata specified. 
  277.    -- 
  278.    --  The passed URI will be used to identify this resource inside the 
  279.    --  list. 
  280.    -- 
  281.    --  In order to register the new recently used resource, metadata about 
  282.    --  the resource must be passed as well as the URI.  This metadata must 
  283.    --  contain the MIME type of the resource pointed by the URI; the name of 
  284.    --  the application that is registering the item, and a command line to be 
  285.    --  used when launching the item. 
  286.    -- 
  287.    --  Optionally, it is possible to specify a UTF-8 string to be used when 
  288.    --  viewing the item instead of the last component of the URI; a short 
  289.    --  description of the item; whether the item should be considered private - 
  290.    --  that is, should be displayed only by the applications that have 
  291.    --  registered it. 
  292.    -- 
  293.    --  Returns True if the new item was successfully added to the recently 
  294.    --  used resources list, False otherwise. 
  295.  
  296.    --------------- 
  297.    -- Functions -- 
  298.    --------------- 
  299.  
  300.    function Get_Default return Gtk_Recent_Manager; 
  301.    --  Gets a unique instance of Gtk.Recent_Manager.Gtk_Recent_Manager, that 
  302.    --  you can share in your application without caring about memory 
  303.    --  management. 
  304.    --  Since: gtk+ 2.10 
  305.  
  306.    ---------------- 
  307.    -- Properties -- 
  308.    ---------------- 
  309.    --  The following properties are defined for this widget. See 
  310.    --  Glib.Properties for more information on properties) 
  311.  
  312.    Filename_Property : constant Glib.Properties.Property_String; 
  313.    --  The full path to the file to be used to store and read the recently 
  314.    --  used resources list 
  315.  
  316.    Size_Property : constant Glib.Properties.Property_Int; 
  317.    --  The size of the recently used resources list. 
  318.  
  319.    ------------- 
  320.    -- Signals -- 
  321.    ------------- 
  322.  
  323.    type Cb_Gtk_Recent_Manager_Void is not null access procedure 
  324.      (Self : access Gtk_Recent_Manager_Record'Class); 
  325.  
  326.    type Cb_GObject_Void is not null access procedure 
  327.      (Self : access Glib.Object.GObject_Record'Class); 
  328.  
  329.    Signal_Changed : constant Glib.Signal_Name := "changed"; 
  330.    procedure On_Changed 
  331.       (Self  : not null access Gtk_Recent_Manager_Record; 
  332.        Call  : Cb_Gtk_Recent_Manager_Void; 
  333.        After : Boolean := False); 
  334.    procedure On_Changed 
  335.       (Self  : not null access Gtk_Recent_Manager_Record; 
  336.        Call  : Cb_GObject_Void; 
  337.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  338.        After : Boolean := False); 
  339.    --  Emitted when the current recently used resources manager changes its 
  340.    --  contents, either by calling Gtk.Recent_Manager.Add_Item or by another 
  341.    --  application. 
  342.  
  343. private 
  344.    Size_Property : constant Glib.Properties.Property_Int := 
  345.      Glib.Properties.Build ("size"); 
  346.    Filename_Property : constant Glib.Properties.Property_String := 
  347.      Glib.Properties.Build ("filename"); 
  348. end Gtk.Recent_Manager;