File: gtk-recent_manager.ads

------------------------------------------------------------------------------

--                                                                          --

--      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       --

--                     Copyright (C) 2000-2014, AdaCore                     --

--                                                                          --

-- This library is free software;  you can redistribute it and/or modify it --

-- under terms of the  GNU General Public License  as published by the Free --

-- Software  Foundation;  either version 3,  or (at your  option) any later --

-- version. This library is distributed in the hope that it will be useful, --

-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --

-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            --

--                                                                          --

-- As a special exception under Section 7 of GPL version 3, you are granted --

-- additional permissions described in the GCC Runtime Library Exception,   --

-- version 3.1, as published by the Free Software Foundation.               --

--                                                                          --

-- You should have received a copy of the GNU General Public License and    --

-- a copy of the GCC Runtime Library Exception along with this program;     --

-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --

-- <http://www.gnu.org/licenses/>.                                          --

--                                                                          --

------------------------------------------------------------------------------

```
 
```
```
--  <description> 
```

--  Gtk.Recent_Manager.Gtk_Recent_Manager provides a facility for adding,

--  removing and looking up recently used files. Each recently used file is

--  identified by its URI, and has meta-data associated to it, like the names

--  and command lines of the applications that have registered it, the number

--  of time each application has registered the same file, the mime type of the

--  file and whether the file should be displayed only by the applications that

```
--  have registered it. 
```
```
-- 
```
```
--  Note: 
```
```
-- 
```

--  The recently used files list is per user.

```
-- 
```

--  The Gtk.Recent_Manager.Gtk_Recent_Manager acts like a database of all the

--  recently used files. You can create new

--  Gtk.Recent_Manager.Gtk_Recent_Manager objects, but it is more efficient to

--  use the default manager created by GTK+.

```
-- 
```

--  Adding a new recently used file is as simple as:

```
-- 
```
```
--  |[ GtkRecentManager *manager; 
```
```
-- 
```

--  manager = gtk_recent_manager_get_default (); gtk_recent_manager_add_item

```
--  (manager, file_uri); ]| 
```
```
-- 
```

--  The Gtk.Recent_Manager.Gtk_Recent_Manager will try to gather all the

--  needed information from the file itself through GIO.

```
-- 
```

--  Looking up the meta-data associated with a recently used file given its

--  URI requires calling Gtk.Recent_Manager.Lookup_Item:

```
-- 
```

