## ShellGlobal

ShellGlobal

## Synopsis

    enum                ShellCursor;
    struct              ShellGlobalClass;
    void                (*ShellGlobalScreenshotCallback)    (ShellGlobal *global,
                                                             gboolean success);
    void                (*ShellLeisureFunction)             (gpointer data);
                        ShellMemoryInfo;
    enum                ShellSessionType;
    enum                ShellStageInputMode;
    gboolean            shell_global_add_extension_importer (ShellGlobal *global,
                                                             const char *target_object_script,
                                                             const char *target_property,
                                                             const char *directory,
                                                             GError **error);
    gboolean            shell_global_begin_modal            (ShellGlobal *global,
                                                             guint32 timestamp,
                                                             MetaModalOptions options);
    void                shell_global_begin_work             (ShellGlobal *global);
    void                shell_global_cancel_theme_sound     (ShellGlobal *global,
                                                             guint id);
    GAppLaunchContext * shell_global_create_app_launch_context
                                                            (ShellGlobal *global);
    guint32             shell_global_create_pointer_barrier (ShellGlobal *global,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2,
                                                             int directions);
    void                shell_global_destroy_pointer_barrier
                                                            (ShellGlobal *global,
                                                             guint32 barrier);
    void                shell_global_end_modal              (ShellGlobal *global,
                                                             guint32 timestamp);
    void                shell_global_end_work               (ShellGlobal *global);
    void                shell_global_gc                     (ShellGlobal *global);
    ShellGlobal *       shell_global_get                    (void);
    guint32             shell_global_get_current_time       (ShellGlobal *global);
    MetaDisplay *       shell_global_get_display            (ShellGlobal *global);
    GdkScreen *         shell_global_get_gdk_screen         (ShellGlobal *global);
    void                shell_global_get_memory_info        (ShellGlobal *global,
                                                             ShellMemoryInfo *meminfo);
    void                shell_global_get_pointer            (ShellGlobal *global,
                                                             int *x,
                                                             int *y,
                                                             ClutterModifierType *mods);
    MetaScreen *        shell_global_get_screen             (ShellGlobal *global);
    ShellSessionType    shell_global_get_session_type       (ShellGlobal *global);
    GSettings *         shell_global_get_settings           (ShellGlobal *global);
    GList *             shell_global_get_window_actors      (ShellGlobal *global);
    void                shell_global_init_xdnd              (ShellGlobal *global);
    void                shell_global_launch_calendar_server (ShellGlobal *global);
    void                shell_global_maybe_gc               (ShellGlobal *global);
    void                shell_global_notify_error           (ShellGlobal *global,
                                                             const char *msg,
                                                             const char *details);
    void                shell_global_play_theme_sound       (ShellGlobal *global,
                                                             guint id,
                                                             const char *name);
    void                shell_global_reexec_self            (ShellGlobal *global);
    void                shell_global_run_at_leisure         (ShellGlobal *global,
                                                             ShellLeisureFunction func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);
    void                shell_global_screenshot             (ShellGlobal *global,
                                                             const char *filename,
                                                             ShellGlobalScreenshotCallback callback);
    void                shell_global_screenshot_area        (ShellGlobal *global,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height,
                                                             const char *filename,
                                                             ShellGlobalScreenshotCallback callback);
    gboolean            shell_global_screenshot_window      (ShellGlobal *global,
                                                             gboolean include_frame,
                                                             const char *filename);
    void                shell_global_set_cursor             (ShellGlobal *global,
                                                             ShellCursor type);
    void                shell_global_set_stage_input_mode   (ShellGlobal *global,
                                                             ShellStageInputMode mode);
    void                shell_global_set_stage_input_region (ShellGlobal *global,
                                                             GSList *rectangles);
    void                shell_global_sync_pointer           (ShellGlobal *global);
    void                shell_global_unset_cursor           (ShellGlobal *global);

## Object Hierarchy

      GEnum
       +----ShellCursor

      GEnum
       +----ShellSessionType

      GEnum
       +----ShellStageInputMode

## Description

## Details

### enum ShellCursor

    typedef enum {
      SHELL_CURSOR_DND_IN_DRAG,
      SHELL_CURSOR_DND_UNSUPPORTED_TARGET,
      SHELL_CURSOR_DND_MOVE,
      SHELL_CURSOR_DND_COPY,
      SHELL_CURSOR_POINTING_HAND
    } ShellCursor;

### struct ShellGlobalClass

    struct ShellGlobalClass {
      GObjectClass parent_class;
    };

### ShellGlobalScreenshotCallback ()

    void                (*ShellGlobalScreenshotCallback)    (ShellGlobal *global,
                                                             gboolean success);

