gi-gio-2.0.32: Gio bindings

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

GI.Gio.Objects.DesktopAppInfo

Contents

- Exported types
- Methods
  - getActionName
  - getBoolean
  - getCategories
  - getFilename
  - getGenericName
  - getImplementations
  - getIsHidden
  - getKeywords
  - getLocaleString
  - getNodisplay
  - getShowIn
  - getStartupWmClass
  - getString
  - getStringList
  - hasKey
  - launchAction
  - launchUrisAsManager
  - launchUrisAsManagerWithFds
  - listActions
  - new
  - newFromFilename
  - newFromKeyfile
  - search
  - setDesktopEnv
- Properties
  - filename

Description

`GDesktopAppInfo` is an implementation of `AppInfo` based on desktop files.

Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it.

Synopsis

- newtype DesktopAppInfo = DesktopAppInfo (ManagedPtr DesktopAppInfo)
- class (GObject o, IsDescendantOf DesktopAppInfo o) => IsDesktopAppInfo o
- toDesktopAppInfo :: (MonadIO m, IsDesktopAppInfo o) => o -> m DesktopAppInfo
- desktopAppInfoGetActionName :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Text -> m Text
- desktopAppInfoGetBoolean :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Text -> m Bool
- desktopAppInfoGetCategories :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m (Maybe Text)
- desktopAppInfoGetFilename :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m (Maybe [Char])
- desktopAppInfoGetGenericName :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m (Maybe Text)
- desktopAppInfoGetImplementations :: (HasCallStack, MonadIO m) => Text -> m [DesktopAppInfo]
- desktopAppInfoGetIsHidden :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m Bool
- desktopAppInfoGetKeywords :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m [Text]
- desktopAppInfoGetLocaleString :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Text -> m (Maybe Text)
- desktopAppInfoGetNodisplay :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m Bool
- desktopAppInfoGetShowIn :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Maybe Text -> m Bool
- desktopAppInfoGetStartupWmClass :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m (Maybe Text)
- desktopAppInfoGetString :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Text -> m (Maybe Text)
- desktopAppInfoGetStringList :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Text -> m ([Text], Word64)
- desktopAppInfoHasKey :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> Text -> m Bool
- desktopAppInfoLaunchAction :: (HasCallStack, MonadIO m, IsDesktopAppInfo a, IsAppLaunchContext b) => a -> Text -> Maybe b -> m ()
- desktopAppInfoLaunchUrisAsManager :: (HasCallStack, MonadIO m, IsDesktopAppInfo a, IsAppLaunchContext b) => a -> [Text] -> Maybe b -> [SpawnFlags] -> Maybe SpawnChildSetupFunc -> Maybe DesktopAppLaunchCallback -> m ()
- desktopAppInfoLaunchUrisAsManagerWithFds :: (HasCallStack, MonadIO m, IsDesktopAppInfo a, IsAppLaunchContext b) => a -> [Text] -> Maybe b -> [SpawnFlags] -> Maybe SpawnChildSetupFunc -> Maybe DesktopAppLaunchCallback -> Int32 -> Int32 -> Int32 -> m ()
- desktopAppInfoListActions :: (HasCallStack, MonadIO m, IsDesktopAppInfo a) => a -> m [Text]
- desktopAppInfoNew :: (HasCallStack, MonadIO m) => Text -> m (Maybe DesktopAppInfo)
- desktopAppInfoNewFromFilename :: (HasCallStack, MonadIO m) => [Char] -> m (Maybe DesktopAppInfo)
- desktopAppInfoNewFromKeyfile :: (HasCallStack, MonadIO m) => KeyFile -> m (Maybe DesktopAppInfo)
- desktopAppInfoSearch :: (HasCallStack, MonadIO m) => Text -> m [[Text]]
- desktopAppInfoSetDesktopEnv :: (HasCallStack, MonadIO m) => Text -> m ()
- constructDesktopAppInfoFilename :: (IsDesktopAppInfo o, MonadIO m) => Text -> m (GValueConstruct o)
- getDesktopAppInfoFilename :: (MonadIO m, IsDesktopAppInfo o) => o -> m (Maybe Text)

# Exported types