--  |[ GtkRecentManager *manager; GtkRecentInfo *info; GError *error = NULL;

```
-- 
```

--  manager = gtk_recent_manager_get_default (); info =

--  gtk_recent_manager_lookup_item (manager, file_uri, &amp;error); if (error)

--  { g_warning ("Could not find the file: %s", error->message); g_error_free

--  (error); } else { /* Use the info object */ gtk_recent_info_unref (info); }

```
--  ]| 
```
```
-- 
```

--  In order to retrieve the list of recently used files, you can use

--  Gtk.Recent_Manager.Get_Items, which returns a list of

--  Gtk.Recent_Info.Gtk_Recent_Info structures.

```
-- 
```

--  A Gtk.Recent_Manager.Gtk_Recent_Manager is the model used to populate the

--  contents of one, or more Gtk.Recent_Chooser.Gtk_Recent_Chooser

```
--  implementations. 
```
```
-- 
```
```
--  Note: 
```
```
-- 
```

--  The maximum age of the recently used files list is controllable through

--  the Gtk.Settings.Gtk_Settings:gtk-recent-files-max-age property.

```
-- 
```

--  Recently used files are supported since GTK+ 2.10.

```
-- 
```
```
--  </description> 
```
```
--  <description> 
```

--  In case the default screen is being used, adding a new recently used file

```
--  is as simple as: 
```
```
-- 
```
```
--  
```
```
--      declare 
```

--         Manager : constant Gtk_Recent_Manager := Get_Default;

```
--      begin 
```

--         Add_Item (Manager, File_URI);

```
--      end; 
```
```
-- 
```

--  While looking up a recently used file is as simple as using:

```
-- 
```
```
--  
```
```
--      declare 
```

--         Manager : constant Gtk_Recent_Manager := Get_Default;

```
--         Info    : Gtk_Recent_Info; 
```

--         Error   : Glib.Error.GError;

```
--      begin 
```

--         Lookup_Item (Info, Manager, File_URI, Error);

```
--         if Error /= null then 
```
```
--            --  Use the info object 
```
```
--            Unref (Info); 
```
```
--         else 
```
```
--            Put_Line 
```

--              ("Could not find the file: " & Glib.Error.Get_Message (Error));

--            Glib.Error.Error_Free (Error);

```
--         end if; 
```
```
--      end; 
```
```
--       
```
```
-- 
```
```
--  </description> 
```
```
pragma Ada_2005; 
```
```
 
```

pragma Warnings (Off, "*is already use-visible*");

with GNAT.Strings;         use GNAT.Strings;

with GlibTo API doc
To spec
To body;                 use GlibTo API doc
To spec
To body;

with Glib.GlistTo API doc
To spec
To body;           use Glib.GlistTo API doc
To spec
To body;

with Glib.ObjectTo API doc
To spec
To body;          use Glib.ObjectTo API doc
To spec
To body;

with Glib.PropertiesTo API doc
To spec
To body;      use Glib.PropertiesTo API doc
To spec
To body;

with Gtk.Recent_InfoTo API doc
To spec
To body;      use Gtk.Recent_InfoTo API doc
To spec
To body;

with Interfaces.C.Strings; use Interfaces.C.Strings;

```
 
```

package Gtk.Recent_ManagerTo API doc
To spec
To body is

```
 
```

   type Gtk_Recent_Manager_Record is new GObject_RecordTo API doc
To spec
To body with null record;

   type Gtk_Recent_Manager is access all Gtk_Recent_Manager_RecordTo API doc
To spec'Class;

```
 
```
```
   type Gtk_Recent_Data is record 
```

      Display_Name : Interfaces.C.Strings.chars_ptr;

      Description : Interfaces.C.Strings.chars_ptr;

      Mime_Type : Interfaces.C.Strings.chars_ptr;

      App_Name : Interfaces.C.Strings.chars_ptr;

      App_Exec : Interfaces.C.Strings.chars_ptr;

      Groups : Interfaces.C.Strings.char_array_access;

```
      Is_Private : Boolean; 
```
```
   end record; 
```

   pragma Convention (C, Gtk_Recent_DataTo API doc
To spec);

```
 
```

   function From_Object_FreeTo API doc
To body (B : access Gtk_Recent_DataTo API doc
To spec) return Gtk_Recent_DataTo API doc
To spec;

   pragma Inline (From_Object_FreeTo API doc
To spec
To body);

   --  Meta-data to be passed to gtk_recent_manager_add_full when registering

```
   --  a recently used resource. 
```
```
 
```

   function ConvertTo API doc
To body (RTo API doc
To body : Gtk.Recent_Info.Gtk_Recent_InfoTo API doc
To spec) return System.Address;

   function ConvertTo API doc
To body (R : System.Address) return Gtk.Recent_Info.Gtk_Recent_InfoTo API doc
To spec;

   package Gtk_Recent_Info_List is new Generic_ListTo API doc
To spec
To body (Gtk.Recent_Info.Gtk_Recent_InfoTo API doc
To spec);

```
 
```
```
   ------------------ 
```
```
   -- Constructors -- 
```
```
   ------------------ 
```
```
 
```

   procedure Gtk_NewTo API doc
To body (Self : out Gtk_Recent_ManagerTo API doc
To spec);

   procedure InitializeTo API doc
To body

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec'Class);

   --  Creates a new recent manager object. Recent manager objects are used to

   --  handle the list of recently used resources. A

   --  Gtk.Recent_Manager.Gtk_Recent_Manager object monitors the recently used

   --  resources list, and emits the "changed" signal each time something

```
   --  inside the list changes. 
```

   --  Gtk.Recent_Manager.Gtk_Recent_Manager objects are expensive: be sure to

   --  create them only when needed. You should use

   --  Gtk.Recent_Manager.Get_Default instead.

```
   --  Since: gtk+ 2.10 
```
```
 
```

   function Gtk_Recent_Manager_NewTo API doc
To body return Gtk_Recent_ManagerTo API doc
To spec;

   --  Creates a new recent manager object. Recent manager objects are used to

   --  handle the list of recently used resources. A

   --  Gtk.Recent_Manager.Gtk_Recent_Manager object monitors the recently used

   --  resources list, and emits the "changed" signal each time something

```
   --  inside the list changes. 
```

   --  Gtk.Recent_Manager.Gtk_Recent_Manager objects are expensive: be sure to

   --  create them only when needed. You should use

   --  Gtk.Recent_Manager.Get_Default instead.

```
   --  Since: gtk+ 2.10 
```
```
 
```

   function Get_TypeTo API doc
To body return Glib.GTypeTo API doc
To spec;

   pragma Import (C, Get_TypeTo API doc
To spec, "gtk_recent_manager_get_type");

```
 
```
```
   ------------- 
```
```
   -- Methods -- 
```
```
   ------------- 
```
```
 
```
```
   function Add_ItemTo API doc
To body 
```

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       URI  : UTF8_StringTo API doc
To spec) return Boolean;

   --  Adds a new resource, pointed by Uri, into the recently used resources