### ShellLeisureFunction ()

    void                (*ShellLeisureFunction)             (gpointer data);

### ShellMemoryInfo

    typedef struct {
      guint glibc_uordblks;

      guint js_bytes;

      guint gjs_boxed;
      guint gjs_gobject;
      guint gjs_function;
      guint gjs_closure;

      /* 32 bit to avoid js conversion problems with 64 bit */
      guint  last_gc_seconds_ago;
    } ShellMemoryInfo;

### enum ShellSessionType

    typedef enum {
      SHELL_SESSION_USER,
      SHELL_SESSION_GDM
    } ShellSessionType;

### enum ShellStageInputMode

    typedef enum {
      SHELL_STAGE_INPUT_MODE_NONREACTIVE,
      SHELL_STAGE_INPUT_MODE_NORMAL,
      SHELL_STAGE_INPUT_MODE_FOCUSED,
      SHELL_STAGE_INPUT_MODE_FULLSCREEN
    } ShellStageInputMode;

### shell_global_add_extension_importer ()

    gboolean            shell_global_add_extension_importer (ShellGlobal *global,
                                                             const char *target_object_script,
                                                             const char *target_property,
                                                             const char *directory,
                                                             GError **error);

This function sets a property named `target_property` on the object resulting from the evaluation of `target_object_script` code, which acts as a GJS importer for directory `directory`.

`target_object_script` : | JavaScript code evaluating to a target object
`target_property` : | Name of property to use for importer
`directory` : | Source directory:
`error` : | A GError
Returns : | `TRUE` on success

### shell_global_begin_modal ()

    gboolean            shell_global_begin_modal            (ShellGlobal *global,
                                                             guint32 timestamp,
                                                             MetaModalOptions options);

Grabs the keyboard and mouse to the stage window. The stage will receive all keyboard and mouse events until `shell_global_end_modal()` is called. This is used to implement "modes" for the shell, such as the overview mode or the "looking glass" debug overlay, that block application and normal key shortcuts.

`global` : | a ShellGlobal
Returns : | `TRUE` if we succesfully entered the mode. `FALSE` if we couldn't enter the mode. Failure may occur because an application has the pointer or keyboard grabbed, because Mutter is in a mode itself like moving a window or alt-Tab window selection, or because `shell_global_begin_modal()` was previouly called.

### shell_global_begin_work ()

    void                shell_global_begin_work             (ShellGlobal *global);

Marks that we are currently doing work. This is used to to track whether we are busy for the purposes of `shell_global_run_at_leisure()`. A count is kept and `shell_global_end_work()` must be called exactly as many times as `shell_global_begin_work()`.

`global` : | the ShellGlobal

### shell_global_cancel_theme_sound ()

    void                shell_global_cancel_theme_sound     (ShellGlobal *global,
                                                             guint id);

Cancels a sound notification.

`global` : | the ShellGlobal
`id` : | the id previously passed to `shell_global_play_theme_sound()`

### shell_global_create_app_launch_context ()

    GAppLaunchContext * shell_global_create_app_launch_context
                                                            (ShellGlobal *global);

Create a GAppLaunchContext set up with the correct timestamp, and targeted to activate on the current workspace.

`global` : | A ShellGlobal
Returns : | A new GAppLaunchContext. [transfer full]

### shell_global_create_pointer_barrier ()

    guint32             shell_global_create_pointer_barrier (ShellGlobal *global,
                                                             int x1,
                                                             int y1,
                                                             int x2,
                                                             int y2,
                                                             int directions);

If supported by X creates a pointer barrier.

`global` : | a ShellGlobal
`x1` : | left X coordinate
`y1` : | top Y coordinate
`x2` : | right X coordinate
`y2` : | bottom Y coordinate
`directions` : | The directions we're allowed to pass through
Returns : | value you can pass to `shell_global_destroy_pointer_barrier()`

### shell_global_destroy_pointer_barrier ()

    void                shell_global_destroy_pointer_barrier
                                                            (ShellGlobal *global,
                                                             guint32 barrier);

Destroys the `barrier` created by `shell_global_create_pointer_barrier()`.

`global` : | a ShellGlobal
`barrier` : | a pointer barrier

### shell_global_end_modal ()

    void                shell_global_end_modal              (ShellGlobal *global,
                                                             guint32 timestamp);

Undoes the effect of `shell_global_begin_modal()`.

`global` : | a ShellGlobal

### shell_global_end_work ()

    void                shell_global_end_work               (ShellGlobal *global);

Marks the end of work that we started with `shell_global_begin_work()`. If no other work is ongoing and functions have been added with `shell_global_run_at_leisure()`, they will be run at the next opportunity.

`global` : | the ShellGlobal

