CinnamonGlobal: Cinnamon Reference Manual

## CinnamonGlobal CinnamonGlobal |

## Functions

CinnamonGlobal * | cinnamon_global_get ()
ClutterStage * | cinnamon_global_get_stage ()
MetaScreen * | cinnamon_global_get_screen ()
GdkScreen * | cinnamon_global_get_gdk_screen ()
MetaDisplay * | cinnamon_global_get_display ()
GList * | cinnamon_global_get_window_actors ()
GSettings * | cinnamon_global_get_settings ()
guint32 | cinnamon_global_get_current_time ()
pid_t | cinnamon_global_get_pid ()
gchar * | cinnamon_global_get_md5_for_string ()
gint64 | cinnamon_global_get_last_gc_end_time ()
void | cinnamon_global_dump_gjs_stack ()
gboolean | cinnamon_global_begin_modal ()
void | cinnamon_global_end_modal ()
void | cinnamon_global_set_stage_input_mode ()
void | cinnamon_global_set_stage_input_region ()
void | cinnamon_global_set_cursor ()
void | cinnamon_global_unset_cursor ()
guint32 | cinnamon_global_create_pointer_barrier ()
void | cinnamon_global_destroy_pointer_barrier ()
void | cinnamon_global_get_pointer ()
void | cinnamon_global_set_pointer ()
void | cinnamon_global_get_memory_info ()
void | cinnamon_global_begin_work ()
void | cinnamon_global_end_work ()
void | (*CinnamonLeisureFunction) ()
void | cinnamon_global_run_at_leisure ()
void | cinnamon_global_sync_pointer ()
GAppLaunchContext * | cinnamon_global_create_app_launch_context ()
void | cinnamon_global_notify_error ()
void | cinnamon_global_init_xdnd ()
void | cinnamon_global_shutdown ()
void | cinnamon_global_reexec_self ()
void | cinnamon_global_segfault ()

## Properties

ClutterActor * | background-actor | Read
ClutterActor * | bottom-window-group | Read
gchar * | datadir | Read
MetaDisplay * | display | Read
StFocusManager * | focus-manager | Read
GdkScreen * | gdk-screen | Read
gchar * | imagedir | Read
ClutterActor * | overlay-group | Read
MetaScreen * | screen | Read
gint | screen-height | Read
gint | screen-width | Read
GSettings * | settings | Read
ClutterActor * | stage | Read
CinnamonStageInputMode | stage-input-mode | Read / Write
ClutterActor * | top-window-group | Read
guint | ui-scale | Read
gchar * | userdatadir | Read
ClutterActor * | window-group | Read
CinnamonWM * | window-manager | Read

## Signals

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

## Types and Values

enum | CinnamonStageInputMode
enum | CinnamonCursor

## Object Hierarchy

        GEnum
        ├── CinnamonCursor
        ╰── CinnamonStageInputMode
        GObject
        ╰── CinnamonGlobal

## Description

## Functions

### cinnamon_global_get ()

    CinnamonGlobal *
    cinnamon_global_get (void);

Gets the singleton global object that represents the desktop.

#### Returns

the singleton global object.

[transfer none]

### cinnamon_global_get_stage ()

    ClutterStage *
    cinnamon_global_get_stage (CinnamonGlobal *global);

#### Returns

The default ClutterStage.

[transfer none]

### cinnamon_global_get_screen ()

    MetaScreen *
    cinnamon_global_get_screen (CinnamonGlobal *global);

#### Returns

The default MetaScreen.

[transfer none]

### cinnamon_global_get_gdk_screen ()

    GdkScreen *
    cinnamon_global_get_gdk_screen (CinnamonGlobal *global);

#### Returns

Gdk screen object for Cinnamon.

[transfer none]

### cinnamon_global_get_display ()

    MetaDisplay *
    cinnamon_global_get_display (CinnamonGlobal *global);

#### Returns

The default MetaDisplay.

[transfer none]

### cinnamon_global_get_window_actors ()

    GList *
    cinnamon_global_get_window_actors (CinnamonGlobal *global);

Gets the list of MetaWindowActor for the plugin's screen

#### Returns

the list of windows.

[element-type Meta.WindowActor][transfer none]

### cinnamon_global_get_settings ()

    GSettings *
    cinnamon_global_get_settings (CinnamonGlobal *global);

Get the global GSettings instance.

#### Parameters

global | A CinnamonGlobal |

#### Returns

The GSettings object.

[transfer none]

### cinnamon_global_get_current_time ()

    guint32
    cinnamon_global_get_current_time (CinnamonGlobal *global);

#### Parameters

global | A CinnamonGlobal |

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

### cinnamon_global_get_pid ()

    pid_t
    cinnamon_global_get_pid (void);

#### Returns

the pid of the cinnamon process.

### cinnamon_global_get_md5_for_string ()

    gchar *
    cinnamon_global_get_md5_for_string (const gchar *string);

#### Returns

the MD5 sum for the given string