```
   --  list. 
```

   --  This function automatically retrieves some of the needed metadata and

   --  setting other metadata to common default values; it then feeds the data

```
   --  to gtk_recent_manager_add_full. 
```

   --  See gtk_recent_manager_add_full if you want to explicitly define the

   --  metadata for the resource pointed by Uri.

```
   --  Since: gtk+ 2.10 
```
```
   --  "uri": a valid URI 
```
```
 
```
```
   function Get_ItemsTo API doc
To body 
```

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec)

       return Gtk_Recent_Info_List.GlistTo API doc
To spec
To body;

   --  Gets the list of recently used resources.

```
   --  Since: gtk+ 2.10 
```
```
 
```
```
   function Has_ItemTo API doc
To body 
```

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       URI  : UTF8_StringTo API doc
To spec) return Boolean;

   --  Checks whether there is a recently used resource registered with Uri

```
   --  inside the recent manager. 
```
```
   --  Since: gtk+ 2.10 
```
```
   --  "uri": a URI 
```
```
 
```

   function Lookup_ItemTo API doc
To body

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       URI  : UTF8_StringTo API doc
To spec) return Gtk.Recent_Info.Gtk_Recent_InfoTo API doc
To spec;

   --  Searches for a URI inside the recently used resources list, and returns

   --  a structure containing informations about the resource like its MIME

```
   --  type, or its display name. 
```
```
   --  Since: gtk+ 2.10 
```
```
   --  "uri": a URI 
```
```
 
```
```
   function Move_ItemTo API doc
To body 
```

      (Self    : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       URI     : UTF8_StringTo API doc
To spec;

       New_Uri : UTF8_StringTo API doc
To spec := "") return Boolean;

   --  Changes the location of a recently used resource from Uri to New_Uri.

   --  Please note that this function will not affect the resource pointed by

   --  the URIs, but only the URI used in the recently used resources list.

```
   --  Since: gtk+ 2.10 
```

   --  "uri": the URI of a recently used resource

   --  "new_uri": the new URI of the recently used resource, or null to remove

   --  the item pointed by Uri in the list

```
 
```

   function Purge_ItemsTo API doc
To body

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec) return GintTo API doc
To spec;

   --  Purges every item from the recently used resources list.

```
   --  Since: gtk+ 2.10 
```
```
 
```

   function Remove_ItemTo API doc
To body

      (Self : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       URI  : UTF8_StringTo API doc
To spec) return Boolean;

   --  Removes a resource pointed by Uri from the recently used resources list

```
   --  handled by a recent manager. 
```
```
   --  Since: gtk+ 2.10 
```

   --  "uri": the URI of the item you wish to remove