newtype DesktopAppInfo Source #

Memory-managed wrapper type.

Constructors

DesktopAppInfo (ManagedPtr DesktopAppInfo) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf DesktopAppInfo o) => IsDesktopAppInfo o Source #

Type class for types which can be safely cast to `DesktopAppInfo`, for instance with `toDesktopAppInfo`.

#### Instances

Instances details

(GObject o, IsDescendantOf DesktopAppInfo o) => IsDesktopAppInfo o Source # |
Instance details Defined in GI.Gio.Objects.DesktopAppInfo

toDesktopAppInfo :: (MonadIO m, IsDesktopAppInfo o) => o -> m DesktopAppInfo Source #

Cast to `DesktopAppInfo`, 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

addSupportsType, bindProperty, bindPropertyFull, canDelete, canRemoveSupportsType, delete, dup, equal, forceFloating, freezeNotify, getv, hasKey, isFloating, launch, launchAction, launchUris, launchUrisAsManager, launchUrisAsManagerWithFds, launchUrisAsync, launchUrisFinish, listActions, notify, notifyByPspec, ref, refSink, removeSupportsType, runDispose, shouldShow, stealData, stealQdata, supportsFiles, supportsUris, thawNotify, unref, watchClosure.

#### Getters

getActionName, getBoolean, getCategories, getCommandline, getData, getDescription, getDisplayName, getExecutable, getFilename, getGenericName, getIcon, getId, getIsHidden, getKeywords, getLocaleString, getName, getNodisplay, getProperty, getQdata, getShowIn, getStartupWmClass, getString, getStringList, getSupportedTypes.

#### Setters

setAsDefaultForExtension, setAsDefaultForType, setAsLastUsedForType, setData, setDataFull, setProperty.

## getActionName

desktopAppInfoGetActionName Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `actionName`: the name of the action as from `desktopAppInfoListActions`
-> m Text | Returns: the locale-specific action name

Gets the user-visible display name of the "additional application action" specified by `actionName`.

This corresponds to the "Name" key within the keyfile group for the action.

Since: 2.38

## getBoolean

desktopAppInfoGetBoolean Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `key`: the key to look up
-> m Bool | Returns: the boolean value, or `False` if the key is not found

Looks up a boolean value in the keyfile backing `info`.

The `key` is looked up in the "Desktop Entry" group.

Since: 2.36

## getCategories

desktopAppInfoGetCategories Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> m (Maybe Text) | Returns: The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it.

Gets the categories from the desktop file.

## getFilename

desktopAppInfoGetFilename Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> m (Maybe [Char]) | Returns: The full path to the file for `info`, or `Nothing` if not known.

When `info` was created from a known filename, return it. In some situations such as the `DesktopAppInfo` returned from `desktopAppInfoNewFromKeyfile`, this function will return `Nothing`.

Since: 2.24

## getGenericName

desktopAppInfoGetGenericName Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> m (Maybe Text) | Returns: The value of the GenericName key

Gets the generic name from the desktop file.

## getImplementations

desktopAppInfoGetImplementations Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `interface`: the name of the interface
-> m [DesktopAppInfo] | Returns: a list of `DesktopAppInfo` objects.

Gets all applications that implement `interface`.

An application implements an interface if that interface is listed in the Implements= line of the desktop file of the application.

Since: 2.42

## getIsHidden

desktopAppInfoGetIsHidden Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`.
-> m Bool | Returns: `True` if hidden, `False` otherwise.

A desktop file is hidden if the Hidden key in it is set to True.

## getKeywords

desktopAppInfoGetKeywords Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> m [Text] | Returns: The value of the Keywords key

Gets the keywords from the desktop file.

Since: 2.32

## getLocaleString

desktopAppInfoGetLocaleString Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `key`: the key to look up
-> m (Maybe Text) | Returns: a newly allocated string, or `Nothing` if the key is not found

Looks up a localized string value in the keyfile backing `info` translated to the current locale.

The `key` is looked up in the "Desktop Entry" group.

Since: 2.56

## getNodisplay

desktopAppInfoGetNodisplay Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> m Bool | Returns: The value of the NoDisplay key

Gets the value of the NoDisplay key, which helps determine if the application info should be shown in menus. See `KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and `appInfoShouldShow`.

