ShellGlobal

ShellGlobal

Synopsis

struct              ShellGlobalClass;
ShellGlobal *       shell_global_get                    (void);
ClutterStage *      shell_global_get_stage              (ShellGlobal *global);
MetaScreen *        shell_global_get_screen             (ShellGlobal *global);
GdkScreen *         shell_global_get_gdk_screen         (ShellGlobal *global);
MetaDisplay *       shell_global_get_display            (ShellGlobal *global);
GList *             shell_global_get_window_actors      (ShellGlobal *global);
GSettings *         shell_global_get_settings           (ShellGlobal *global);
guint32             shell_global_get_current_time       (ShellGlobal *global);
gboolean            shell_global_begin_modal            (ShellGlobal *global,
                                                         guint32 timestamp,
                                                         MetaModalOptions options);
void                shell_global_end_modal              (ShellGlobal *global,
                                                         guint32 timestamp);
void                shell_global_freeze_keyboard        (ShellGlobal *global,
                                                         guint32 timestamp);
void                shell_global_set_stage_input_region (ShellGlobal *global,
                                                         GSList *rectangles);
void                shell_global_get_pointer            (ShellGlobal *global,
                                                         int *x,
                                                         int *y,
                                                         ClutterModifierType *mods);
                    ShellMemoryInfo;
void                shell_global_get_memory_info        (ShellGlobal *global,
                                                         ShellMemoryInfo *meminfo);
void                shell_global_begin_work             (ShellGlobal *global);
void                shell_global_end_work               (ShellGlobal *global);
void                (*ShellLeisureFunction)             (gpointer data);
void                shell_global_run_at_leisure         (ShellGlobal *global,
                                                         ShellLeisureFunction func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                shell_global_sync_pointer           (ShellGlobal *global);
GAppLaunchContext * shell_global_create_app_launch_context
                                                        (ShellGlobal *global);
void                shell_global_play_theme_sound       (ShellGlobal *global,
                                                         guint id,
                                                         const char *name,
                                                         const char *description,
                                                         ClutterEvent *for_event);
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);
void                shell_global_play_sound_file        (ShellGlobal *global,
                                                         guint id,
                                                         const char *file_name,
                                                         const char *description,
                                                         ClutterEvent *for_event);
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);
void                shell_global_cancel_theme_sound     (ShellGlobal *global,
                                                         guint id);
void                shell_global_notify_error           (ShellGlobal *global,
                                                         const char *msg,
                                                         const char *details);
void                shell_global_init_xdnd              (ShellGlobal *global);
void                shell_global_reexec_self            (ShellGlobal *global);
const char *        shell_global_get_session_mode       (ShellGlobal *global);
void                shell_global_set_runtime_state      (ShellGlobal *global,
                                                         const char *property_name,
                                                         GVariant *variant);
GVariant *          shell_global_get_runtime_state      (ShellGlobal *global,
                                                         const char *property_type,
                                                         const char *property_name);
                    ShellGlobal;

Object Hierarchy

  GObject
   +----ShellGlobal

Properties

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

Signals

  "notify-error"                                   : Run Last
  "xdnd-enter"                                     : Run Last
  "xdnd-leave"                                     : Run Last
  "xdnd-position-changed"                          : Run Last

Description

Details

struct ShellGlobalClass

struct ShellGlobalClass {
  GObjectClass parent_class;
};


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 none]

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

void                shell_global_end_modal              (ShellGlobal *global,
                                                         guint32 timestamp);

Undoes the effect of shell_global_begin_modal().

global :

a ShellGlobal

shell_global_freeze_keyboard ()

void                shell_global_freeze_keyboard        (ShellGlobal *global,
                                                         guint32 timestamp);


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.

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.

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]

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;


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

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.

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

global :

the ShellGlobal

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

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. [allow-none]

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.

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. [allow-none]

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.

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. [allow-none]

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.

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. [allow-none]

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.

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.

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

global :

the ShellGlobal

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

global :

a ShellGlobal

property_name :

Name of the property

variant :

A GVariant, or NULL to unset. [allow-none]

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.

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]

ShellGlobal

typedef struct _ShellGlobal ShellGlobal;

Property Details

The "datadir" property

  "datadir"                  gchar*                : Read

Directory containing gnome-shell data files.

Default value: NULL


The "display" property

  "display"                  MetaDisplay*          : Read

Metacity display object for the shell.


The "focus-manager" property

  "focus-manager"            StFocusManager*       : Read

The shell's StFocusManager.


The "gdk-screen" property

  "gdk-screen"               GdkScreen*            : Read

Gdk screen object for the shell.


The "imagedir" property

  "imagedir"                 gchar*                : Read

Directory containing gnome-shell image files.

Default value: NULL


The "screen" property

  "screen"                   MetaScreen*           : Read

Metacity screen object for the shell.


The "screen-height" property

  "screen-height"            gint                  : Read

Screen height, in pixels.

Allowed values: >= 0

Default value: 1


The "screen-width" property

  "screen-width"             gint                  : Read

Screen width, in pixels.

Allowed values: >= 0

Default value: 1


The "session-mode" property

  "session-mode"             gchar*                : Read / Write / Construct Only

The session mode to use.

Default value: "user"


The "settings" property

  "settings"                 GSettings*            : Read

GSettings instance for gnome-shell configuration.


The "stage" property

  "stage"                    ClutterActor*         : Read

Stage holding the desktop scene graph.


The "top-window-group" property

  "top-window-group"         ClutterActor*         : Read

Actor holding override-redirect windows.


The "userdatadir" property

  "userdatadir"              gchar*                : Read

Directory containing gnome-shell user data.

Default value: NULL


The "window-group" property

  "window-group"             ClutterActor*         : Read

Actor holding window actors.


The "window-manager" property

  "window-manager"           ShellWM*              : Read

Window management interface.

Signal Details

The "notify-error" signal

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

shellglobal :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "xdnd-enter" signal

void                user_function                      (ShellGlobal *shellglobal,
                                                        gpointer     user_data)        : Run Last

shellglobal :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "xdnd-leave" signal

void                user_function                      (ShellGlobal *shellglobal,
                                                        gpointer     user_data)        : Run Last

shellglobal :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "xdnd-position-changed" signal

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

shellglobal :

the object which received the signal.

user_data :

user data set when the signal handler was connected.