### shell_global_gc ()

    void                shell_global_gc                     (ShellGlobal *global);

Start a garbage collection process. For more information, see https://developer.mozilla.org/En/JS_GC

`global` : | A ShellGlobal

### shell_global_get ()

    ShellGlobal *       shell_global_get                    (void);

Gets the singleton global object that represents the desktop.

Returns : | the singleton global object. [transfer none]

### shell_global_get_current_time ()

    guint32             shell_global_get_current_time       (ShellGlobal *global);

`global` : | A ShellGlobal
Returns : | the current X server time from the current Clutter, Gdk, or X event. If called from outside an event handler, this may return `Clutter`.CURRENT_TIME (aka 0), or it may return a slightly out-of-date timestamp.

### shell_global_get_display ()

    MetaDisplay *       shell_global_get_display            (ShellGlobal *global);

Returns : | The default MetaDisplay. [transfer none]

### shell_global_get_gdk_screen ()

    GdkScreen *         shell_global_get_gdk_screen         (ShellGlobal *global);

Returns : | Gdk screen object for the shell. [transfer none]

### shell_global_get_memory_info ()

    void                shell_global_get_memory_info        (ShellGlobal *global,
                                                             ShellMemoryInfo *meminfo);

Load process-global data about memory usage.

`meminfo` : | Output location for memory information. [out caller-allocates]

### shell_global_get_pointer ()

    void                shell_global_get_pointer            (ShellGlobal *global,
                                                             int *x,
                                                             int *y,
                                                             ClutterModifierType *mods);

Gets the pointer coordinates and current modifier key state. This is a wrapper around `gdk_display_get_pointer()` that strips out any un-declared modifier flags, to make gjs happy; see https://bugzilla.gnome.org/show_bug.cgi?id=597292.

`global` : | the ShellGlobal
`x` : | the X coordinate of the pointer, in global coordinates. [out]
`y` : | the Y coordinate of the pointer, in global coordinates. [out]
`mods` : | the current set of modifier keys that are pressed down. [out]

### shell_global_get_screen ()

    MetaScreen *        shell_global_get_screen             (ShellGlobal *global);

Returns : | The default MetaScreen. [transfer none]

### shell_global_get_session_type ()

    ShellSessionType    shell_global_get_session_type       (ShellGlobal *global);

Gets the type of session gnome-shell provides.

The type determines what UI elements are displayed, what keybindings work, and generally how the shell behaves.

A session type of SHELL_SESSION_USER means gnome-shell will enable the activities overview, status menu, run dialog, etc. This is the default.

A session type of SHELL_SESSION_GDM means gnome-shell will enable a login dialog and run in a more confined way. This type is suitable for the display manager.

`global` : | The ShellGlobal.
Returns : | the type of session gnome-shell is providing.

### shell_global_get_settings ()

    GSettings *         shell_global_get_settings           (ShellGlobal *global);

Get the global GSettings instance.

`global` : | A ShellGlobal
Returns : | The GSettings object. [transfer none]

### shell_global_get_window_actors ()

    GList *             shell_global_get_window_actors      (ShellGlobal *global);

Gets the list of MetaWindowActor for the plugin's screen

Returns : | the list of windows. [element-type Meta.WindowActor][transfer none]

### shell_global_init_xdnd ()

    void                shell_global_init_xdnd              (ShellGlobal *global);

Enables tracking of Xdnd events

`global` : | the ShellGlobal

### shell_global_launch_calendar_server ()

    void                shell_global_launch_calendar_server (ShellGlobal *global);

Launch the gnome-shell-calendar-server helper.

`global` : | The ShellGlobal.

### shell_global_maybe_gc ()

    void                shell_global_maybe_gc               (ShellGlobal *global);

Start a garbage collection process when it would free up enough memory to be worth the amount of time it would take https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JS_MaybeGC

`global` : | A ShellGlobal

### shell_global_notify_error ()

    void                shell_global_notify_error           (ShellGlobal *global,
                                                             const char *msg,
                                                             const char *details);

Show a system error notification. Use this function when a user-initiated action results in a non-fatal problem from causes that may not be under system control. For example, an application crash.

`global` : | a ShellGlobal
`msg` : | Error message
`details` : | Error details

### shell_global_play_theme_sound ()

    void                shell_global_play_theme_sound       (ShellGlobal *global,
                                                             guint id,
                                                             const char *name);

Plays a simple sound picked according to Freedesktop sound theme. Really just a workaround for libcanberra not being introspected.

`global` : | the ShellGlobal
`id` : | an id, used to cancel later (0 if not needed)
`name` : | the sound name

### shell_global_reexec_self ()

    void                shell_global_reexec_self            (ShellGlobal *global);

