GDesktopAppInfo

GDesktopAppInfo — Application information from desktop files

Functions

Properties

gchar * filename Read / Write / Construct Only

Types and Values

Object Hierarchy

    GInterface
    ╰── GDesktopAppInfoLookup
    GObject
    ╰── GDesktopAppInfo

Prerequisites

GDesktopAppInfoLookup requires GObject.

Implemented Interfaces

GDesktopAppInfo implements GAppInfo.

Includes

#include <gio/gdesktopappinfo.h>

Description

GDesktopAppInfo is an implementation of GAppInfo 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 when using it.

Functions

g_desktop_app_info_new_from_filename ()

GDesktopAppInfo *
g_desktop_app_info_new_from_filename (const char *filename);

Creates a new GDesktopAppInfo.

Parameters

filename

the path of a desktop file, in the GLib filename encoding

 

Returns

a new GDesktopAppInfo or NULL on error.


g_desktop_app_info_new_from_keyfile ()

GDesktopAppInfo *
g_desktop_app_info_new_from_keyfile (GKeyFile *key_file);

Creates a new GDesktopAppInfo.

Parameters

key_file

an opened GKeyFile

 

Returns

a new GDesktopAppInfo or NULL on error.

Since: 2.18


g_desktop_app_info_new ()

GDesktopAppInfo *
g_desktop_app_info_new (const char *desktop_id);

Creates a new GDesktopAppInfo 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).

Parameters

desktop_id

the desktop file id

 

Returns

a new GDesktopAppInfo, or NULL if no desktop file with that id


g_desktop_app_info_get_filename ()

const char *
g_desktop_app_info_get_filename (GDesktopAppInfo *info);

When info was created from a known filename, return it. In some situations such as the GDesktopAppInfo returned from g_desktop_app_info_new_from_keyfile(), this function will return NULL.

Parameters

info

a GDesktopAppInfo

 

Returns

The full path to the file for info , or NULL if not known.

Since: 2.24


g_desktop_app_info_get_is_hidden ()

gboolean
g_desktop_app_info_get_is_hidden (GDesktopAppInfo *info);

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

Parameters

info

a GDesktopAppInfo.

 

Returns

TRUE if hidden, FALSE otherwise.


g_desktop_app_info_get_nodisplay ()

gboolean
g_desktop_app_info_get_nodisplay (GDesktopAppInfo *info);

Gets the value of the NoDisplay key, which helps determine if the application info should be shown in menus. See G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().

Parameters

info

a GDesktopAppInfo

 

Returns

The value of the NoDisplay key

Since: 2.30


g_desktop_app_info_get_show_in ()

gboolean
g_desktop_app_info_get_show_in (GDesktopAppInfo *info,
                                const gchar *desktop_env);

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.

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

Note that g_app_info_should_show() for info will include this check (with NULL for desktop_env ) as well as additional checks.

Parameters

info

a GDesktopAppInfo

 

desktop_env

a string specifying a desktop name.

[nullable]

Returns

TRUE if the info should be shown in desktop_env according to the OnlyShowIn and NotShowIn keys, FALSE otherwise.

Since: 2.30


g_desktop_app_info_get_generic_name ()

const char *
g_desktop_app_info_get_generic_name (GDesktopAppInfo *info);

Gets the generic name from the destkop file.

Parameters

info

a GDesktopAppInfo

 

Returns

The value of the GenericName key


g_desktop_app_info_get_categories ()

const char *
g_desktop_app_info_get_categories (GDesktopAppInfo *info);

Gets the categories from the desktop file.

Parameters

info

a GDesktopAppInfo

 

Returns

The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it.


g_desktop_app_info_get_keywords ()

const char * const *
g_desktop_app_info_get_keywords (GDesktopAppInfo *info);

Gets the keywords from the desktop file.

Parameters

info

a GDesktopAppInfo

 

Returns

The value of the Keywords key.

[transfer none]

Since: 2.32


g_desktop_app_info_get_startup_wm_class ()

const char *
g_desktop_app_info_get_startup_wm_class
                               (GDesktopAppInfo *info);

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

Parameters

info

a GDesktopAppInfo that supports startup notify

 

Returns

the startup WM class, or NULL if none is set in the desktop file.

[transfer none]

Since: 2.34


g_desktop_app_info_set_desktop_env ()

void
g_desktop_app_info_set_desktop_env (const char *desktop_env);

g_desktop_app_info_set_desktop_env has been deprecated since version 2.42 and should not be used in newly-written code.

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 g_app_info_should_show() and g_desktop_app_info_get_show_in() to evaluate the OnlyShowIn and NotShowIn desktop entry fields.

Should be called only once; subsequent calls are ignored.

Parameters

desktop_env

a string specifying what desktop this is

 

g_desktop_app_info_get_string ()

char *
g_desktop_app_info_get_string (GDesktopAppInfo *info,
                               const char *key);

Looks up a string value in the keyfile backing info .

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

Parameters

info

a GDesktopAppInfo

 

key

the key to look up

 

Returns

a newly allocated string, or NULL if the key is not found

Since: 2.36


g_desktop_app_info_get_boolean ()

gboolean
g_desktop_app_info_get_boolean (GDesktopAppInfo *info,
                                const char *key);

Looks up a boolean value in the keyfile backing info .

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

Parameters

info

a GDesktopAppInfo

 

key

the key to look up

 

Returns

the boolean value, or FALSE if the key is not found

Since: 2.36


g_desktop_app_info_has_key ()

gboolean
g_desktop_app_info_has_key (GDesktopAppInfo *info,
                            const char *key);

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

