1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                    Copyright (C) 2010-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. --  Gtk_Recent_Manager provides a facility for adding, removing and looking up 
  31. --  recently used files. Each recently used file is identified by its URI, and 
  32. --  has meta-data associated to it, like the names and command lines of the 
  33. --  applications that have registered it, the number of time each application 
  34. --  has registered the same file, the mime type of the file and whether the 
  35. --  file should be displayed only by the applications that have registered it. 
  36. -- 
  37. --  The Gtk_Recent_Manager acts like a database of all the recently used files. 
  38. --  You can create new Gtk_Recent_Manager objects, but it is more efficient to 
  39. --  use the standard recent manager for the Gdk_Screen so that information 
  40. --  about recently used files is shared with other people using them. In case 
  41. --  the default screen is being used, adding a new recently used file is 
  42. --  as simple as: 
  43. -- 
  44. --     declare 
  45. --        Manager : constant Gtk_Recent_Manager := Get_Default; 
  46. --     begin 
  47. --        Add_Item (Manager, File_URI); 
  48. --     end; 
  49. -- 
  50. --  While looking up a recently used file is as simple as using: 
  51. -- 
  52. --     declare 
  53. --        Manager : constant Gtk_Recent_Manager := Get_Default; 
  54. --        Info    : Gtk_Recent_Info; 
  55. --        Error   : Glib.Error.GError; 
  56. --     begin 
  57. --        Lookup_Item (Info, Manager, File_URI, Error); 
  58. --        if Error /= null then 
  59. --           --  Use the info object 
  60. --           Unref (Info); 
  61. --        else 
  62. --           Put_Line 
  63. --             ("Could not find the file: " & Glib.Error.Get_Message (Error)); 
  64. --           Glib.Error.Error_Free (Error); 
  65. --        end if; 
  66. --     end; 
  67. -- 
  68. --  Recently used files are supported since GTK+ 2.10. 
  69. --  </description> 
  70. --  <c_version>2.16.6</c_version> 
  71.  
  72. with GNAT.Strings; 
  73.  
  74. with Glib.Error; 
  75. with Glib.Glist; 
  76. with Glib.Properties; 
  77. with Glib.Object; 
  78. with Gdk.Pixbuf; 
  79. with Gdk.Screen; 
  80.  
  81. package Gtk.Recent_Manager is 
  82.  
  83.    type Gtk_Recent_Manager_Record is 
  84.      new Glib.Object.GObject_Record with private; 
  85.    type Gtk_Recent_Manager is access all Gtk_Recent_Manager_Record'Class; 
  86.  
  87.    subtype time_t is Long_Integer; 
  88.    --  Type to interface with C's time_t type.  To convert this to/from 
  89.    --  an Ada type, look at Ada.Calendar.Conversion_Operations and be 
  90.    --  sure to pay special attention to the ranges each type is capable 
  91.    --  of representing. 
  92.  
  93.    ----------------- 
  94.    -- Recent_Info -- 
  95.    ----------------- 
  96.  
  97.    type Gtk_Recent_Info_Record is 
  98.      new Glib.Object.GObject_Record with private; 
  99.    type Gtk_Recent_Info is access all Gtk_Recent_Info_Record'Class; 
  100.  
  101.    function Convert (Widget : Gtk_Recent_Info) return System.Address; 
  102.    function Convert (Widget : System.Address) return Gtk_Recent_Info; 
  103.  
  104.    package Gtk_Recent_Info_List is 
  105.      new Glib.Glist.Generic_List (Gtk_Recent_Info); 
  106.    --  Instantiation of a list of Gtk_Recent_Info objects. 
  107.  
  108.    function Get_Type_Recent_Info return GType; 
  109.    --  Return the internal value associated with a Gtk_Recent_Info widget. 
  110.  
  111.    function Exists (Info : access Gtk_Recent_Info_Record) return Boolean; 
  112.    --  Checks whether the resource pointed to by Info still exists.  At 
  113.    --  the moment this check is done only on resources pointing to local 
  114.    --  files. 
  115.  
  116.    function Get_Added (Info : access Gtk_Recent_Info_Record) return time_t; 
  117.    --  Gets the timestamp (seconds from system's Epoch) when the resource 
  118.    --  was added to the recently used resources list. 
  119.    -- 
  120.    --  Return value: the number of seconds elapsed from system's Epoch when 
  121.    --  the resource was added to the list, or -1 on failure. 
  122.  
  123.    function Get_Age (Info : access Gtk_Recent_Info_Record) return Gint; 
  124.    --  Gets the number of days elapsed since the last update of the resource 
  125.    --  pointed by Info. 
  126.    -- 
  127.    --  Return value: a positive integer containing the number of days 
  128.    --  elapsed since the time this resource was last modified. 
  129.  
  130.    type Application_Info_Record is record 
  131.       Result : Boolean; 
  132.       --  True if an application with App_Name has registered this resource 
  133.       --  inside the recently used list, or False otherwise. 
  134.  
  135.       App_Exec : String_Ptr; 
  136.       --  Pointer to the string containing the command line.  Free using 
  137.       --  Glib.Free when no longer needed. 
  138.  
  139.       Count : Guint; 
  140.       --  The number of times this item was registered. 
  141.  
  142.       Time : time_t; 
  143.       --  The timestamp this item was last registered for this application. 
  144.    end record; 
  145.    --  Information returned by Get_Application_Info, below. 
  146.  
  147.    function Get_Application_Info 
  148.      (Info     : access Gtk_Recent_Info_Record; 
  149.       App_Name : String) 
  150.       return Application_Info_Record; 
  151.    --  Gets the data regarding the application that has registered the resource 
  152.    --  pointed by Info. 
  153.    -- 
  154.    --  If the command line contains any escape characters defined inside the 
  155.    --  storage specification, they will be expanded. 
  156.  
  157.    function Get_Description 
  158.      (Info : access Gtk_Recent_Info_Record) return UTF8_String; 
  159.       --  Gets the (short) description of the resource. 
  160.  
  161.    function Get_Display_Name 
  162.      (Info : access Gtk_Recent_Info_Record) return String; 
  163.    --  Gets the name of the resource.  If none has been defined, the 
  164.    --  basename of the resource is obtained. 
  165.  
  166.    function Get_Icon 
  167.      (Info : access Gtk_Recent_Info_Record; 
  168.       Size : Gint) 
  169.       return Gdk.Pixbuf.Gdk_Pixbuf; 
  170.    --  Retrieves the icon of size Size (in pixels) associated to the 
  171.    --  resource MIME type.  Returns a Gdk_Pixbuf containing the icon, or 
  172.    --  null. Use Glib.Object.Unref when finished using the icon. 
  173.  
  174.    function Get_Mime_Type 
  175.      (Info : access Gtk_Recent_Info_Record) return UTF8_String; 
  176.    --  Gets the MIME type of the resource. 
  177.  
  178.    function Get_Modified (Info : access Gtk_Recent_Info_Record) return time_t; 
  179.    --  Gets the timestamp (seconds from system's Epoch) when the resource 
  180.    --  was last modified. Returns -1 on failure. 
  181.  
  182.    function Get_Private_Hint 
  183.      (Info : access Gtk_Recent_Info_Record) return Boolean; 
  184.    --  Gets the value of the "private" flag.  Resources in the recently used 
  185.    --  list that have this flag set to True should only be displayed by the 
  186.    --  applications that have registered them. 
  187.  
  188.    function Get_Uri (Info : access Gtk_Recent_Info_Record) return UTF8_String; 
  189.    --  Gets the URI of the resource. 
  190.  
  191.    function Get_Visited (Info : access Gtk_Recent_Info_Record) return time_t; 
  192.    --  Gets the timestamp (seconds from system's Epoch) when the resource 
  193.    --  was last visited. Returns -1 on failure. 
  194.  
  195.    function Has_Application 
  196.      (Info     : access Gtk_Recent_Info_Record; 
  197.       App_Name : UTF8_String) 
  198.       return Boolean; 
  199.    --  Checks whether an application registered this resource using 
  200.    --  App_Name. 
  201.  
  202.    function Has_Group 
  203.      (Info       : access Gtk_Recent_Info_Record; 
  204.       Group_Name : UTF8_String) 
  205.       return Boolean; 
  206.    --  Checks whether Group_Name appears inside the groups registered for 
  207.    --  the recently used item Info. 
  208.  
  209.    function Is_Local (Info : access Gtk_Recent_Info_Record) return Boolean; 
  210.    --  Checks whether the resource is local or not by looking at the 
  211.    --  scheme of its URI. 
  212.  
  213.    function Match 
  214.      (Info_A : access Gtk_Recent_Info_Record'Class; 
  215.       Info_B : access Gtk_Recent_Info_Record'Class) 
  216.       return Boolean; 
  217.    --  Checks whether two Gtk_Recent_Info structures point to the same 
  218.    --  resource. 
  219.  
  220.    function Ref (Info : access Gtk_Recent_Info_Record) return Gtk_Recent_Info; 
  221.    --  Increases the reference count of Recent_Info by one. 
  222.  
  223.    procedure Unref (Info : access Gtk_Recent_Info_Record); 
  224.    --  Decreases the reference count of Info by one.  If the reference 
  225.    --  count reaches zero, Info is deallocated, and the memory freed. 
  226.  
  227.    -------------------- 
  228.    -- Recent_Manager -- 
  229.    -------------------- 
  230.  
  231.    procedure Gtk_New (Widget : out Gtk_Recent_Manager); 
  232.    procedure Initialize (Widget : access Gtk_Recent_Manager_Record'Class); 
  233.    --  Creates a new recent manager object.  Recent manager objects are used to 
  234.    --  handle the list of recently used resources.  A Gtk_Recent_Manager object 
  235.    --  monitors the recently used resources list, and emits the "changed" 
  236.    --  signal each time something inside the list changes. 
  237.    -- 
  238.    --  Gtk_Recent_Manager objects are expensive: be sure to create them only 
  239.    --  when needed. You should use Gtk.Recent_Manager.Get_Default instead. 
  240.  
  241.    function Get_Type return GType; 
  242.    --  Return the internal value associated with a Gtk_Recent_Manager widget. 
  243.  
  244.    function Error_Quark return GQuark; 
  245.  
  246.    function Add_Full 
  247.      (Manager      : access Gtk_Recent_Manager_Record; 
  248.       Uri          : UTF8_String; 
  249.       Display_Name : UTF8_String := ""; 
  250.       Description  : UTF8_String := ""; 
  251.       Mime_Type    : UTF8_String; 
  252.       App_Name     : UTF8_String; 
  253.       App_Exec     : UTF8_String; 
  254.       Groups       : GNAT.Strings.String_List; 
  255.       Is_Private   : Boolean) 
  256.       return Boolean; 
  257.    --  Manager      : the Gtk_Recent_Manager on which to operate 
  258.    --  Uri          : pointer to resource 
  259.    --  Display_Name : a UTF-8 encoded string, containing the name of the 
  260.    --                 recently used resource to be displayed, or "". 
  261.    --  Description  : a UTF-8 encoded string, containing a short description 
  262.    --                 of the resource, or "". 
  263.    --  Mime_Type    : the MIME type of the resource. 
  264.    --  App_Name     : the name of the application that is registering this 
  265.    --                 recently used resource. 
  266.    --  App_Exec     : command line used to launch this resource; may contain 
  267.    --                 the "%f" and "%u" escape characters which will be 
  268.    --                 expanded to the resource file path and URI, respectively, 
  269.    --                 when the command line is retrieved. 
  270.    --  Groups       : a vector of strings containing groups names. 
  271.    --  Is_Private   : whether this resource should be displayed only by the 
  272.    --                 applications that have registered it or not. 
  273.    -- 
  274.    --  Adds a new resource, pointed by Uri, into the recently used 
  275.    --  resources list, using the metadata specified. 
  276.    -- 
  277.    --  The passed URI will be used to identify this resource inside the 
  278.    --  list. 
  279.    -- 
  280.    --  In order to register the new recently used resource, metadata about 
  281.    --  the resource must be passed as well as the URI.  This metadata must 
  282.    --  contain the MIME type of the resource pointed by the URI; the name of 
  283.    --  the application that is registering the item, and a command line to be 
  284.    --  used when launching the item. 
  285.    -- 
  286.    --  Optionally, it is possible to specify a UTF-8 string to be used when 
  287.    --  viewing the item instead of the last component of the URI; a short 
  288.    --  description of the item; whether the item should be considered private - 
  289.    --  that is, should be displayed only by the applications that have 
  290.    --  registered it. 
  291.    -- 
  292.    --  Returns True if the new item was successfully added to the recently 
  293.    --  used resources list, False otherwise. 
  294.  
  295.    function Add_Item 
  296.      (Manager : access Gtk_Recent_Manager_Record; 
  297.       Uri     : UTF8_String) 
  298.       return Boolean; 
  299.    --  Adds a new resource, pointed by Uri, into the recently used 
  300.    --  resources list. 
  301.    -- 
  302.    --  This function automatically retrieves some of the needed 
  303.    --  metadata and setting other metadata to common default values; it 
  304.    --  then feeds the data to Add_Full. 
  305.    -- 
  306.    --  See Add_Full if you want to explicitly define the metadata for the 
  307.    --  resource pointed by Uri. 
  308.    -- 
  309.    --  Returns True if the new item was successfully added to the recently 
  310.    --  used resources list 
  311.  
  312.    function Get_Default return Gtk_Recent_Manager; 
  313.    --  Gets a unique instance of Gtk_Recent_Manager that you can share 
  314.    --  in your application without caring about memory management. The 
  315.    --  returned instance will be freed when you application terminates. 
  316.    -- 
  317.    --  Do not ref or unref the returned manager. 
  318.  
  319.    function Get_Items 
  320.      (Manager : access Gtk_Recent_Manager_Record) 
  321.       return Gtk_Recent_Info_List.Glist; 
  322.    --  Gets the list of recently used resources.  Use Unref on each item 
  323.    --  inside the list, and then free the list itself using 
  324.    --  Glib.Object.Object_Simple_List.Free. 
  325.  
  326.    function Get_Limit (Manager : access Gtk_Recent_Manager_Record) return Gint; 
  327.    procedure Set_Limit 
  328.      (Manager : access Gtk_Recent_Manager_Record; 
  329.       Limit   : Gint); 
  330.    --  Maximum number of items that the Get_Items function should return. 
  331.    --  If Limit is set to -1, then return all the items. 
  332.  
  333.    function Has_Item 
  334.      (Manager : access Gtk_Recent_Manager_Record; 
  335.       Uri     : UTF8_String) 
  336.       return Boolean; 
  337.    --  Checks whether there is a recently used resource registered 
  338.    --  with Uri inside the recent manager. 
  339.  
  340.    function Lookup_Item 
  341.      (Manager : access Gtk_Recent_Manager_Record; 
  342.       Uri     : UTF8_String; 
  343.       Error   : Glib.Error.GError) 
  344.       return Gtk_Recent_Info; 
  345.    --  Searches for a URI inside the recently used resources list, and 
  346.    --  returns a structure containing information about the resource 
  347.    --  like its MIME type, or its display name. 
  348.    -- 
  349.    --  Returns null if the URI was not registered in the recently used 
  350.    --  resources list.  Free with Unref. 
  351.  
  352.    function Move_Item 
  353.      (Manager : access Gtk_Recent_Manager_Record; 
  354.       Uri     : UTF8_String; 
  355.       New_Uri : UTF8_String; 
  356.       Error   : Glib.Error.GError) 
  357.       return Boolean; 
  358.    --  Changes the location of a recently used resource from Uri to New_Uri. 
  359.    --  A New_Uri of "" will remove the item pointed to by Uri in the list. 
  360.    -- 
  361.    --  Please note that this function will not affect the resource pointed 
  362.    --  by the URIs, but only the URI used in the recently used resources list. 
  363.  
  364.    function Purge_Items 
  365.      (Manager : access Gtk_Recent_Manager_Record; 
  366.       Error   : Glib.Error.GError) 
  367.       return Gint; 
  368.    --  Purges every item from the recently used resources list. 
  369.    -- 
  370.    --  Returns the number of items that have been removed from the 
  371.    --  recently used resources list. 
  372.  
  373.    function Remove_Item 
  374.      (Manager : access Gtk_Recent_Manager_Record; 
  375.       Uri     : UTF8_String; 
  376.       Error   : Glib.Error.GError) 
  377.       return Boolean; 
  378.    --  Removes a resource pointed by Uri from the recently used resources 
  379.    --  list handled by a recent manager. 
  380.  
  381.    ----------------- 
  382.    -- Obsolescent -- 
  383.    ----------------- 
  384.  
  385.    function Get_For_Screen 
  386.      (Screen : access Gdk.Screen.Gdk_Screen_Record) return Gtk_Recent_Manager; 
  387.    pragma Obsolescent;  --  Get_For_Screen 
  388.    --  Gets the recent manager object associated with Screen; if this 
  389.    --  function has not previously been called for the given screen, 
  390.    --  a new recent manager object will be created and associated with 
  391.    --  the screen. Recent manager objects are fairly expensive to create, 
  392.    --  so using this function is usually a better choice than calling 
  393.    --  New and setting the screen yourself; by using this function a single 
  394.    --  recent manager object will be shared between users. 
  395.    -- 
  396.    --  Return value: A unique Gtk_Recent_Manager associated with the given 
  397.    --  screen. This recent manager is associated to the with the screen 
  398.    --  and can be used as long as the screen is open. Do not ref or 
  399.    --  unref it. 
  400.    -- 
  401.    --  Deprecated: 2.12: This function has been deprecated and should 
  402.    --  not be used in newly written code. Calling this function is 
  403.    --  equivalent to calling Get_Default. 
  404.  
  405.    procedure Set_Screen 
  406.      (Manager : access Gtk_Recent_Manager_Record; 
  407.       Screen  : access Gdk.Screen.Gdk_Screen_Record'Class); 
  408.    pragma Obsolescent;  --  Set_Screen 
  409.    --  Sets the screen for a recent manager; the screen is used to 
  410.    --  track the user's currently configured recently used documents 
  411.    --  storage. 
  412.    -- 
  413.    --  Deprecated: 2.12: This function has been deprecated and should 
  414.    --  not be used in newly written code. Calling this function has 
  415.    --  no effect. 
  416.  
  417.    ---------------- 
  418.    -- Properties -- 
  419.    ---------------- 
  420.  
  421.    --  <properties> 
  422.    --  Name:  Filename_Property 
  423.    --  Type:  String 
  424.    --  Descr: The full path to the file to be used to store and read the list 
  425.    -- 
  426.    --  Name:  Limit_Property 
  427.    --  Type:  Int 
  428.    --  Descr: The maximum number of items to be returned by 
  429.    --         Gtk.Recent_Manager.Get_Items 
  430.    -- 
  431.    --  Name:  Size_Property 
  432.    --  Type:  Int 
  433.    --  Descr: The size of the recently used resources list 
  434.    -- 
  435.    --  </properties> 
  436.  
  437.    Filename_Property : constant Glib.Properties.Property_String; 
  438.    Limit_Property    : constant Glib.Properties.Property_Int; 
  439.    Size_Property     : constant Glib.Properties.Property_Int; 
  440.  
  441. private 
  442.  
  443.    type Gtk_Recent_Manager_Record is 
  444.      new Glib.Object.GObject_Record with null record; 
  445.  
  446.    type Gtk_Recent_Info_Record is 
  447.      new Glib.Object.GObject_Record with null record; 
  448.  
  449.    Filename_Property : constant Glib.Properties.Property_String := 
  450.      Glib.Properties.Build ("filename"); 
  451.    Limit_Property : constant Glib.Properties.Property_Int := 
  452.      Glib.Properties.Build ("limit"); 
  453.    Size_Property : constant Glib.Properties.Property_Int := 
  454.      Glib.Properties.Build ("size"); 
  455.  
  456.    pragma Import (C, Error_Quark, "gtk_recent_manager_error_quark"); 
  457.    pragma Import (C, Get_Type, "gtk_recent_manager_get_type"); 
  458.    pragma Import (C, Get_Type_Recent_Info, "gtk_recent_info_get_type"); 
  459.  
  460. end Gtk.Recent_Manager;