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