shell-app: Shell Reference Manual

## shell-app shell-app — Object representing an application |

## Functions

const char * | shell_app_get_id ()
GDesktopAppInfo * | shell_app_get_app_info ()
ClutterActor * | shell_app_create_icon_texture ()
const char * | shell_app_get_name ()
const char * | shell_app_get_description ()
gboolean | shell_app_is_window_backed ()
void | shell_app_activate_window ()
void | shell_app_activate ()
void | shell_app_activate_full ()
void | shell_app_open_new_window ()
gboolean | shell_app_can_open_new_window ()
ShellAppState | shell_app_get_state ()
gboolean | shell_app_request_quit ()
guint | shell_app_get_n_windows ()
GSList * | shell_app_get_windows ()
GSList * | shell_app_get_pids ()
gboolean | shell_app_is_on_workspace ()
gboolean | shell_app_launch ()
void | shell_app_launch_action ()
int | shell_app_compare_by_name ()
int | shell_app_compare ()
void | shell_app_update_window_actions ()
void | shell_app_update_app_menu ()
gboolean | shell_app_get_busy ()

## Properties

GActionGroup * | action-group | Read
GDesktopAppInfo * | app-info | Read / Write / Construct Only
gboolean | busy | Read
gchar * | id | Read
GMenuModel * | menu | Read
ShellAppState | state | Read

## Signals

void | windows-changed | Run Last

## Types and Values

#define | SHELL_TYPE_APP
enum | ShellAppState
| ShellApp

## Object Hierarchy

        GEnum
        ╰── ShellAppState
        GObject
        ╰── ShellApp

## Description

This object wraps a GDesktopAppInfo, providing methods and signals primarily useful for running applications.

## Functions

### shell_app_get_id ()

    const char *
    shell_app_get_id (ShellApp *app);

### shell_app_get_app_info ()

    GDesktopAppInfo *
    shell_app_get_app_info (ShellApp *app);

#### Parameters

app | a ShellApp |

#### Returns

The GDesktopAppInfo for this app, or `NULL` if backed by a window.

[transfer none]

### shell_app_create_icon_texture ()

    ClutterActor *
    shell_app_create_icon_texture (ShellApp *app,
                                   int size);

Look up the icon for this application, and create a ClutterTexture for it at the given size.

#### Returns

A floating ClutterActor.

[transfer none]

### shell_app_get_name ()

    const char *
    shell_app_get_name (ShellApp *app);

### shell_app_get_description ()

    const char *
    shell_app_get_description (ShellApp *app);

### shell_app_is_window_backed ()

    gboolean
    shell_app_is_window_backed (ShellApp *app);

A window backed application is one which represents just an open window, i.e. there's no .desktop file assocation, so we don't know how to launch it again.

### shell_app_activate_window ()

    void
    shell_app_activate_window (ShellApp *app,
                               MetaWindow *window,
                               guint32 timestamp);

Bring all windows for the given app to the foreground, but ensure that `window` is on top. If `window` is `NULL`, the window with the most recent user time for the app will be used.

This function has no effect if `app` is not currently running.

#### Parameters

app | a ShellApp |
window | Window to be focused. | [nullable]
timestamp | Event timestamp |

### shell_app_activate ()

    void
    shell_app_activate (ShellApp *app);

Like `shell_app_activate_full()`, but using the default workspace and event timestamp.

#### Parameters

app | a ShellApp |

### shell_app_activate_full ()

    void
    shell_app_activate_full (ShellApp *app,
                             int workspace,
                             guint32 timestamp);

Perform an appropriate default action for operating on this application, dependent on its current state. For example, if the application is not currently running, launch it. If it is running, activate the most recently used NORMAL window (or if that window has a transient, the most recently used transient for that window).

#### Parameters

app | a ShellApp |
workspace | launch on this workspace, or -1 for default. Ignored if activating an existing window |
timestamp | Event timestamp |

### shell_app_open_new_window ()

    void
    shell_app_open_new_window (ShellApp *app,
                               int workspace);

Request that the application create a new window.

#### Parameters

app | a ShellApp |
workspace | open on this workspace, or -1 for default |

### shell_app_can_open_new_window ()

    gboolean
    shell_app_can_open_new_window (ShellApp *app);

Returns `TRUE` if the app supports opening a new window through `shell_app_open_new_window()` (ie, if calling that function will result in actually opening a new window and not something else, like presenting the most recently active one)

#### Parameters

app | a ShellApp |

### shell_app_get_state ()

    ShellAppState
    shell_app_get_state (ShellApp *app);

#### Parameters

app | a ShellApp |

#### Returns

State of the application

