shell-global: Shell Reference Manual

## shell-global shell-global |

## Functions

ShellGlobal * | shell_global_get ()
ClutterStage * | shell_global_get_stage ()
MetaScreen * | shell_global_get_screen ()
GdkScreen * | shell_global_get_gdk_screen ()
MetaDisplay * | shell_global_get_display ()
GList * | shell_global_get_window_actors ()
GSettings * | shell_global_get_settings ()
GSettings * | shell_global_get_overrides_settings ()
guint32 | shell_global_get_current_time ()
gboolean | shell_global_begin_modal ()
void | shell_global_end_modal ()
void | shell_global_set_stage_input_region ()
void | shell_global_get_pointer ()
void | shell_global_begin_work ()
void | shell_global_end_work ()
void | (*ShellLeisureFunction) ()
void | shell_global_run_at_leisure ()
void | shell_global_sync_pointer ()
GAppLaunchContext * | shell_global_create_app_launch_context ()
void | shell_global_play_theme_sound ()
void | shell_global_play_theme_sound_full ()
void | shell_global_play_sound_file ()
void | shell_global_play_sound_file_full ()
void | shell_global_cancel_theme_sound ()
void | shell_global_notify_error ()
void | shell_global_init_xdnd ()
void | shell_global_reexec_self ()
void | shell_global_log_structured ()
const char * | shell_global_get_session_mode ()
void | shell_global_set_runtime_state ()
GVariant * | shell_global_get_runtime_state ()
void | shell_global_set_persistent_state ()
GVariant * | shell_global_get_persistent_state ()

## Properties

gchar * | datadir | Read
MetaDisplay * | display | Read
StFocusManager * | focus-manager | Read
gboolean | frame-finish-timestamp | Read / Write
gboolean | frame-timestamps | Read / Write
GdkScreen * | gdk-screen | Read
gchar * | imagedir | Read
MetaScreen * | screen | Read
gint | screen-height | Read
gint | screen-width | Read
gchar * | session-mode | Read / Write / Construct Only
GSettings * | settings | Read
ClutterActor * | stage | Read
ClutterActor * | top-window-group | Read
gchar * | userdatadir | Read
ClutterActor * | window-group | Read
ShellWM * | window-manager | Read

## Signals

void | notify-error | Run Last
void | xdnd-enter | Run Last
void | xdnd-leave | Run Last
void | xdnd-position-changed | Run Last

## Types and Values

#define | SHELL_TYPE_GLOBAL
| ShellMemoryInfo
| ShellGlobal

## Object Hierarchy

        GObject
        ╰── ShellGlobal

## Description

## Functions

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

    ClutterStage *
    shell_global_get_stage (ShellGlobal *global);

#### Returns

The default ClutterStage.

[transfer none]

### shell_global_get_screen ()

    MetaScreen *
    shell_global_get_screen (ShellGlobal *global);

#### Returns

The default MetaScreen.