### cinnamon_global_get_last_gc_end_time ()

    gint64
    cinnamon_global_get_last_gc_end_time (CinnamonGlobal *global);

#### Parameters

global | A CinnamonGlobal |

#### Returns

The timestamp of the last js garbage collection.

### cinnamon_global_dump_gjs_stack ()

    void
    cinnamon_global_dump_gjs_stack (CinnamonGlobal *global);

Prints out the gjs stack

#### Parameters

global | A CinnamonGlobal |

### cinnamon_global_begin_modal ()

    gboolean
    cinnamon_global_begin_modal (CinnamonGlobal *global,
                                 guint32 timestamp,
                                 MetaModalOptions options);

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

Returns value: `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 Muffin is in a mode itself like moving a window or alt-Tab window selection, or because `cinnamon_global_begin_modal()` was previouly called.

#### Parameters

global | a CinnamonGlobal |

### cinnamon_global_end_modal ()

    void
    cinnamon_global_end_modal (CinnamonGlobal *global,
                               guint32 timestamp);

Undoes the effect of `cinnamon_global_begin_modal()`.

#### Parameters

global | a CinnamonGlobal |

### cinnamon_global_set_stage_input_mode ()

    void
    cinnamon_global_set_stage_input_mode (CinnamonGlobal *global,
                                          CinnamonStageInputMode mode);

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

When the input mode is `CINNAMON_STAGE_INPUT_MODE_FOCUSED`, the pointer is handled as with `CINNAMON_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 `CINNAMON_STAGE_INPUT_MODE_NORMAL`.

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

#### Parameters

global | the CinnamonGlobal |
mode | the stage input mode |

### cinnamon_global_set_stage_input_region ()

    void
    cinnamon_global_set_stage_input_region
                                   (CinnamonGlobal *global,
                                    GSList *rectangles);

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

#### Parameters

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

### cinnamon_global_set_cursor ()

    void
    cinnamon_global_set_cursor (CinnamonGlobal *global,
                                CinnamonCursor type);

Set the cursor on the stage window.

#### Parameters

global | A CinnamonGlobal |
type | the type of the cursor |

### cinnamon_global_unset_cursor ()

    void
    cinnamon_global_unset_cursor (CinnamonGlobal *global);

Unset the cursor on the stage window.

#### Parameters

global | A CinnamonGlobal |

### cinnamon_global_create_pointer_barrier ()

    guint32
    cinnamon_global_create_pointer_barrier
                                   (CinnamonGlobal *global,
                                    int x1,
                                    int y1,
                                    int x2,
                                    int y2,
                                    int directions);

If supported by X creates a pointer barrier.

#### Parameters

global | a CinnamonGlobal |
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 `cinnamon_global_destroy_pointer_barrier()`

### cinnamon_global_destroy_pointer_barrier ()

    void
    cinnamon_global_destroy_pointer_barrier
                                   (CinnamonGlobal *global,
                                    guint32 barrier);

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

#### Parameters

global | a CinnamonGlobal |
barrier | a pointer barrier |

### cinnamon_global_get_pointer ()

    void
    cinnamon_global_get_pointer (CinnamonGlobal *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.

#### Parameters

global | the CinnamonGlobal |
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]

### cinnamon_global_set_pointer ()

    void
    cinnamon_global_set_pointer (CinnamonGlobal *global,
                                 int x,
                                 int y);

Sets the pointer coordinates. This is a wrapper around `gdk_device_warp()`.

#### Parameters

global | the CinnamonGlobal |
x | the X coordinate of the pointer, in global coordinates. | [in]
y | the Y coordinate of the pointer, in global coordinates. | [in]

### cinnamon_global_get_memory_info ()

    void
    cinnamon_global_get_memory_info (CinnamonGlobal *global,
                                     CinnamonJSMemoryInfo *meminfo);

#### Parameters

global | A CinnamonGlobal |
meminfo | Output location for memory information. | [out caller-allocates]

#### Returns

a generic pointer to the GjsContext.

[transfer none]

### cinnamon_global_begin_work ()

    void
    cinnamon_global_begin_work (CinnamonGlobal *global);

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

#### Parameters

global | the CinnamonGlobal |

### cinnamon_global_end_work ()

    void
    cinnamon_global_end_work (CinnamonGlobal *global);

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

#### Parameters

global | the CinnamonGlobal |

### CinnamonLeisureFunction ()

    void
    (*CinnamonLeisureFunction) (gpointer data);

### cinnamon_global_run_at_leisure ()

    void
    cinnamon_global_run_at_leisure (CinnamonGlobal *global,
                                    CinnamonLeisureFunction func,
                                    gpointer user_data,
                                    GDestroyNotify notify);

Schedules a function to be called the next time Cinnamon 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 Cinnamon'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 CinnamonGlobal |
func | function to call at leisure |
user_data | data to pass to `func` |
notify | function to call to free `user_data` |

