Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (inaki@blueleaf.cc)
Safe Haskell	None
Language	Haskell2010

GI.Gtk.Objects.RecentManager

Contents

Exported types
Methods
Properties
- filename
- size
Signals
- changed

Description

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

Synopsis

newtype RecentManager = RecentManager (ManagedPtr RecentManager)
class (GObject o, IsDescendantOf RecentManager o) => IsRecentManager o
toRecentManager :: (MonadIO m, IsRecentManager o) => o -> m RecentManager
noRecentManager :: Maybe RecentManager
recentManagerAddFull :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> Text -> RecentData -> m Bool
recentManagerAddItem :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> Text -> m Bool
recentManagerGetDefault :: (HasCallStack, MonadIO m) => m RecentManager
recentManagerGetItems :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> m [RecentInfo]
recentManagerHasItem :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> Text -> m Bool
recentManagerLookupItem :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> Text -> m (Maybe RecentInfo)
recentManagerMoveItem :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> Text -> Maybe Text -> m ()
recentManagerNew :: (HasCallStack, MonadIO m) => m RecentManager
recentManagerPurgeItems :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> m Int32
recentManagerRemoveItem :: (HasCallStack, MonadIO m, IsRecentManager a) => a -> Text -> m ()
constructRecentManagerFilename :: IsRecentManager o => Text -> IO (GValueConstruct o)
getRecentManagerFilename :: (MonadIO m, IsRecentManager o) => o -> m (Maybe Text)
getRecentManagerSize :: (MonadIO m, IsRecentManager o) => o -> m Int32
type C_RecentManagerChangedCallback = Ptr () -> Ptr () -> IO ()
type RecentManagerChangedCallback = IO ()
afterRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> RecentManagerChangedCallback -> m SignalHandlerId
genClosure_RecentManagerChanged :: MonadIO m => RecentManagerChangedCallback -> m (GClosure C_RecentManagerChangedCallback)
mk_RecentManagerChangedCallback :: C_RecentManagerChangedCallback -> IO (FunPtr C_RecentManagerChangedCallback)
noRecentManagerChangedCallback :: Maybe RecentManagerChangedCallback
onRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> RecentManagerChangedCallback -> m SignalHandlerId
wrap_RecentManagerChangedCallback :: RecentManagerChangedCallback -> C_RecentManagerChangedCallback

Exported types

newtype RecentManager Source #

Memory-managed wrapper type.

Constructors

RecentManager (ManagedPtr RecentManager)

Instances

GObject RecentManager Source #
Instance details Defined in GI.Gtk.Objects.RecentManager Methods gobjectType :: IO GType #
HasParentTypes RecentManager Source #
Instance details Defined in GI.Gtk.Objects.RecentManager
type ParentTypes RecentManager Source #
Instance details Defined in GI.Gtk.Objects.RecentManager type ParentTypes RecentManager = Object ': ([] :: [Type])

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

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

Instances

(GObject o, IsDescendantOf RecentManager o) => IsRecentManager o Source #
Instance details Defined in GI.Gtk.Objects.RecentManager

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

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

noRecentManager :: Maybe RecentManager Source #

A convenience alias for Nothing :: Maybe RecentManager.

Methods

addFull

recentManagerAddFull Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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) Source #

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) Source #

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 Source #

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 () Source #

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

type RecentManagerChangedCallback = IO () Source #

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 Source #

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) Source #

Wrap the callback into a GClosure.

mk_RecentManagerChangedCallback :: C_RecentManagerChangedCallback -> IO (FunPtr C_RecentManagerChangedCallback) Source #

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

noRecentManagerChangedCallback :: Maybe RecentManagerChangedCallback Source #

A convenience synonym for Nothing :: Maybe RecentManagerChangedCallback.

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

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 Source #

Wrap a RecentManagerChangedCallback into a C_RecentManagerChangedCallback.