-----------------------------------------------------------------------
-- GtkAda - Ada95 binding for Gtk+/Gnome --
-- --
-- Copyright (C) 2010, AdaCore --
-- --
-- This library is free software; you can redistribute it and/or --
-- modify it under the terms of the GNU General Public --
-- License as published by the Free Software Foundation; either --
-- version 2 of the License, 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 --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU --
-- General Public License for more details. --
-- --
-- You should have received a copy of the GNU General Public --
-- License along with this library; if not, write to the --
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330, --
-- Boston, MA 02111-1307, USA. --
-- --
-- --
-- --
-- --
-- --
-- --
-- --
-----------------------------------------------------------------------
--
-- 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.
--
-- The Gtk_Recent_Manager acts like a database of all the recently used files.
-- You can create new Gtk_Recent_Manager objects, but it is more efficient to
-- use the standard recent manager for the Gdk_Screen so that information
-- about recently used files is shared with other people using them. 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;
--
-- Recently used files are supported since GTK+ 2.10.
--
-- 2.16.6
with GNAT.Strings;
with Glib.Error;
with Glib.Glist;
with Glib.Properties;
with Glib.Object;
with Gdk.Pixbuf;
with Gdk.Screen;
package Gtk.Recent_Manager is
type Gtk_Recent_Manager_Record is
new Glib.Object.GObject_Record with private;
type Gtk_Recent_Manager is access all Gtk_Recent_Manager_Record'Class;
subtype time_t is Long_Integer;
-- Type to interface with C's time_t type. To convert this to/from
-- an Ada type, look at Ada.Calendar.Conversion_Operations and be
-- sure to pay special attention to the ranges each type is capable
-- of representing.
-----------------
-- Recent_Info --
-----------------
type Gtk_Recent_Info_Record is
new Glib.Object.GObject_Record with private;
type Gtk_Recent_Info is access all Gtk_Recent_Info_Record'Class;
function Convert (Widget : Gtk_Recent_Info) return System.Address;
function Convert (Widget : System.Address) return Gtk_Recent_Info;
package Gtk_Recent_Info_List is
new Glib.Glist.Generic_List (Gtk_Recent_Info);
-- Instantiation of a list of Gtk_Recent_Info objects.
function Get_Type_Recent_Info return GType;
-- Return the internal value associated with a Gtk_Recent_Info widget.
function Exists (Info : access Gtk_Recent_Info_Record) return Boolean;
-- Checks whether the resource pointed to by Info still exists. At
-- the moment this check is done only on resources pointing to local
-- files.
function Get_Added (Info : access Gtk_Recent_Info_Record) return time_t;
-- Gets the timestamp (seconds from system's Epoch) when the resource
-- was added to the recently used resources list.
--
-- Return value: the number of seconds elapsed from system's Epoch when
-- the resource was added to the list, or -1 on failure.
function Get_Age (Info : access Gtk_Recent_Info_Record) return Gint;
-- Gets the number of days elapsed since the last update of the resource
-- pointed by Info.
--
-- Return value: a positive integer containing the number of days
-- elapsed since the time this resource was last modified.
type Application_Info_Record is record
Result : Boolean;
-- True if an application with App_Name has registered this resource
-- inside the recently used list, or False otherwise.
App_Exec : String_Ptr;
-- Pointer to the string containing the command line. Free using
-- Glib.Free when no longer needed.
Count : Guint;
-- The number of times this item was registered.
Time : time_t;
-- The timestamp this item was last registered for this application.
end record;
-- Information returned by Get_Application_Info, below.
function Get_Application_Info
(Info : access Gtk_Recent_Info_Record;
App_Name : String)
return Application_Info_Record;
-- Gets the data regarding the application that has registered the resource
-- pointed by Info.
--
-- If the command line contains any escape characters defined inside the
-- storage specification, they will be expanded.
function Get_Description
(Info : access Gtk_Recent_Info_Record) return UTF8_String;
-- Gets the (short) description of the resource.
function Get_Display_Name
(Info : access Gtk_Recent_Info_Record) return String;
-- Gets the name of the resource. If none has been defined, the
-- basename of the resource is obtained.
function Get_Icon
(Info : access Gtk_Recent_Info_Record;
Size : Gint)
return Gdk.Pixbuf.Gdk_Pixbuf;
-- Retrieves the icon of size Size (in pixels) associated to the
-- resource MIME type. Returns a Gdk_Pixbuf containing the icon, or
-- null. Use Glib.Object.Unref when finished using the icon.
function Get_Mime_Type
(Info : access Gtk_Recent_Info_Record) return UTF8_String;
-- Gets the MIME type of the resource.
function Get_Modified (Info : access Gtk_Recent_Info_Record) return time_t;
-- Gets the timestamp (seconds from system's Epoch) when the resource
-- was last modified. Returns -1 on failure.
function Get_Private_Hint
(Info : access Gtk_Recent_Info_Record) return Boolean;
-- Gets the value of the "private" flag. Resources in the recently used
-- list that have this flag set to True should only be displayed by the
-- applications that have registered them.
function Get_Uri (Info : access Gtk_Recent_Info_Record) return UTF8_String;
-- Gets the URI of the resource.
function Get_Visited (Info : access Gtk_Recent_Info_Record) return time_t;
-- Gets the timestamp (seconds from system's Epoch) when the resource
-- was last visited. Returns -1 on failure.
function Has_Application
(Info : access Gtk_Recent_Info_Record;
App_Name : UTF8_String)
return Boolean;
-- Checks whether an application registered this resource using
-- App_Name.
function Has_Group
(Info : access Gtk_Recent_Info_Record;
Group_Name : UTF8_String)
return Boolean;
-- Checks whether Group_Name appears inside the groups registered for
-- the recently used item Info.
function Is_Local (Info : access Gtk_Recent_Info_Record) return Boolean;
-- Checks whether the resource is local or not by looking at the
-- scheme of its URI.
function Match
(Info_A : access Gtk_Recent_Info_Record'Class;
Info_B : access Gtk_Recent_Info_Record'Class)
return Boolean;
-- Checks whether two Gtk_Recent_Info structures point to the same
-- resource.
function Ref (Info : access Gtk_Recent_Info_Record) return Gtk_Recent_Info;
-- Increases the reference count of Recent_Info by one.
procedure Unref (Info : access Gtk_Recent_Info_Record);
-- Decreases the reference count of Info by one. If the reference
-- count reaches zero, Info is deallocated, and the memory freed.
--------------------
-- Recent_Manager --
--------------------
procedure Gtk_New (Widget : out Gtk_Recent_Manager);
procedure Initialize (Widget : access Gtk_Recent_Manager_Record'Class);
-- Creates a new recent manager object. Recent manager objects are used to
-- handle the list of recently used resources. A 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 objects are expensive: be sure to create them only
-- when needed. You should use Gtk.Recent_Manager.Get_Default instead.
function Get_Type return GType;
-- Return the internal value associated with a Gtk_Recent_Manager widget.
function Error_Quark return GQuark;
function Add_Full
(Manager : access Gtk_Recent_Manager_Record;
Uri : UTF8_String;
Display_Name : UTF8_String := "";
Description : UTF8_String := "";
Mime_Type : UTF8_String;
App_Name : UTF8_String;
App_Exec : UTF8_String;
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.
function Add_Item
(Manager : access Gtk_Recent_Manager_Record;
Uri : UTF8_String)
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 Add_Full.
--
-- See Add_Full if you want to explicitly define the metadata for the
-- resource pointed by Uri.
--
-- Returns True if the new item was successfully added to the recently
-- used resources list
function Get_Default return Gtk_Recent_Manager;
-- Gets a unique instance of Gtk_Recent_Manager that you can share
-- in your application without caring about memory management. The
-- returned instance will be freed when you application terminates.
--
-- Do not ref or unref the returned manager.
function Get_Items
(Manager : access Gtk_Recent_Manager_Record)
return Gtk_Recent_Info_List.Glist;
-- Gets the list of recently used resources. Use Unref on each item
-- inside the list, and then free the list itself using
-- Glib.Object.Object_Simple_List.Free.
function Get_Limit (Manager : access Gtk_Recent_Manager_Record) return Gint;
procedure Set_Limit
(Manager : access Gtk_Recent_Manager_Record;
Limit : Gint);
-- Maximum number of items that the Get_Items function should return.
-- If Limit is set to -1, then return all the items.
function Has_Item
(Manager : access Gtk_Recent_Manager_Record;
Uri : UTF8_String)
return Boolean;
-- Checks whether there is a recently used resource registered
-- with Uri inside the recent manager.
function Lookup_Item
(Manager : access Gtk_Recent_Manager_Record;
Uri : UTF8_String;
Error : Glib.Error.GError)
return Gtk_Recent_Info;
-- Searches for a URI inside the recently used resources list, and
-- returns a structure containing information about the resource
-- like its MIME type, or its display name.
--
-- Returns null if the URI was not registered in the recently used
-- resources list. Free with Unref.
function Move_Item
(Manager : access Gtk_Recent_Manager_Record;
Uri : UTF8_String;
New_Uri : UTF8_String;
Error : Glib.Error.GError)
return Boolean;
-- Changes the location of a recently used resource from Uri to New_Uri.
-- A New_Uri of "" will remove the item pointed to by Uri in the list.
--
-- 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.
function Purge_Items
(Manager : access Gtk_Recent_Manager_Record;
Error : Glib.Error.GError)
return Gint;
-- Purges every item from the recently used resources list.
--
-- Returns the number of items that have been removed from the
-- recently used resources list.
function Remove_Item
(Manager : access Gtk_Recent_Manager_Record;
Uri : UTF8_String;
Error : Glib.Error.GError)
return Boolean;
-- Removes a resource pointed by Uri from the recently used resources
-- list handled by a recent manager.
-----------------
-- Obsolescent --
-----------------
function Get_For_Screen
(Screen : access Gdk.Screen.Gdk_Screen_Record) return Gtk_Recent_Manager;
pragma Obsolescent; -- Get_For_Screen
-- Gets the recent manager object associated with Screen; if this
-- function has not previously been called for the given screen,
-- a new recent manager object will be created and associated with
-- the screen. Recent manager objects are fairly expensive to create,
-- so using this function is usually a better choice than calling
-- New and setting the screen yourself; by using this function a single
-- recent manager object will be shared between users.
--
-- Return value: A unique Gtk_Recent_Manager associated with the given
-- screen. This recent manager is associated to the with the screen
-- and can be used as long as the screen is open. Do not ref or
-- unref it.
--
-- Deprecated: 2.12: This function has been deprecated and should
-- not be used in newly written code. Calling this function is
-- equivalent to calling Get_Default.
procedure Set_Screen
(Manager : access Gtk_Recent_Manager_Record;
Screen : access Gdk.Screen.Gdk_Screen_Record'Class);
pragma Obsolescent; -- Set_Screen
-- Sets the screen for a recent manager; the screen is used to
-- track the user's currently configured recently used documents
-- storage.
--
-- Deprecated: 2.12: This function has been deprecated and should
-- not be used in newly written code. Calling this function has
-- no effect.
----------------
-- Properties --
----------------
--
-- Name: Filename_Property
-- Type: String
-- Descr: The full path to the file to be used to store and read the list
--
-- Name: Limit_Property
-- Type: Int
-- Descr: The maximum number of items to be returned by
-- Gtk.Recent_Manager.Get_Items
--
-- Name: Size_Property
-- Type: Int
-- Descr: The size of the recently used resources list
--
--
Filename_Property : constant Glib.Properties.Property_String;
Limit_Property : constant Glib.Properties.Property_Int;
Size_Property : constant Glib.Properties.Property_Int;
private
type Gtk_Recent_Manager_Record is
new Glib.Object.GObject_Record with null record;
type Gtk_Recent_Info_Record is
new Glib.Object.GObject_Record with null record;
Filename_Property : constant Glib.Properties.Property_String :=
Glib.Properties.Build ("filename");
Limit_Property : constant Glib.Properties.Property_Int :=
Glib.Properties.Build ("limit");
Size_Property : constant Glib.Properties.Property_Int :=
Glib.Properties.Build ("size");
pragma Import (C, Error_Quark, "gtk_recent_manager_error_quark");
pragma Import (C, Get_Type, "gtk_recent_manager_get_type");
pragma Import (C, Get_Type_Recent_Info, "gtk_recent_info_get_type");
end Gtk.Recent_Manager;