Main: Cinnamon Javascript Reference Manual

## Main Main — This is the heart of Cinnamon, the mother of everything. |

## Functions

| start ()
| setWorkspaceName ()
string | getWorkspaceName ()
boolean | hasDefaultWorkspaceName ()
| moveWindowToNewWorkspace ()
string | getThemeStylesheet ()
| setThemeStylesheet ()
| loadTheme ()
| notify ()
| criticalNotify ()
| warningNotify ()
| notifyError ()
| _log ()
boolean | isError ()
| _LogTraceFormatted ()
| _logTrace ()
| _logWarning ()
| _logError ()
| _logInfo ()
string | formatTime ()
string | renderLogLine ()
| logStackTrace ()
boolean | isWindowActorDisplayedOnWorkspace ()
array | getWindowActorsForWorkspace ()
boolean | pushModal ()
| popModal ()
LookingGlass.Melange | createLookingGlass ()
RunDialog.RunDialog | getRunDialog ()
| activateWindow ()
string | initializeDeferredWork ()
| queueDeferredWork ()
boolean | isInteresting ()
array | getTabList ()

## Properties

PlacesManager.PlacesManager | placesManager |
Overview.Overview | overview |
Expo.Expo | expo |
RunDialog.RunDialog | runDialog |
LookingGlass.Melange | lookingGlass |
WindowManager.WindowManager | wm |
MessageTray.MessageTray | messageTray |
IndicatorManager.IndicatorManager | indicatorManager |
NotificationDaemon.NotificationDaemon | notificationDaemon |
WindowAttentionHandler.WindowAttentionHandler | windowAttentionHandler |
Cinnamon.Recorder | recorder |
CinnamonDBus.Cinnamon | cinnamonDBusService |
int | modalCount |
array | modalActorFocusStack |
Cinnamon.GenericContainer | uiGroup |
Magnifier.Magnifier | magnifier |
XdndHandler.XdndHandler | xdndHandler |
StatusIconDispatcher.StatusIconDispatcher | statusIconDispatcher |
Keyboard.Keyboard | keyboard |
Layout.LayoutManager | layoutManager |
Panel.PanelManager | panelManager |
ThemeManager.ThemeManager | themeManager |
SoundManager.SoundManager | soundManager |
Settings.SettingsManager | settingsManager |
BackgroundManager.BackgroundManager | backgroundManager |
SlideshowManager.SlideshowManager | slideshowManager |
KeybindingManager.KeybindingManager | keybindingManager |
Systray.SystrayManager | systrayManager |
OsdWindow.OsdWindow | osdWindow |
Cinnamon.WindowTracker | tracker |
array | workspace_names |
DeskletManager.DeskletContainer | deskletContainer |
boolean | software_rendering |
Gio.FileOutputStream | lg_log_file |
boolean | can_log |
Clutter.Actor | popup_rendering_actor |
boolean | xlet_startup_error |

## Description

The main file is responsible for launching Cinnamon as well as creating its components. The C part of cinnamon calls the `start`() function, which then initializes all of cinnamon. Most components of Cinnamon can be accessed through main.

## Functions

### start ()

    start ();

Starts cinnamon. Should not be called in JavaScript code

### setWorkspaceName ()

    setWorkspaceName (int      index,
                      string   name);

Sets the name of the workspace `index` to `name`

#### Parameters

index | index of workspace |
name | name of workspace |

### getWorkspaceName ()

    string
    getWorkspaceName (int   index);

Retrieves the name of the workspace `index`

#### Parameters

index | index of workspace |

#### Returns

name of workspace

### hasDefaultWorkspaceName ()

    boolean
    hasDefaultWorkspaceName (int   index);

Whether the workspace uses the default name

#### Parameters

index | index of workspace |

#### Returns

whether the workspace uses the default name

### moveWindowToNewWorkspace ()

    moveWindowToNewWorkspace (Meta.Window   metaWindow,
                              boolean       switchToNewWorkspace);

Moves the window to a new workspace.

If `switchToNewWorkspace` is true, it will switch to the new workspace after moving the window

