gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.RecentManager

Contents

- Exported types
- Methods
  - addFull
  - addItem
  - getDefault
  - getItems
  - hasItem
  - lookupItem
  - moveItem
  - new
  - purgeItems
  - removeItem
- Properties
  - filename
  - size
- Signals
  - changed

Description

Manages and looks 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.

`GtkRecentManager` acts like a database of all the recently used files. You can create new `GtkRecentManager` 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 `GtkRecentManager` 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`.

Note that the maximum age of the recently used files list is controllable through the Settings:gtkRecentFilesMaxAge property.

Synopsis

- newtype RecentManager = RecentManager (ManagedPtr RecentManager)
- class (GObject o, IsDescendantOf RecentManager o) => IsRecentManager o
- toRecentManager :: (MonadIO m, IsRecentManager o) => o -> m 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, MonadIO m) => Text -> m (GValueConstruct o)
- getRecentManagerFilename :: (MonadIO m, IsRecentManager o) => o -> m (Maybe Text)
- getRecentManagerSize :: (MonadIO m, IsRecentManager o) => o -> m Int32
- type RecentManagerChangedCallback = IO ()
- afterRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> ((?self :: a) => RecentManagerChangedCallback) -> m SignalHandlerId
- onRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> ((?self :: a) => RecentManagerChangedCallback) -> m SignalHandlerId

# Exported types

newtype RecentManager Source #

Memory-managed wrapper type.

Constructors

RecentManager (ManagedPtr RecentManager) |

#### Instances

Instances details

Eq RecentManager Source # |
Instance details Defined in GI.Gtk.Objects.RecentManager Methods (==) :: RecentManager -> RecentManager -> Bool Source # (/=) :: RecentManager -> RecentManager -> Bool Source #
GObject RecentManager Source # |
Instance details Defined in GI.Gtk.Objects.RecentManager
ManagedPtrNewtype RecentManager Source # |
Instance details Defined in GI.Gtk.Objects.RecentManager Methods toManagedPtr :: RecentManager -> ManagedPtr RecentManager Source #
TypedObject RecentManager Source # |
Instance details Defined in GI.Gtk.Objects.RecentManager Methods glibType :: IO GType Source #
HasParentTypes RecentManager Source # |
Instance details Defined in GI.Gtk.Objects.RecentManager
IsGValue (Maybe RecentManager) Source # | Convert `RecentManager` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.RecentManager Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe RecentManager -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe RecentManager) Source #
type ParentTypes RecentManager Source # |
Instance details Defined in GI.Gtk.Objects.RecentManager type ParentTypes RecentManager = '[Object]

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

Instances details

(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`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

addFull, addItem, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, hasItem, isFloating, lookupItem, moveItem, notify, notifyByPspec, purgeItems, ref, refSink, removeItem, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getItems, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## addFull

recentManagerAddFull Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> 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 `GtkRecentData` 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 `GtkRecentData`, 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 `GtkRecentData` 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.

## addItem

recentManagerAddItem Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> 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`.

## getDefault

recentManagerGetDefault Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m RecentManager | Returns: A unique `GtkRecentManager`. Do not ref or unref it.

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

## getItems

recentManagerGetItems Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> m [RecentInfo] | Returns: a list of newly allocated `GtkRecentInfo 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.

## hasItem

recentManagerHasItem Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> 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.

## lookupItem

recentManagerLookupItem Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> Text | `uri`: a URI
-> m (Maybe RecentInfo) | Returns: a `GtkRecentInfo` 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 `GtkRecentInfo` containing information about the resource like its MIME type, or its display name.

## moveItem

recentManagerMoveItem Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> 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.

## new

recentManagerNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m RecentManager | Returns: A newly created `GtkRecentManager` object

Creates a new recent manager object.

Recent manager objects are used to handle the list of recently used resources. A `GtkRecentManager` object monitors the recently used resources list, and emits the RecentManager::changed signal each time something inside the list changes.

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

## purgeItems

recentManagerPurgeItems Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> 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.

## removeItem

recentManagerRemoveItem Source #

Arguments

:: (HasCallStack, MonadIO m, IsRecentManager a) |
=> a | `manager`: a `GtkRecentManager`
-> 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.

# Properties

## filename

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

constructRecentManagerFilename :: (IsRecentManager o, MonadIO m) => Text -> m (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.

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

Emitted when the current recently used resources manager changes its contents.

This can happen either by calling `recentManagerAddItem` or by another application.

afterRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> ((?self :: 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

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onRecentManagerChanged :: (IsRecentManager a, MonadIO m) => a -> ((?self :: 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