Since: 2.30

## getShowIn

desktopAppInfoGetShowIn Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Maybe Text | `desktopEnv`: a string specifying a desktop name
-> m Bool | Returns: `True` if the `info` should be shown in `desktopEnv` according to the `OnlyShowIn` and `NotShowIn` keys, `False` otherwise.

Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the `OnlyShowIn` and `NotShowIn` keys.

`desktopEnv` should typically be given as `Nothing`, in which case the `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want to override the default mechanism then you may specify `desktopEnv`, but this is not recommended.

Note that `appInfoShouldShow` for `info` will include this check (with `Nothing` for `desktopEnv`) as well as additional checks.

Since: 2.30

## getStartupWmClass

desktopAppInfoGetStartupWmClass Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo` that supports startup notify
-> m (Maybe Text) | Returns: the startup WM class, or `Nothing` if none is set in the desktop file.

Retrieves the StartupWMClass field from `info`. This represents the WM_CLASS property of the main window of the application, if launched through `info`.

Since: 2.34

## getString

desktopAppInfoGetString Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `key`: the key to look up
-> m (Maybe Text) | Returns: a newly allocated string, or `Nothing` if the key is not found

Looks up a string value in the keyfile backing `info`.

The `key` is looked up in the "Desktop Entry" group.

Since: 2.36

## getStringList

desktopAppInfoGetStringList Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `key`: the key to look up
-> m ([Text], Word64) | Returns: a `Nothing`-terminated string array or `Nothing` if the specified key cannot be found. The array should be freed with `strfreev`.

Looks up a string list value in the keyfile backing `info`.

The `key` is looked up in the "Desktop Entry" group.

Since: 2.60

## hasKey

desktopAppInfoHasKey Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `key`: the key to look up
-> m Bool | Returns: `True` if the `key` exists

Returns whether `key` exists in the "Desktop Entry" group of the keyfile backing `info`.

Since: 2.36

## launchAction

desktopAppInfoLaunchAction Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a, IsAppLaunchContext b) |
=> a | `info`: a `DesktopAppInfo`
-> Text | `actionName`: the name of the action as from `desktopAppInfoListActions`
-> Maybe b | `launchContext`: a `AppLaunchContext`
-> m () |

Activates the named application action.

You may only call this function on action names that were returned from `desktopAppInfoListActions`.

Note that if the main entry of the desktop file indicates that the application supports startup notification, and `launchContext` is non-`Nothing`, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional actions, as per the desktop file specification.

As with `appInfoLaunch` there is no way to detect failures that occur while using this function.

Since: 2.38

## launchUrisAsManager

desktopAppInfoLaunchUrisAsManager Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a, IsAppLaunchContext b) |
=> a | `appinfo`: a `DesktopAppInfo`
-> [Text] | `uris`: List of URIs
-> Maybe b | `launchContext`: a `AppLaunchContext`
-> [SpawnFlags] | `spawnFlags`: `SpawnFlags`, used for each process
-> Maybe SpawnChildSetupFunc | `userSetup`: a `SpawnChildSetupFunc`, used once for each process.
-> Maybe DesktopAppLaunchCallback | `pidCallback`: Callback for child processes
-> m () | (Can throw `GError`)

This function performs the equivalent of `appInfoLaunchUris`, but is intended primarily for operating system components that launch applications. Ordinary applications should use `appInfoLaunchUris`.

If the application is launched via GSpawn, then `spawnFlags`, `userSetup` and `userSetupData` are used for the call to `spawnAsync`. Additionally, `pidCallback` (with `pidCallbackData`) will be called to inform about the PID of the created process. See `spawnAsyncWithPipes` for information on certain parameter conditions that can enable an optimized `posix_spawn()` codepath to be used.

If application launching occurs via some other mechanism (eg: D-Bus activation) then `spawnFlags`, `userSetup`, `userSetupData`, `pidCallback` and `pidCallbackData` are ignored.

## launchUrisAsManagerWithFds