#### Parameters

metaWindow | the window to be moved |
switchToNewWorkspace | whether or not to switch to the new created workspace |

### getThemeStylesheet ()

    string
    getThemeStylesheet ();

Get the theme CSS file that Cinnamon will load

#### Returns

A file path that contains the theme CSS, null if using the default

### setThemeStylesheet ()

    setThemeStylesheet (string   cssStylesheet);

Set the theme CSS file that Cinnamon will load

#### Parameters

cssStylesheet | A file path that contains the theme CSS, set it to null to use the default |

### loadTheme ()

    loadTheme ();

Reloads the theme CSS file

### notify ()

    notify (string   msg,
            string   details);

Sends a notification

#### Parameters

msg | A message |
details | Additional information to be |

### criticalNotify ()

    criticalNotify (msg,
                    details);

#### Parameters

msg | A critical message |
details | Additional information |

### warningNotify ()

    warningNotify (msg,
                   details);

#### Parameters

msg | A warning message |
details | Additional information |

### notifyError ()

    notifyError (string   msg,
                 string   details);

See cinnamon_global_notify_problem().

#### Parameters

msg | An error message |
details | Additional information |

### _log ()

    _log (string   category,
          string   msg);

Log a message into the LookingGlass error stream. This is primarily intended for use by the extension system as well as debugging.

#### Parameters

category | string message type ('info', 'error') |
msg | A message string ``...: Any further arguments are converted into JSON notation, and appended to the log message, separated by spaces. |

### isError ()

    boolean
    isError (Object   obj);

Tests whether `obj` is an error object

#### Parameters

obj | the object to be tested |

#### Returns

whether `obj` is an error object

### _LogTraceFormatted ()

    _LogTraceFormatted (string   stack);

Prints the stack trace to the LookingGlass error stream in a predefined format

#### Parameters

stack | the stack trace |

### _logTrace ()

    _logTrace (Error   msg);

Prints a stack trace of the given object.

If msg is an error, its stack-trace will be printed. Otherwise, a stack-trace of the call will be generated

If you want to print the message of an Error as well, use the other log functions instead.

#### Parameters

msg | An error object |

### _logWarning ()

    _logWarning (Error/string   msg);

Logs the message to the LookingGlass error stream.

If msg is an error, its stack-trace will be printed.

#### Parameters

msg | An error object or the message string |

### _logError ()

    _logError (string   msg,
               Error    error);

Logs the following (if present) to the LookingGlass error stream:

- The message from the error object

- The stack trace of the error object

- The message `msg`

It can be called in the form of either _logError(msg), _logError(error) or _logError(msg, error).

#### Parameters

msg | (optional) The message string |
error | (optional) The error object |

### _logInfo ()

    _logInfo (Error/string   msg);

Logs the message to the LookingGlass error stream. If `msg` is an Error object, its stack trace will also be printed

#### Parameters

msg | The error object or the message string |

### formatTime ()

    string
    formatTime (Date   d);

Formats a date object into a ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ) in UTC+0

#### Parameters

d | date object to be formatted |

#### Returns

a formatted string showing the date

### renderLogLine ()

    string
    renderLogLine (dictionary   line);

Converts a log line object into a string

#### Parameters

line | a log line |

#### Returns

line in the format CATEGORY t=TIME MESSAGE

### logStackTrace ()

    logStackTrace (string   msg);

Logs the message `msg` to stdout with backtrace

#### Parameters

msg | message |

### isWindowActorDisplayedOnWorkspace ()

    boolean
    isWindowActorDisplayedOnWorkspace (Meta.WindowActor   win,
                                       int                workspaceIndex);

Determines whether the window actor belongs to a specific workspace

#### Parameters

win | window actor |
workspaceIndex | index of workspace |

#### Returns

whether the window is on the workspace

### getWindowActorsForWorkspace ()

    array
    getWindowActorsForWorkspace (int   workspaceIndex);

Gets a list of actors on a workspace

#### Parameters

workspaceIndex | index of workspace |

#### Returns

the array of window actors