### cinnamon_global_sync_pointer ()

    void
    cinnamon_global_sync_pointer (CinnamonGlobal *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 CinnamonGlobal |

### cinnamon_global_create_app_launch_context ()

    GAppLaunchContext *
    cinnamon_global_create_app_launch_context
                                   (CinnamonGlobal *global);

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

#### Parameters

global | A CinnamonGlobal |

#### Returns

A new GAppLaunchContext.

[transfer full]

### cinnamon_global_notify_error ()

    void
    cinnamon_global_notify_error (CinnamonGlobal *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 CinnamonGlobal |
msg | Error message |
details | Error details |

### cinnamon_global_init_xdnd ()

    void
    cinnamon_global_init_xdnd (CinnamonGlobal *global);

Enables tracking of Xdnd events

#### Parameters

global | the CinnamonGlobal |

### cinnamon_global_shutdown ()

    void
    cinnamon_global_shutdown (void);

### cinnamon_global_reexec_self ()

    void
    cinnamon_global_reexec_self (CinnamonGlobal *global);

Restart the current process. Only intended for development purposes.

#### Parameters

global | A CinnamonGlobal |

### cinnamon_global_segfault ()

    void
    cinnamon_global_segfault (CinnamonGlobal *global);

Crashes Cinnamon by causing a segfault

#### Parameters

global | the CinnamonGlobal |

## Types and Values

### enum CinnamonStageInputMode

#### Members

CINNAMON_STAGE_INPUT_MODE_NONREACTIVE |  |
CINNAMON_STAGE_INPUT_MODE_NORMAL |  |
CINNAMON_STAGE_INPUT_MODE_FOCUSED |  |
CINNAMON_STAGE_INPUT_MODE_FULLSCREEN |  |

### enum CinnamonCursor

#### Members

CINNAMON_CURSOR_DND_IN_DRAG |  |
CINNAMON_CURSOR_DND_UNSUPPORTED_TARGET |  |
CINNAMON_CURSOR_DND_MOVE |  |
CINNAMON_CURSOR_DND_COPY |  |
CINNAMON_CURSOR_POINTING_HAND |  |

## Property Details

### The `“background-actor”` property

      “background-actor”         ClutterActor *

Actor drawing root window background.

Flags: Read

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

      “bottom-window-group”      ClutterActor *

Actor holding window actors that must appear below desklets.

Flags: Read

### The `“datadir”` property

      “datadir”                  gchar *

Directory containing cinnamon data files.

Flags: Read

Default value: NULL

### The `“display”` property

      “display”                  MetaDisplay *

Metacity display object for Cinnamon.

Flags: Read

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

      “focus-manager”            StFocusManager *

Cinnamon's StFocusManager.

Flags: Read

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

      “gdk-screen”               GdkScreen *

Gdk screen object for Cinnamon.

Flags: Read

### The `“imagedir”` property

      “imagedir”                 gchar *

Directory containing cinnamon image files.

Flags: Read

Default value: NULL

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

      “overlay-group”            ClutterActor *

Actor holding objects that appear above the desktop contents.

Flags: Read

### The `“screen”` property

      “screen”                   MetaScreen *

Metacity screen object for Cinnamon.

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 `“settings”` property

      “settings”                 GSettings *

GSettings instance for cinnamon configuration.

Flags: Read

### The `“stage”` property

      “stage”                    ClutterActor *

Stage holding the desktop scene graph.

Flags: Read

### The `“stage-input-mode”` property

      “stage-input-mode”         CinnamonStageInputMode

The stage input mode.

Flags: Read / Write

Default value: CINNAMON_STAGE_INPUT_MODE_NORMAL

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

      “top-window-group”         ClutterActor *

Actor holding popup menus and other actors which must appear on top of the panels.

Flags: Read

### The `“ui-scale”` property

      “ui-scale”                 guint

Current UI Scale.

Flags: Read

Default value: 1

### The `“userdatadir”` property

      “userdatadir”              gchar *

Directory containing cinnamon 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”           CinnamonWM *

Window management interface.

Flags: Read

## Signal Details

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

    void
    user_function (CinnamonGlobal *cinnamonglobal,
                   gchar          *arg1,
                   gchar          *arg2,
                   gpointer        user_data)

Flags: Run Last

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

    void
    user_function (CinnamonGlobal *cinnamonglobal,
                   gpointer        user_data)

Flags: Run Last

### The `“shutdown”` signal

    void
    user_function (CinnamonGlobal *cinnamonglobal,
                   gpointer        user_data)

Flags: Run Last

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

    void
    user_function (CinnamonGlobal *cinnamonglobal,
                   gpointer        user_data)

Flags: Run Last

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

    void
    user_function (CinnamonGlobal *cinnamonglobal,
                   gpointer        user_data)

Flags: Run Last

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

    void
    user_function (CinnamonGlobal *cinnamonglobal,
                   gint            arg1,
                   gint            arg2,
                   gpointer        user_data)

Flags: Run Last