GI.Gtk.Objects.RecentManager

RecentManager 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 recently used files list is per user.

The RecentManager acts like a database of all the recently used files. You can create new RecentManager objects, but it is more efficient to use the default manager created by GTK+.

Adding a new recently used file is as simple as:

C code

GtkRecentManager *manager;

manager = gtk_recent_manager_get_default ();
gtk_recent_manager_add_item (manager, file_uri);

The RecentManager 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 recentManagerLookupItem:

C code

GtkRecentManager *manager;
GtkRecentInfo *info;
GError *error = NULL;

manager = gtk_recent_manager_get_default ();
info = gtk_recent_manager_lookup_item (manager, file_uri, &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 recentManagerGetItems, which returns a list of RecentInfo-structs.

A RecentManager is the model used to populate the contents of one, or more RecentChooser implementations.

Note that the maximum age of the recently used files list is controllable through the Settings:gtk-recent-files-max-age property.

Recently used files are supported since GTK+ 2.10.

Since: 2.10

Exported types

newtype RecentManager

Memory-managed wrapper type.

Constructors

RecentManager (ManagedPtr RecentManager)

Instances

Eq RecentManager

Defined in GI.Gtk.Objects.RecentManager

Methods

(==) :: RecentManager -> RecentManager -> Bool

(/=) :: RecentManager -> RecentManager -> Bool

IsGValue RecentManager

Convert RecentManager to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Objects.RecentManager

Methods

toGValue :: RecentManager -> IO GValue

fromGValue :: GValue -> IO RecentManager

GObject RecentManager

Defined in GI.Gtk.Objects.RecentManager

Methods

gobjectType :: IO GType

HasParentTypes RecentManager

Defined in GI.Gtk.Objects.RecentManager

type ParentTypes RecentManager

Defined in GI.Gtk.Objects.RecentManager

type ParentTypes RecentManager = '[Object]

class (GObject o, IsDescendantOf RecentManager o) => IsRecentManager o

Type class for types which can be safely cast to RecentManager, for instance with toRecentManager.

Instances

(GObject o, IsDescendantOf RecentManager o) => IsRecentManager o

Defined in GI.Gtk.Objects.RecentManager

toRecentManager :: (MonadIO m, IsRecentManager o) => o -> m RecentManager

Cast to RecentManager, for types for which this is known to be safe. For general casts, use castTo.

noRecentManager :: Maybe RecentManager

A convenience alias for Nothing :: Maybe RecentManager.

Methods

Overloaded methods

addFull

recentManagerAddFull

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> Text

uri: a valid URI

-> RecentData

recentData: metadata of the resource

-> m Bool

Returns: True if the new item was successfully added to the recently used resources list, False otherwise

Adds a new resource, pointed by uri, into the recently used resources list, using the metadata specified inside the RecentData-struct passed in recentData.

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; the metadata is stored in a RecentData-struct, which 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, a RecentData-struct might contain 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.

Since: 2.10

addItem

recentManagerAddItem

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> Text

uri: a valid URI

-> m Bool

Returns: True if the new item was successfully added to the recently used resources list

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 recentManagerAddFull.

See recentManagerAddFull if you want to explicitly define the metadata for the resource pointed by uri.

Since: 2.10

getDefault

recentManagerGetDefault

Arguments

:: (HasCallStack, MonadIO m)

=> m RecentManager

Returns: A unique RecentManager. Do not ref or unref it.

Gets a unique instance of RecentManager, that you can share in your application without caring about memory management.

Since: 2.10

getItems

recentManagerGetItems

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> m [RecentInfo]

Returns: a list of newly allocated RecentInfo objects. Use recentInfoUnref on each item inside the list, and then free the list itself using g_list_free().

Gets the list of recently used resources.

Since: 2.10

hasItem

recentManagerHasItem

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> Text

uri: a URI

-> m Bool

Returns: True if the resource was found, False otherwise

Checks whether there is a recently used resource registered with uri inside the recent manager.

Since: 2.10

lookupItem

recentManagerLookupItem

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> Text

uri: a URI

-> m (Maybe RecentInfo)

Returns: a RecentInfo-struct containing information about the resource pointed by uri, or Nothing if the URI was not registered in the recently used resources list. Free with recentInfoUnref. (Can throw GError)

Searches for a URI inside the recently used resources list, and returns a RecentInfo-struct containing informations about the resource like its MIME type, or its display name.

Since: 2.10

moveItem

recentManagerMoveItem

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> Text

uri: the URI of a recently used resource

-> Maybe Text

newUri: the new URI of the recently used resource, or Nothing to remove the item pointed by uri in the list

-> m ()

(Can throw GError)

Changes the location of a recently used resource from uri to newUri.

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: 2.10

new

recentManagerNew

Arguments

:: (HasCallStack, MonadIO m)

=> m RecentManager

Returns: A newly created RecentManager object

Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A RecentManager object monitors the recently used resources list, and emits the “changed” signal each time something inside the list changes.

RecentManager objects are expensive: be sure to create them only when needed. You should use recentManagerGetDefault instead.

Since: 2.10

purgeItems

recentManagerPurgeItems

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> m Int32

Returns: the number of items that have been removed from the recently used resources list (Can throw GError)

Purges every item from the recently used resources list.

Since: 2.10

removeItem

recentManagerRemoveItem

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a)

=> a

manager: a RecentManager

-> Text

uri: the URI of the item you wish to remove

-> m ()

(Can throw GError)

Removes a resource pointed by uri from the recently used resources list handled by a recent manager.

Since: 2.10

Properties

filename

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

Since: 2.10

constructRecentManagerFilename :: IsRecentManager o => Text -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “filename” property. This is rarely needed directly, but it is used by new.

getRecentManagerFilename :: (MonadIO m, IsRecentManager o) => o -> m (Maybe Text)

Get the value of the “filename” property. When overloading is enabled, this is equivalent to

get recentManager #filename

size

The size of the recently used resources list.

Since: 2.10

getRecentManagerSize :: (MonadIO m, IsRecentManager o) => o -> m Int32

Get the value of the “size” property. When overloading is enabled, this is equivalent to

get recentManager #size

Signals

changed

type C_RecentManagerChangedCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type RecentManagerChangedCallback = IO ()

Emitted when the current recently used resources manager changes its contents, either by calling recentManagerAddItem or by another application.

Since: 2.10

afterRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> RecentManagerChangedCallback -> m SignalHandlerId

Connect a signal handler for the changed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after recentManager #changed callback

genClosure_RecentManagerChanged :: MonadIO m => RecentManagerChangedCallback -> m (GClosure C_RecentManagerChangedCallback)

Wrap the callback into a GClosure.

mk_RecentManagerChangedCallback :: C_RecentManagerChangedCallback -> IO (FunPtr C_RecentManagerChangedCallback)

Generate a function pointer callable from C code, from a C_RecentManagerChangedCallback.

noRecentManagerChangedCallback :: Maybe RecentManagerChangedCallback

A convenience synonym for Nothing :: Maybe RecentManagerChangedCallback.

onRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> RecentManagerChangedCallback -> m SignalHandlerId

Connect a signal handler for the changed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on recentManager #changed callback

wrap_RecentManagerChangedCallback :: RecentManagerChangedCallback -> C_RecentManagerChangedCallback

Wrap a RecentManagerChangedCallback into a C_RecentManagerChangedCallback.