Parameters

info

a GDesktopAppInfo

 

key

the key to look up

 

Returns

TRUE if the key exists

Since: 2.36


GDesktopAppLaunchCallback ()

void
(*GDesktopAppLaunchCallback) (GDesktopAppInfo *appinfo,
                              GPid pid,
                              gpointer user_data);

During invocation, g_desktop_app_info_launch_uris_as_manager() may create one or more child processes. This callback is invoked once for each, providing the process ID.

Parameters

appinfo

a GDesktopAppInfo

 

pid

Process identifier

 

user_data

User data

 

g_desktop_app_info_launch_uris_as_manager ()

gboolean
g_desktop_app_info_launch_uris_as_manager
                               (GDesktopAppInfo *appinfo,
                                GList *uris,
                                GAppLaunchContext *launch_context,
                                GSpawnFlags spawn_flags,
                                GSpawnChildSetupFunc user_setup,
                                gpointer user_setup_data,
                                GDesktopAppLaunchCallback pid_callback,
                                gpointer pid_callback_data,
                                GError **error);

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

If the application is launched via traditional UNIX fork()/exec() then spawn_flags , user_setup and user_setup_data are used for the call to g_spawn_async(). Additionally, pid_callback (with pid_callback_data ) will be called to inform about the PID of the created process.

If application launching occurs via some other mechanism (eg: D-Bus activation) then spawn_flags , user_setup , user_setup_data , pid_callback and pid_callback_data are ignored.

Parameters

appinfo

a GDesktopAppInfo

 

uris

List of URIs.

[element-type utf8]

launch_context

a GAppLaunchContext.

[allow-none]

spawn_flags

GSpawnFlags, used for each process

 

user_setup

a GSpawnChildSetupFunc, used once for each process.

[scope call][allow-none]

user_setup_data

User data for user_setup .

[closure user_setup][allow-none]

pid_callback

Callback for child processes.

[scope call][allow-none]

pid_callback_data

User data for callback .

[closure pid_callback][allow-none]

error

return location for a GError, or NULL

 

Returns

TRUE on successful launch, FALSE otherwise.


g_desktop_app_info_list_actions ()

const gchar * const *
g_desktop_app_info_list_actions (GDesktopAppInfo *info);

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.

Parameters

info

a GDesktopAppInfo

 

Returns

a list of strings, always non-NULL.

[array zero-terminated=1][element-type utf8][transfer none]

Since: 2.38


g_desktop_app_info_get_action_name ()

gchar *
g_desktop_app_info_get_action_name (GDesktopAppInfo *info,
                                    const gchar *action_name);

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

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

Parameters

info

a GDesktopAppInfo

 

action_name

the name of the action as from g_desktop_app_info_list_actions()

 

Returns

the locale-specific action name.

[transfer full]

Since: 2.38


g_desktop_app_info_launch_action ()

void
g_desktop_app_info_launch_action (GDesktopAppInfo *info,
                                  const gchar *action_name,
                                  GAppLaunchContext *launch_context);

Activates the named application action.

You may only call this function on action names that were returned from g_desktop_app_info_list_actions().

Note that if the main entry of the desktop file indicates that the application supports startup notification, and launch_context is non-NULL, 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 g_app_info_launch() there is no way to detect failures that occur while using this function.

Parameters

info

a GDesktopAppInfo

 

action_name

the name of the action as from g_desktop_app_info_list_actions()

 

launch_context

a GAppLaunchContext.

[allow-none]

Since: 2.38


g_desktop_app_info_search ()

gchar ***
g_desktop_app_info_search (const gchar *search_string);

Searches desktop files for ones that match search_string .

The return value is an array of strvs. Each strv contains a list of applications that matched search_string 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.

Parameters

search_string

the search string to use

 

Returns

a list of strvs. Free each item with g_strfreev() and free the outer list with g_free().

[array zero-terminated=1][element-type GStrv][transfer full]


g_desktop_app_info_get_implementations ()

GList *
g_desktop_app_info_get_implementations
                               (const gchar *interface);

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.

Parameters

interface

the name of the interface

 

Returns

a list of GDesktopAppInfo objects.

[element-type GDesktopAppInfo][transfer full]

Since: 2.42

Types and Values

GDesktopAppInfo

typedef struct _GDesktopAppInfo GDesktopAppInfo;

Information about an installed application from a desktop file.


GDesktopAppInfoLookup

typedef struct _GDesktopAppInfoLookup GDesktopAppInfoLookup;

GDesktopAppInfoLookup is deprecated and should not be used in newly-written code.

GDesktopAppInfoLookup is an opaque data structure and can only be accessed using the following functions.


struct GDesktopAppInfoLookupIface

struct GDesktopAppInfoLookupIface {
  GTypeInterface g_iface;

  GAppInfo * (* get_default_for_uri_scheme) (GDesktopAppInfoLookup *lookup,
                                             const char            *uri_scheme);
};

GDesktopAppInfoLookupIface is deprecated and should not be used in newly-written code.

Interface that is used by backends to associate default handlers with URI schemes.

Members

get_default_for_uri_scheme ()

Virtual method for g_desktop_app_info_lookup_get_default_for_uri_scheme().

 

G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME

#define G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME "gio-desktop-app-info-lookup"

G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME is deprecated and should not be used in newly-written code.

Extension point for default handler to URI association. See Extending GIO.

Property Details

The “filename” property

  “filename”                 gchar *

The origin filename of this GDesktopAppInfo

Flags: Read / Write / Construct Only

Default value: NULL