```
 
```
```
   ---------------------- 
```
```
   -- GtkAda additions -- 
```
```
   ---------------------- 
```
```
 
```
```
   function Add_FullTo API doc
To body 
```

     (Manager      : access Gtk_Recent_Manager_RecordTo API doc
To spec;

      Uri          : UTF8_StringTo API doc
To spec;

      Display_Name : UTF8_StringTo API doc
To spec := "";

      Description  : UTF8_StringTo API doc
To spec := "";

      Mime_Type    : UTF8_StringTo API doc
To spec;

      App_Name     : UTF8_StringTo API doc
To spec;

      App_Exec     : UTF8_StringTo API doc
To spec;

      Groups       : GNAT.Strings.String_List;

```
      Is_Private   : Boolean) 
```
```
   return Boolean; 
```

   --  Manager      : the Gtk_Recent_Manager on which to operate

   --  Uri          : pointer to resource

   --  Display_Name : a UTF-8 encoded string, containing the name of the

   --                 recently used resource to be displayed, or "".

   --  Description  : a UTF-8 encoded string, containing a short description

   --                 of the resource, or "".

   --  Mime_Type    : the MIME type of the resource.

   --  App_Name     : the name of the application that is registering this

   --                 recently used resource.

   --  App_Exec     : command line used to launch this resource; may contain

   --                 the "%f" and "%u" escape characters which will be

   --                 expanded to the resource file path and URI, respectively,

   --                 when the command line is retrieved.

   --  Groups       : a vector of strings containing groups names.

   --  Is_Private   : whether this resource should be displayed only by the

   --                 applications that have registered it or not.

```
   -- 
```

   --  Adds a new resource, pointed by Uri, into the recently used

   --  resources list, using the metadata specified.

```
   -- 
```

   --  The passed URI will be used to identify this resource inside the

```
   --  list. 
```
```
   -- 
```

   --  In order to register the new recently used resource, metadata about

   --  the resource must be passed as well as the URI.  This metadata must

   --  contain the MIME type of the resource pointed by the URI; the name of

   --  the application that is registering the item, and a command line to be

```
   --  used when launching the item. 
```
```
   -- 
```

   --  Optionally, it is possible to specify a UTF-8 string to be used when

   --  viewing the item instead of the last component of the URI; a short

   --  description of the item; whether the item should be considered private -

   --  that is, should be displayed only by the applications that have

```
   --  registered it. 
```
```
   -- 
```

   --  Returns True if the new item was successfully added to the recently

   --  used resources list, False otherwise.

```
 
```
```
   --------------- 
```
```
   -- Functions -- 
```
```
   --------------- 
```
```
 
```

   function Get_DefaultTo API doc
To body return Gtk_Recent_ManagerTo API doc
To spec;

   --  Gets a unique instance of Gtk.Recent_Manager.Gtk_Recent_Manager, that

   --  you can share in your application without caring about memory

```
   --  management. 
```
```
   --  Since: gtk+ 2.10 
```
```
 
```
```
   ---------------- 
```
```
   -- Properties -- 
```
```
   ---------------- 
```

   --  The following properties are defined for this widget. See

   --  Glib.Properties for more information on properties)

```
 
```

   Filename_Property : constant Glib.Properties.Property_StringTo API doc
To spec;

   --  The full path to the file to be used to store and read the recently

```
   --  used resources list 
```
```
 
```

   Size_Property : constant Glib.Properties.Property_IntTo API doc
To spec;

   --  The size of the recently used resources list.

```
 
```
```
   ------------- 
```
```
   -- Signals -- 
```
```
   ------------- 
```
```
 
```

   type Cb_Gtk_Recent_Manager_Void is not null access procedure

     (Self : access Gtk_Recent_Manager_RecordTo API doc
To spec'Class);

```
 
```

   type Cb_GObject_Void is not null access procedure

     (Self : access Glib.Object.GObject_RecordTo API doc
To spec
To body'Class);

```
 
```

   Signal_Changed : constant Glib.Signal_NameTo API doc
To spec := "changed";

   procedure On_ChangedTo API doc
To body

      (Self  : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       Call  : Cb_Gtk_Recent_Manager_VoidTo API doc
To spec;

```
       After : Boolean := False); 
```

   procedure On_ChangedTo API doc
To body

      (Self  : not null access Gtk_Recent_Manager_RecordTo API doc
To spec;

       Call  : Cb_GObject_VoidTo API doc
To spec;

       Slot  : not null access Glib.Object.GObject_RecordTo API doc
To spec
To body'Class;

```
       After : Boolean := False); 
```

   --  Emitted when the current recently used resources manager changes its

   --  contents, either by calling Gtk.Recent_Manager.Add_Item or by another

```
   --  application. 
```
```
 
```
```
private 
```

   Size_PropertyTo API doc
To spec : constant Glib.Properties.Property_IntTo API doc
To spec :=

     Glib.Properties.BuildTo API doc
To spec
To body ("size");

   Filename_PropertyTo API doc
To spec : constant Glib.Properties.Property_StringTo API doc
To spec :=

     Glib.Properties.BuildTo API doc
To spec
To body ("filename");

end Gtk.Recent_ManagerTo API doc
To spec
To body;

Documentation