### pushModal ()

    boolean
    pushModal (Clutter.Actor       actor,
               int                 timestamp,
               Meta.ModalOptions   options);

Ensure we are in a mode where all keyboard and mouse input goes to the stage, and focus `actor`. Multiple calls to this function act in a stacking fashion; the effect will be undone when an equal number of popModal() invocations have been made.

Next, record the current Clutter keyboard focus on a stack. If the modal stack returns to this actor, reset the focus to the actor which was focused at the time pushModal() was invoked.

`timestamp` is optionally used to associate the call with a specific user initiated event. If not provided then the value of global.get_current_time() is assumed.

#### Parameters

actor | actor which will be given keyboard focus |
timestamp | optional timestamp |
options | (optional) flags to indicate that the pointer is alrady grabbed |

#### Returns

true iff we successfully acquired a grab or already had one

### popModal ()

    popModal (Clutter.Actor   actor,
              int             timestamp);

Reverse the effect of pushModal(). If this invocation is undoing the topmost invocation, then the focus will be restored to the previous focus at the time when pushModal() was invoked.

`timestamp` is optionally used to associate the call with a specific user initiated event. If not provided then the value of global.get_current_time() is assumed.

#### Parameters

actor | actor passed to original invocation of pushModal(). |
timestamp | optional timestamp |

### createLookingGlass ()

    LookingGlass.Melange
    createLookingGlass ();

Obtains the looking glass object. Create if it does not exist

#### Returns

looking glass object

### getRunDialog ()

    RunDialog.RunDialog
    getRunDialog ();

Obtains the run dialog object. Create if it does not exist

#### Returns

run dialog object

### activateWindow ()

    activateWindow (Meta.Window   window,
                    int           time,
                    int           workspaceNum);

Activates `window`, switching to its workspace first if necessary, and switching out of the overview if it's currently active

#### Parameters

window | the Meta.Window to activate |
time | (optional) current event time |
workspaceNum | (optional) window's workspace number |

### initializeDeferredWork ()

    string
    initializeDeferredWork (Clutter.Actor   actor,
                            function        callback);

This function sets up a callback to be invoked when either the given actor is mapped, or after some period of time when the machine is idle. This is useful if your actor isn't always visible on the screen (for example, all actors in the overview), and you don't want to consume resources updating if the actor isn't actually going to be displaying to the user.

Note that queueDeferredWork is called by default immediately on initialization as well, under the assumption that new actors will need it.

#### Parameters

actor | A `ClutterActor` |
callback | Function to invoke to perform work |

#### Returns

A string work identifer

### queueDeferredWork ()

    queueDeferredWork (string   workId);

Ensure that the work identified by `workId` will be run on map or timeout. You should call this function for example when data being displayed by the actor has changed.

#### Parameters

workId | work identifier |

### isInteresting ()

    boolean
    isInteresting (Meta.Window   metaWindow);

Determines whether a window is "interesting", i.e. ones to be displayed in alt-tab, window list etc.

#### Parameters

metaWindow | the window to be tested |

#### Returns

whether the window is interesting

### getTabList ()

    array
    getTabList (Meta.Workspace   workspaceOpt,
                Meta.Screen      screenOpt);

Return a list of the interesting windows on a workspace (by default, the active workspace). The list will include app-less dialogs.

#### Parameters

workspaceOpt | (optional) workspace, defaults to global.screen.get_active_workspace() |
screenOpt | (optional) screen, defaults to global.screen |

#### Returns

list of windows

## Property Details

### The `“placesManager”` property

      “placesManager”        PlacesManager.PlacesManager

The places manager

### The `“overview”` property

      “overview”             Overview.Overview

The "scale" overview

### The `“expo”` property

      “expo”                 Expo.Expo

The "expo" overview

### The `“runDialog”` property

      “runDialog”            RunDialog.RunDialog

The run dialog

### The `“lookingGlass”` property

      “lookingGlass”         LookingGlass.Melange

The looking glass object

### The `“wm”` property

      “wm”                   WindowManager.WindowManager

The window manager