[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_display ()

    MetaDisplay *
    shell_global_get_display (ShellGlobal *global);

#### Returns

The default MetaDisplay.

[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 container]

### shell_global_get_settings ()

    GSettings *
    shell_global_get_settings (ShellGlobal *global);

Get the global GSettings instance.

#### Parameters

global | A ShellGlobal |

#### Returns

The GSettings object.

[transfer none]

### shell_global_get_overrides_settings ()

    GSettings *
    shell_global_get_overrides_settings (ShellGlobal *global);

Get the session overrides GSettings instance.

#### Parameters

global | A ShellGlobal |

#### Returns

The GSettings object.

[transfer none]

### shell_global_get_current_time ()

    guint32
    shell_global_get_current_time (ShellGlobal *global);

#### Parameters

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

#### Parameters

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_end_modal ()

    void
    shell_global_end_modal (ShellGlobal *global,
                            guint32 timestamp);

Undoes the effect of `shell_global_begin_modal()`.

#### Parameters

global | a ShellGlobal |

### 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 we don't have a modal or grab.

#### Parameters

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

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

#### Parameters

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

#### Parameters

global | the 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.

#### Parameters

global | the ShellGlobal |

### ShellLeisureFunction ()

    void
    (*ShellLeisureFunction) (gpointer data);

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

#### Parameters

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

#### Parameters

global | the ShellGlobal |

### shell_global_create_app_launch_context ()

    GAppLaunchContext *
    shell_global_create_app_launch_context
                                   (ShellGlobal *global,
                                    int timestamp,
                                    int workspace);

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

#### Parameters

global | A ShellGlobal |
timestamp | the timestamp for the launch (or 0 for current time) |
workspace | a workspace index, or -1 to indicate the current one |

#### Returns

A new GAppLaunchContext.

[transfer full]

### shell_global_play_theme_sound ()

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

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

#### Parameters

global | the ShellGlobal |
id | an id, used to cancel later (0 if not needed) |
name | the sound name |
for_event | a ClutterEvent in response to which the sound is played. | [nullable]

### shell_global_play_theme_sound_full ()

    void
    shell_global_play_theme_sound_full (ShellGlobal *global,
                                        guint id,
                                        const char *name,
                                        const char *description,
                                        ClutterEvent *for_event,
                                        const char *application_id,
                                        const char *application_name);

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

#### Parameters

global | the ShellGlobal |
id | an id, used to cancel later (0 if not needed) |
name | the sound name |
description | the localized description of the event that triggered this alert |
for_event | a ClutterEvent in response to which the sound is played. | [nullable]
application_id | application on behalf of which the sound is played |

### shell_global_play_sound_file ()

    void
    shell_global_play_sound_file (ShellGlobal *global,
                                  guint id,
                                  const char *file_name,
                                  const char *description,
                                  ClutterEvent *for_event);

Like `shell_global_play_theme_sound()`, but with an explicit path instead of a themed sound.

#### Parameters

global | the ShellGlobal |
id | an id, used to cancel later (0 if not needed) |
file_name | the file name to play |
description | the localized description of the event that triggered this alert |
for_event | a ClutterEvent in response to which the sound is played. | [nullable]

### shell_global_play_sound_file_full ()

    void
    shell_global_play_sound_file_full (ShellGlobal *global,
                                       guint id,
                                       const char *file_name,
                                       const char *description,
                                       ClutterEvent *for_event,
                                       const char *application_id,
                                       const char *application_name);

Like `shell_global_play_theme_sound_full()`, but with an explicit path instead of a themed sound.

#### Parameters

global | the ShellGlobal |
id | an id, used to cancel later (0 if not needed) |
file_name | the file name to play |
description | the localized description of the event that triggered this alert |
for_event | a ClutterEvent in response to which the sound is played. | [nullable]
application_id | application on behalf of which the sound is played |

### shell_global_cancel_theme_sound ()

    void
    shell_global_cancel_theme_sound (ShellGlobal *global,
                                     guint id);

Cancels a sound notification.

#### Parameters

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

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

#### Parameters

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

### shell_global_init_xdnd ()

    void
    shell_global_init_xdnd (ShellGlobal *global);

Enables tracking of Xdnd events

#### Parameters

global | the ShellGlobal |

### shell_global_reexec_self ()

    void
    shell_global_reexec_self (ShellGlobal *global);

Restart the current process. Only intended for development purposes.

#### Parameters

global | A ShellGlobal |

### shell_global_log_structured ()

    void
    shell_global_log_structured (const char *message,
                                 const char *const *keys);

Log structured data in an operating-system specific fashion. The parameter `opts` should be an array of UTF-8 KEY=VALUE strings. This function does not support binary data. See http://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html or more information about fields that can be used on a systemd system.

#### Parameters

message | A message to print |
keys | Optional structured data. | [allow-none][array zero-terminated=1][element-type utf8]

### shell_global_get_session_mode ()

    const char *
    shell_global_get_session_mode (ShellGlobal *global);

### shell_global_set_runtime_state ()

    void
    shell_global_set_runtime_state (ShellGlobal *global,
                                    const char *property_name,
                                    GVariant *variant);

Change the value of serialized runtime state.

#### Parameters

global | a ShellGlobal |
property_name | Name of the property |
variant | A GVariant, or `NULL` to unset. | [nullable]

### shell_global_get_runtime_state ()

    GVariant *
    shell_global_get_runtime_state (ShellGlobal *global,
                                    const char *property_type,
                                    const char *property_name);

The shell maintains "runtime" state which does not persist across logout or reboot.

#### Parameters

global | a ShellGlobal |
property_type | Expected data type |
property_name | Name of the property |

#### Returns

The value of a serialized property, or `NULL` if none stored.

[transfer floating]

### shell_global_set_persistent_state ()

    void
    shell_global_set_persistent_state (ShellGlobal *global,
                                       const char *property_name,
                                       GVariant *variant);

Change the value of serialized persistent state.

#### Parameters

global | a ShellGlobal |
property_name | Name of the property |
variant | A GVariant, or `NULL` to unset. | [nullable]

### shell_global_get_persistent_state ()

    GVariant *
    shell_global_get_persistent_state (ShellGlobal *global,
                                       const char *property_type,
                                       const char *property_name);

The shell maintains "persistent" state which will persist after logout or reboot.

#### Parameters

global | a ShellGlobal |
property_type | Expected data type |
property_name | Name of the property |

#### Returns

The value of a serialized property, or `NULL` if none stored.

[transfer none]

## Types and Values

### SHELL_TYPE_GLOBAL

    #define SHELL_TYPE_GLOBAL              (shell_global_get_type ())

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

### ShellGlobal

    typedef struct _ShellGlobal ShellGlobal;

## Property Details

### The `“datadir”` property

      “datadir”                  gchar *

Directory containing gnome-shell data files.

Flags: Read

Default value: NULL

### The `“display”` property

      “display”                  MetaDisplay *

Metacity display object for the shell.

Flags: Read

### The `“focus-manager”` property

      “focus-manager”            StFocusManager *

The shell's StFocusManager.

Flags: Read

### The `“frame-finish-timestamp”` property

      “frame-finish-timestamp”   gboolean

Whether at the end of a frame to call glFinish and log paintCompletedTimestamp.

Flags: Read / Write

Default value: FALSE

### The `“frame-timestamps”` property

      “frame-timestamps”         gboolean

Whether to log frame timestamps in the performance log.

Flags: Read / Write

Default value: FALSE

### The `“gdk-screen”` property

      “gdk-screen”               GdkScreen *

Gdk screen object for the shell.

Flags: Read

### The `“imagedir”` property

      “imagedir”                 gchar *

Directory containing gnome-shell image files.

Flags: Read

Default value: NULL

### The `“screen”` property

      “screen”                   MetaScreen *

Metacity screen object for the shell.

Flags: Read

### The `“screen-height”` property

      “screen-height”            gint

Screen height, in pixels.

Flags: Read

Allowed values: >= 0

Default value: 1

### The `“screen-width”` property

      “screen-width”             gint

Screen width, in pixels.

Flags: Read

Allowed values: >= 0

Default value: 1

### The `“session-mode”` property

      “session-mode”             gchar *

The session mode to use.

Flags: Read / Write / Construct Only

Default value: "user"

### The `“settings”` property

      “settings”                 GSettings *

GSettings instance for gnome-shell configuration.

Flags: Read

### The `“stage”` property

      “stage”                    ClutterActor *

Stage holding the desktop scene graph.

Flags: Read

### The `“top-window-group”` property

      “top-window-group”         ClutterActor *

Actor holding override-redirect windows.

Flags: Read

### The `“userdatadir”` property

      “userdatadir”              gchar *

Directory containing gnome-shell user data.

Flags: Read

Default value: NULL

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

      “window-group”             ClutterActor *

Actor holding window actors.

Flags: Read

### The `“window-manager”` property

      “window-manager”           ShellWM *

Window management interface.

Flags: Read

## Signal Details

### The `“notify-error”` signal

    void
    user_function (ShellGlobal *shellglobal,
                   gchar       *arg1,
                   gchar       *arg2,
                   gpointer     user_data)

Flags: Run Last

### The `“xdnd-enter”` signal

    void
    user_function (ShellGlobal *shellglobal,
                   gpointer     user_data)

Flags: Run Last

### The `“xdnd-leave”` signal

    void
    user_function (ShellGlobal *shellglobal,
                   gpointer     user_data)

Flags: Run Last

### The `“xdnd-position-changed”` signal

    void
    user_function (ShellGlobal *shellglobal,
                   gint         arg1,
                   gint         arg2,
                   gpointer     user_data)

Flags: Run Last