desktopAppInfoLaunchUrisAsManagerWithFds Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a, IsAppLaunchContext b) |
=> a | `appinfo`: a `DesktopAppInfo`
-> [Text] | `uris`: List of URIs
-> Maybe b | `launchContext`: a `AppLaunchContext`
-> [SpawnFlags] | `spawnFlags`: `SpawnFlags`, used for each process
-> Maybe SpawnChildSetupFunc | `userSetup`: a `SpawnChildSetupFunc`, used once for each process.
-> Maybe DesktopAppLaunchCallback | `pidCallback`: Callback for child processes
-> Int32 | `stdinFd`: file descriptor to use for child's stdin, or -1
-> Int32 | `stdoutFd`: file descriptor to use for child's stdout, or -1
-> Int32 | `stderrFd`: file descriptor to use for child's stderr, or -1
-> m () | (Can throw `GError`)

Equivalent to `desktopAppInfoLaunchUrisAsManager` but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process.

If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then `stdinFd`, `stdoutFd` and `stderrFd` are ignored.

Since: 2.58

## listActions

desktopAppInfoListActions Source #

Arguments

:: (HasCallStack, MonadIO m, IsDesktopAppInfo a) |
=> a | `info`: a `DesktopAppInfo`
-> m [Text] | Returns: a list of strings, always non-`Nothing`

Returns the list of "additional application actions" supported on the desktop file, as per the desktop file specification.

As per the specification, this is the list of actions that are explicitly listed in the "Actions" key of the [Desktop Entry] group.

Since: 2.38

## new

desktopAppInfoNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `desktopId`: the desktop file id
-> m (Maybe DesktopAppInfo) | Returns: a new `DesktopAppInfo`, or `Nothing` if no desktop file with that id exists.

Creates a new `DesktopAppInfo` based on a desktop file id.

A desktop file id is the basename of the desktop file, including the .desktop extension. GIO is looking for a desktop file with this name in the `applications` subdirectories of the XDG data directories (i.e. the directories specified in the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the Menu Spec (i.e. a desktop id of kde-foo.desktop will match `/usr/share/applications/kde/foo.desktop`).

## newFromFilename

desktopAppInfoNewFromFilename Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [Char] | `filename`: the path of a desktop file, in the GLib filename encoding
-> m (Maybe DesktopAppInfo) | Returns: a new `DesktopAppInfo` or `Nothing` on error.

Creates a new `DesktopAppInfo`.

## newFromKeyfile

desktopAppInfoNewFromKeyfile Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: an opened `KeyFile`
-> m (Maybe DesktopAppInfo) | Returns: a new `DesktopAppInfo` or `Nothing` on error.

Creates a new `DesktopAppInfo`.

Since: 2.18

## search

desktopAppInfoSearch Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `searchString`: the search string to use
-> m [[Text]] | Returns: a list of strvs. Free each item with `strfreev` and free the outer list with `free`.

Searches desktop files for ones that match `searchString`.

The return value is an array of strvs. Each strv contains a list of applications that matched `searchString` with an equal score. The outer list is sorted by score so that the first strv contains the best-matching applications, and so on. The algorithm for determining matches is undefined and may change at any time.

None of the search results are subjected to the normal validation checks performed by `desktopAppInfoNew` (for example, checking that the executable referenced by a result exists), and so it is possible for `desktopAppInfoNew` to return `Nothing` when passed an app ID returned by this function. It is expected that calling code will do this when subsequently creating a `DesktopAppInfo` for each result.

## setDesktopEnv

desktopAppInfoSetDesktopEnv Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `desktopEnv`: a string specifying what desktop this is
-> m () |

Deprecated: (Since version 2.42)do not use this API. Since 2.42 the value of the`XDG_CURRENT_DESKTOP` environment variable will be used.

Sets the name of the desktop that the application is running in. This is used by `appInfoShouldShow` and `desktopAppInfoGetShowIn` to evaluate the `OnlyShowIn` and `NotShowIn` desktop entry fields.

Should be called only once; subsequent calls are ignored.

# Properties

## filename

The origin filename of this `DesktopAppInfo`

constructDesktopAppInfoFilename :: (IsDesktopAppInfo 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`.

getDesktopAppInfoFilename :: (MonadIO m, IsDesktopAppInfo o) => o -> m (Maybe Text) Source #

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

    get desktopAppInfo #filename