### The `“messageTray”` property

      “messageTray”          MessageTray.MessageTray

The mesesage tray

### The `“indicatorManager”` property

      “indicatorManager”     IndicatorManager.IndicatorManager

The indicator manager

### The `“notificationDaemon”` property

      “notificationDaemon”   NotificationDaemon.NotificationDaemon

The notification daemon

### The `“windowAttentionHandler”` property

      “windowAttentionHandler”  WindowAttentionHandler.WindowAttentionHandler

The window attention handler

### The `“recorder”` property

      “recorder”             Cinnamon.Recorder

The recorder

### The `“cinnamonDBusService”` property

      “cinnamonDBusService”  CinnamonDBus.Cinnamon

The cinnamon dbus object

### The `“modalCount”` property

      “modalCount”           int

The number of modals "pushed"

### The `“modalActorFocusStack”` property

      “modalActorFocusStack”  array

Array of pushed modal actors

### The `“uiGroup”` property

      “uiGroup”              Cinnamon.GenericContainer

The group containing all Cinnamon and Muffin actors

### The `“magnifier”` property

      “magnifier”            Magnifier.Magnifier

The magnifier

### The `“xdndHandler”` property

      “xdndHandler”          XdndHandler.XdndHandler

The X DND handler

### The `“statusIconDispatcher”` property

      “statusIconDispatcher”  StatusIconDispatcher.StatusIconDispatcher

The status icon dispatcher

### The `“keyboard”` property

      “keyboard”             Keyboard.Keyboard

The keyboard object

### The `“layoutManager”` property

      “layoutManager”        Layout.LayoutManager

The layout manager.

All actors that are part of the Cinnamon UI ar handled by the layout manager, which will determine when to show and hide the actors etc.

### The `“panelManager”` property

      “panelManager”         Panel.PanelManager

The panel manager.

This is responsible for handling events relating to panels, eg. showing all panels.

### The `“themeManager”` property

      “themeManager”         ThemeManager.ThemeManager

The theme manager

### The `“soundManager”` property

      “soundManager”         SoundManager.SoundManager

The sound manager

### The `“settingsManager”` property

      “settingsManager”      Settings.SettingsManager

The manager of the xlet Settings API

### The `“backgroundManager”` property

      “backgroundManager”    BackgroundManager.BackgroundManager

The background manager.

This listens to changes in the GNOME background settings and mirrors them to the Cinnamon settings, since many applications have a "Set background" button that modifies the GNOME background settings.

### The `“slideshowManager”` property

      “slideshowManager”     SlideshowManager.SlideshowManager

The slideshow manager.

This is responsible for managing the background slideshow, since the background "slideshow" is created by cinnamon changing the active background gsetting every x minutes.

### The `“keybindingManager”` property

      “keybindingManager”    KeybindingManager.KeybindingManager

The keybinding manager

### The `“systrayManager”` property

      “systrayManager”       Systray.SystrayManager

The systray manager

### The `“osdWindow”` property

      “osdWindow”            OsdWindow.OsdWindow

Osd window that pops up when you use media keys.

### The `“tracker”` property

      “tracker”              Cinnamon.WindowTracker

The window tracker

### The `“workspace_names”` property

      “workspace_names”      array

Names of workspace

### The `“deskletContainer”` property

      “deskletContainer”     DeskletManager.DeskletContainer

The desklet container.

This is a container that contains all the desklets as childs. Its actor is put between `global`.bottom_window_group and `global`.uiGroup.

### The `“software_rendering”` property

      “software_rendering”   boolean

Whether software rendering is used

### The `“lg_log_file”` property

      “lg_log_file”          Gio.FileOutputStream

The stream used to log looking messages to ~/.cinnamon/glass.log

### The `“can_log”` property

      “can_log”              boolean

Whether looking glass log to file can be used

### The `“popup_rendering_actor”` property

      “popup_rendering_actor”  Clutter.Actor

The popup actor that is in the process of rendering

### The `“xlet_startup_error”` property

      “xlet_startup_error”   boolean

Whether there was at least one xlet that did not manage to load