### shell_app_request_quit ()

    gboolean
    shell_app_request_quit (ShellApp *app);

Initiate an asynchronous request to quit this application. The application may interact with the user, and the user might cancel the quit request from the application UI.

This operation may not be supported for all applications.

#### Parameters

app | A ShellApp |

#### Returns

`TRUE` if a quit request is supported for this application

### shell_app_get_n_windows ()

    guint
    shell_app_get_n_windows (ShellApp *app);

### shell_app_get_windows ()

    GSList *
    shell_app_get_windows (ShellApp *app);

Get the windows which are associated with this application. The returned list will be sorted first by whether they're on the active workspace, then by whether they're visible, and finally by the time the user last interacted with them.

#### Returns

List of windows.

[transfer none][element-type MetaWindow]

### shell_app_get_pids ()

    GSList *
    shell_app_get_pids (ShellApp *app);

#### Parameters

app | a ShellApp |

#### Returns

An unordered list of process identifers associated with this application.

[transfer container][element-type int]

### shell_app_is_on_workspace ()

    gboolean
    shell_app_is_on_workspace (ShellApp *app,
                               MetaWorkspace *workspace);

### shell_app_launch ()

    gboolean
    shell_app_launch (ShellApp *app,
                      guint timestamp,
                      int workspace,
                      gboolean discrete_gpu,
                      GError **error);

#### Parameters

timestamp | Event timestamp, or 0 for current event timestamp |
workspace | Start on this workspace, or -1 for default |
discrete_gpu | Whether to start on the discrete GPU |
error | A GError |

### shell_app_launch_action ()

    void
    shell_app_launch_action (ShellApp *app,
                             const char *action_name,
                             guint timestamp,
                             int workspace);

#### Parameters

app | the ShellApp |
action_name | the name of the action to launch (as obtained by `g_desktop_app_info_list_actions()`) |
timestamp | Event timestamp, or 0 for current event timestamp |
workspace | Start on this workspace, or -1 for default |

### shell_app_compare_by_name ()

    int
    shell_app_compare_by_name (ShellApp *app,
                               ShellApp *other);

Order two applications by name.

#### Parameters

app | One app |
other | The other app |

#### Returns

-1, 0, or 1; suitable for use as a comparison function for e.g. `g_slist_sort()`

### shell_app_compare ()

    int
    shell_app_compare (ShellApp *app,
                       ShellApp *other);

Compare one ShellApp instance to another, in the following way:

- Running applications sort before not-running applications.

- If one of them has non-minimized windows and the other does not, the one with visible windows is first.

- Finally, the application which the user interacted with most recently compares earlier.

#### Parameters

other | A ShellApp |

### shell_app_update_window_actions ()

    void
    shell_app_update_window_actions (ShellApp *app,
                                     MetaWindow *window);

### shell_app_update_app_menu ()

    void
    shell_app_update_app_menu (ShellApp *app,
                               MetaWindow *window);

### shell_app_get_busy ()

    gboolean
    shell_app_get_busy (ShellApp *app);

## Types and Values

### SHELL_TYPE_APP

    #define SHELL_TYPE_APP (shell_app_get_type ())

### enum ShellAppState

#### Members

SHELL_APP_STATE_STOPPED |  |
SHELL_APP_STATE_STARTING |  |
SHELL_APP_STATE_RUNNING |  |

### ShellApp

    typedef struct _ShellApp ShellApp;

## Property Details

### The `“action-group”` property

      “action-group”             GActionGroup *

The GDBusActionGroup associated with this ShellApp, if any. See the documentation of GApplication and GActionGroup for details.

Flags: Read

### The `“app-info”` property

      “app-info”                 GDesktopAppInfo *

The GDesktopAppInfo associated with this ShellApp, if any.

Flags: Read / Write / Construct Only

### The `“busy”` property

      “busy”                     gboolean

Whether the application has marked itself as busy.

Flags: Read

Default value: FALSE

### The `“id”` property

      “id”                       gchar *

The id of this application (a desktop filename, or a special string like window:0xabcd1234)

Flags: Read

Default value: NULL

### The `“menu”` property

      “menu”                     GMenuModel *

The GMenuProxy associated with this ShellApp, if any. See the documentation of GMenuModel for details.

Flags: Read

### The `“state”` property

      “state”                    ShellAppState

The high-level state of the application, effectively whether it's running or not, or transitioning between those states.

Flags: Read

Default value: SHELL_APP_STATE_STOPPED

## Signal Details

### The `“windows-changed”` signal

    void
    user_function (ShellApp *shellapp,
                   gpointer  user_data)

Flags: Run Last