Restart the current process. Only intended for development purposes.

`global` : | A ShellGlobal

### shell_global_run_at_leisure ()

    void                shell_global_run_at_leisure         (ShellGlobal *global,
                                                             ShellLeisureFunction func,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Schedules a function to be called the next time the shell is idle. Idle means here no animations, no redrawing, and no ongoing background work. Since there is currently no way to hook into the Clutter master clock and know when is running, the implementation here is somewhat approximation. Animations done through the shell's Tweener module will be handled properly, but other animations may be detected as terminating early if they can be drawn fast enough so that the event loop goes idle between frames.

The intent of this function is for performance measurement runs where a number of actions should be run serially and each action is timed individually. Using this function for other purposes will interfere with the ability to use it for performance measurement so should be avoided.

`global` : | the ShellGlobal
`func` : | function to call at leisure
`user_data` : | data to pass to `func`
`notify` : | function to call to free `user_data`

### shell_global_screenshot ()

    void                shell_global_screenshot             (ShellGlobal *global,
                                                             const char *filename,
                                                             ShellGlobalScreenshotCallback callback);

Takes a screenshot of the whole screen in `filename` as png image.

`global` : | the ShellGlobal
`filename` : | The filename for the screenshot
`callback` : | function to call returning success or failure of the async grabbing. [scope async]

### shell_global_screenshot_area ()

    void                shell_global_screenshot_area        (ShellGlobal *global,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height,
                                                             const char *filename,
                                                             ShellGlobalScreenshotCallback callback);

Takes a screenshot of the passed in area and saves it in `filename` as png image.

`global` : | the ShellGlobal
`x` : | The X coordinate of the area
`y` : | The Y coordinate of the area
`width` : | The width of the area
`height` : | The height of the area
`filename` : | The filename for the screenshot
`callback` : | function to call returning success or failure of the async grabbing. [scope async]

### shell_global_screenshot_window ()

    gboolean            shell_global_screenshot_window      (ShellGlobal *global,
                                                             gboolean include_frame,
                                                             const char *filename);

`filename`: The filename for the screenshot

Takes a screenshot of the focused window (optionally omitting the frame) in `filename` as png image.

`global` : | the ShellGlobal
`include_frame` : | Whether to include the frame or not
Returns : | success or failure.

### shell_global_set_cursor ()

    void                shell_global_set_cursor             (ShellGlobal *global,
                                                             ShellCursor type);

Set the cursor on the stage window.

`global` : | A ShellGlobal
`type` : | the type of the cursor

### shell_global_set_stage_input_mode ()

    void                shell_global_set_stage_input_mode   (ShellGlobal *global,
                                                             ShellStageInputMode mode);

Sets the input mode of the stage; when `mode` is `SHELL_STAGE_INPUT_MODE_NONREACTIVE`, then the stage does not absorb any clicks, but just passes them through to underlying windows. When it is `SHELL_STAGE_INPUT_MODE_NORMAL`, then the stage accepts clicks in the region defined by `shell_global_set_stage_input_region()` but passes through clicks outside that region. When it is `SHELL_STAGE_INPUT_MODE_FULLSCREEN`, the stage absorbs all input.

When the input mode is `SHELL_STAGE_INPUT_MODE_FOCUSED`, the pointer is handled as with `SHELL_STAGE_INPUT_MODE_NORMAL`, but additionally the stage window has the keyboard focus. If the stage loses the focus (eg, because the user clicked into a window) the input mode will revert to `SHELL_STAGE_INPUT_MODE_NORMAL`.

Note that whenever a mutter-internal Gtk widget has a pointer grab, the shell behaves as though it was in `SHELL_STAGE_INPUT_MODE_NONREACTIVE`, to ensure that the widget gets any clicks it is expecting.

`global` : | the ShellGlobal
`mode` : | the stage input mode

### shell_global_set_stage_input_region ()

    void                shell_global_set_stage_input_region (ShellGlobal *global,
                                                             GSList *rectangles);

Sets the area of the stage that is responsive to mouse clicks when the stage mode is `SHELL_STAGE_INPUT_MODE_NORMAL` (but does not change the current stage mode).

`global` : | the ShellGlobal
`rectangles` : | a list of MetaRectangle describing the input region. [element-type Meta.Rectangle]

### shell_global_sync_pointer ()

    void                shell_global_sync_pointer           (ShellGlobal *global);

Ensures that clutter is aware of the current pointer position, causing enter and leave events to be emitted if the pointer moved behind our back (ie, during a pointer grab).

`global` : | the ShellGlobal

### shell_global_unset_cursor ()

    void                shell_global_unset_cursor           (ShellGlobal *global);

Unset the cursor on the stage window.

`global` : | A ShellGlobal