## ShellApp

ShellApp — Object representing an application

## Synopsis

    struct              ShellAppClass;
    enum                ShellAppState;
    void                shell_app_activate                  (ShellApp *app);
    void                shell_app_activate_full             (ShellApp *app,
                                                             int workspace,
                                                             guint32 timestamp);
    void                shell_app_activate_window           (ShellApp *app,
                                                             MetaWindow *window,
                                                             guint32 timestamp);
    int                 shell_app_compare                   (ShellApp *app,
                                                             ShellApp *other);
    int                 shell_app_compare_by_name           (ShellApp *app,
                                                             ShellApp *other);
    ClutterActor *      shell_app_create_icon_texture       (ShellApp *app,
                                                             int size);
    GDesktopAppInfo *   shell_app_get_app_info              (ShellApp *app);
    const char *        shell_app_get_description           (ShellApp *app);
    ClutterActor *      shell_app_get_faded_icon            (ShellApp *app,
                                                             int size);
    const char *        shell_app_get_id                    (ShellApp *app);
    guint               shell_app_get_n_windows             (ShellApp *app);
    const char *        shell_app_get_name                  (ShellApp *app);
    GSList *            shell_app_get_pids                  (ShellApp *app);
    ShellAppState       shell_app_get_state                 (ShellApp *app);
    GMenuTreeEntry *    shell_app_get_tree_entry            (ShellApp *app);
    GSList *            shell_app_get_windows               (ShellApp *app);
    gboolean            shell_app_is_on_workspace           (ShellApp *app,
                                                             MetaWorkspace *workspace);
    gboolean            shell_app_is_window_backed          (ShellApp *app);
    gboolean            shell_app_launch                    (ShellApp *app,
                                                             guint timestamp,
                                                             GList *uris,
                                                             int workspace,
                                                             char **startup_id,
                                                             GError **error);
    void                shell_app_open_new_window           (ShellApp *app,
                                                             int workspace);
    gboolean            shell_app_request_quit              (ShellApp *app);

## Object Hierarchy

      GEnum
       +----ShellAppState

## Description

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

## Details

### struct ShellAppClass

    struct ShellAppClass {
      GObjectClass parent_class;
    };

### enum ShellAppState

    typedef enum {
      SHELL_APP_STATE_STOPPED,
      SHELL_APP_STATE_STARTING,
      SHELL_APP_STATE_RUNNING
    } ShellAppState;

### shell_app_activate ()

    void                shell_app_activate                  (ShellApp *app);

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

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

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

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

`app` : | a ShellApp
`window` : | Window to be focused. [allow-none]
`timestamp` : | Event timestamp

### 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 visible 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.

`other` : | A ShellApp

### shell_app_compare_by_name ()

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

Order two applications by name.

`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_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_app_info ()

    GDesktopAppInfo *   shell_app_get_app_info              (ShellApp *app);

`app` : | a ShellApp
Returns : | The GDesktopAppInfo for this app, or `NULL` if backed by a window. [transfer none]

### shell_app_get_description ()

    const char *        shell_app_get_description           (ShellApp *app);

### shell_app_get_faded_icon ()

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

Return an actor with a horizontally faded look.

`app` : | A ShellApp
`size` : | Size in pixels
Returns : | A floating ClutterActor, or `NULL` if no icon. [transfer none]

### shell_app_get_id ()

    const char *        shell_app_get_id                    (ShellApp *app);

### shell_app_get_n_windows ()

    guint               shell_app_get_n_windows             (ShellApp *app);

### shell_app_get_name ()

    const char *        shell_app_get_name                  (ShellApp *app);

### shell_app_get_pids ()

    GSList *            shell_app_get_pids                  (ShellApp *app);

`app` : | a ShellApp
Returns : | An unordered list of process identifers associated with this application. [transfer container][element-type int]

### shell_app_get_state ()

    ShellAppState       shell_app_get_state                 (ShellApp *app);

`app` : | a ShellApp
Returns : | State of the application

### shell_app_get_tree_entry ()

    GMenuTreeEntry *    shell_app_get_tree_entry            (ShellApp *app);

`app` : | a ShellApp
Returns : | The GMenuTreeEntry for this app, or `NULL` if backed by a window. [transfer none]

### shell_app_get_windows ()

    GSList *            shell_app_get_windows               (ShellApp *app);

Get the toplevel, interesting 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_is_on_workspace ()

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

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

    gboolean            shell_app_launch                    (ShellApp *app,
                                                             guint timestamp,
                                                             GList *uris,
                                                             int workspace,
                                                             char **startup_id,
                                                             GError **error);

`timestamp` : | Event timestamp, or 0 for current event timestamp
`uris` : | List of uris to pass to application. [element-type utf8]
`workspace` : | Start on this workspace, or -1 for default
`startup_id` : | Returned startup notification ID, or `NULL` if none. [out]
`error` : | A GError

### shell_app_open_new_window ()

    void                shell_app_open_new_window           (ShellApp *app,
                                                             int workspace);

Request that the application create a new window.

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

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

`app` : | A ShellApp
Returns : | `TRUE` if a quit request is supported for this application