Skip to content

Latest commit

 

History

History
891 lines (737 loc) · 48.4 KB

REFERENCE.md

File metadata and controls

891 lines (737 loc) · 48.4 KB
Raw

GNOME Shell Javascript Source Reference


Documentation for the Javascript files that make up GNOME Shell's Javascript side
Notes
  • The actual version of GNOME Shell as of today is 3.22
  • This is just a reference list, not full documentation or anything.
  • Use this to get a quick idea of what is in what file.
  • I might not be correct
  • Contributions are welcome
Links

Files imports.ui

Files imports.misc

Overview of classes in each file

accessDialog.js

  • AccessDialog:
  • AccessDialogDBus:

altTab.js

altTab.js

  • AppSwitcherPopup:
  • CyclerHighlight:
  • CyclerPopup:
  • GroupCyclerPopup:
  • WindowSwitcherPopup:
  • WindowCyclerPopup:
  • AppIcon: Class defining the icon for an app
  • AppSwitcher: This handles the display of icons for each app in the AltTab popup. Generates an AppIcon per app
  • ThumbnailList: This is what appears when you hover over an app with multiple windows in the AltTab popup. It handles the list of thumbnails for a given app
  • WindowIcon:
  • WindowList:

animation.js

  • Animation:
  • AnimatedIcon: Generate a animated icon (this is used for the "waves" when you reach the hot corner of the panel)

appDisplay.js

appDisplay.js

  • BaseAppView:
  • PageIndicatorsActor:
  • PageIndicators:
  • AllView:
  • FrequentView:
  • ViewStackLayout:
  • AppDisplay:
  • AppSearchProvider: Handles finding apps matching search item(s)
  • FolderView:
  • FolderIcon:
  • AppFolderPopup:
  • AppIcon: An icon for an app
  • AppIconMenu: The right-click menu of an App containing the relevant actions New Window/Remove from favourites/Add to favourites/etc

appFavorites.js

  • AppFavorites: Handles your list of app favourites - updates the list when you choose Add to Favourite, provides API for you to add/remove from your favourites

audioDeviceSelection.js

  • AudioDeviceSelectionDialog:
  • AudioDeviceSelectionDBus:

background.js

  • BackgroundCache:
  • Background:
  • SystemBackground:
  • BackgroundSource:
  • Animation:
  • BackgroundManager:

backgroundMenu.js

  • BackgroundMenu:

boxpointer.js

BoxPointer.js

BoxPointer is the triangle bit

  • BoxPointer: The triangle arrow connecting a [popupMenu](#popupmenujs) to its source (you can configure what side of the menu the pointer appears).

calendar.js

Calendar.js

  • Contains several functions for manipulating date formats, day abbreviations, etc
  • CalendarEvent: An event in the calendar
  • EmptyEventSource: Interface for appointments/events
  • DBusEventSource: A calendar event on the DBus
  • Calendar: Main Calendar class, handles the UI part of the calendar month navigation/date/graphical calendar as well as monitoring events
  • EventMessage:
  • NotificationMessage:
  • EventsSection:
  • NotificationSection:
  • Placeholder:
  • CalendarMessageList: Notification section

See also dateMenu.js which ties all these elements together

checkBox.js

checkBox.js

  • CheckBox: Checkbox itself

ctrlAltTab.js

ctrlAltTab.js

  • CtrlAltTabManager: Handles CTRL + ALT + Tab behaviour - showing the popup, setting up the stage to be ready for keyboard navigation
  • CtrlAltTabPopup: The UI popup itself
  • CtrlAltTabSwitcher: UI element holding all the options you ALT + Tab between

dash.js

dash.js

  • DashItemContainer: Helper class - each item in the dash is one of these
  • ShowAppsIcon:
  • DragPlaceholderItem:
  • EmptyDropTargetItem:
  • DashActor:
  • Dash: The master Dash class, making use of all the other classes

dateMenu.js

dash.js

The date menu. Red: DateMenuButton, Green: TodayButton, Yellow: WorldClockSection

  • TodayButton:
  • WorldClocksSection:
  • MessagesIndicator:
  • IndicatorPad:
  • FreezableBinLayout:
  • DateMenuButton: Subclass of PanelMenu.Button to provide the date menu in the middle Top Panel.

See also calendar.js

dnd.js

This allow you to add drag-and-drop functionality to your own classes. You use the following functions defined in the file:

  • addDragMonitor: You define an object defining the drag behaviour you want, and use addDragMonitor to add it. A drag monitor is an object with the key dragMonitor whick is a callback for what happens when a drag monitor event occurs See dash.js and workspacesView.js for examples

  • removeDragMonitor: Remove the drag behaviour that you added with addDragMonitor

  • makeDraggable: This is what makes an item draggable. You call it on an actor and get a draggable actor back out. You have to define some functions in actor._delegate's class in order for this to work: handleDragOver, acceptDrop, getDragActor, getDragActorSource

  • _Draggable: Class defining a basic draggable item, defining how the dragging happens. You do not use this directly, Instead, use makeDraggable to make an actor draggable

edgeDragAction.js

  • EdgeDragAction:

endSessionDialog.js

endSessionDialog.js endSessionDialog.js

  • EndSessionDialog: The end session dialog. Handles the UI part. In terms of actually logging out/shutting down/etc the dialog simply sends a message to the GNOME SessionManager DBus to request a shutdown rather thant doing the shutdown itself

environment.js

This module sets upd the GJS environment for the rest of the JS files:

  • Adds up the global object to the environment
  • Adds the add function to St.BoxLayout
  • Adds the child_set function to St.BoxLayout, Clutter.TableLayout, Clutter.GridLayout and Clutter.BoxLayout
  • Adds/Improevs the toString() function
  • Adds method String.format
  • Initialises various things the shell needs to work

extensionDownloader.js

extensionDownloader.js

This is a collection of functions to do with installing, updating and uninstalling extensions

The extension UUID is like extensionname@some.website.com

  • installExtension: Installs an extension by UUID by downloading it form GNOME Shell Extensions

  • uninstallExtension: Uninstalls an extension by UUID

  • updateExtension: Updates an extension by UUID

  • InstallExtensionDialog: The dialog that pops up when you choose to install an extension from GNOME Shell Extensions confirming that you want to install the extension

extensionSystem.js

This is a collection of functions to do with enabling and disabling extensions, and accessing their metadata

You can access extensions and their metadata using imports.misc.extensionUtils.extensions. Use imports.misc.extensionUtils.getCurrentExtension() from withing an extension to get the object for that extension

The extension UUID is like extensionname@some.website.com

  • disableExtension: Disables an extension by UUID
  • enableExtension: Enables an extension by UUID

focusCaretTracker.js

  • FocusCaretTracker:

grabHelper.js

  • GrabHelper:

ibusCandidatePopup.js

  • CandidateArea:
  • CandidatePopup:

iconGrid.js

  • BaseIcon: A basic icon class consisting of an icon and a label
  • IconGrid: A widget displaying its children in a grid allowing you to set a row limit or column limit, and actors that don't fit in will not be painted
  • PaginatedIconGrid:

keyboard.js

keyboard.js

  • Key: A key on the keyboard
  • Keyboard: The Keyboard class
  • KeyboardSource: Inherits from MessageTray.Source, shows the keyboard in the message tray
  • ShellWaylandAdapter:

layout.js

  • MonitorConstraint:
  • Monitor:
  • LayoutManager: Manages layout of items on the stage Messsage Tray/Top Panel/Hot Corners and updates when monitors change
  • HotCorner: Hot corners. The Top Left hot corner lets you switch to the overview
  • PressureBarrier:

legacyTray.js

  • LegacyTray:

lightbox.js

  • RadialShaderQuad:
  • Lightbox: A shade obscuring the specific container actor

lookingGlass.js

lookingGlass.js

Autocomplete function in the Looking Glass

lookingGlass.js

Looking Glass Inspector - outlines the actor your mouse is over and lets you pick it

lookingGlass.js

Looking Glass ObjInspector - inspecting Main.panel.statusArea.dateMenu

  • AutoComplete: Adds completion behaviour on Tab/double-Tab to the Looking Glass like the terminal
  • Notebook: The Looking Glass consists of Inspector/Evaluator/Windows/Extensions. The notebook is what holds them all
  • ObjLink: When you type thing into the Looking Glass console the results are clickable. This class handles those links
  • Result: When you type things into the Looking Glass the results get printed like so:

r(result_number) = result

  • WindowList: The Windows tab of the Looking Glass
  • ObjInspector: When you click on a result in the Looking Glass you get a window that shows you more information about that result. Clicking on an object will show some of its properties. This is that class
  • RedBorderEffect: When you pick an object with the Inspector. There is a red border around the selected object. This class handles adding and removing these borders
  • Inspector: There is a picker icon. When you select it, you can pick an object from the stage to examine further. As you move your pointer over particular objects, they get a red border drawn around them. The Inspector class handles tracking which object your pointer is over
  • Extensions: The Extensions tab in the Looking Glass
  • LookingGlass: Assembles the whole Looking Glass together. Also privedes the Evaluator tab and handles the actual evaluation of commands typed into the console

magnifierDBus.js

  • ShellMagnifier:
  • ShellMagnifierZoomRegion:

magnifier.js

magnifier.js

  • Magnifier: Defines the shell magnifier
  • ZoomRegion: Defines a particular zoom region
  • Crosshairs: Defines the crosshairs of the magnifier
  • MagShaderEffects:

main.js

This file is like the int main(); of programs, setting up the whole GNOME Shell interface and making parts available to everyone else (Top Panel/Overview/Message Tray/...). Many global objects in GNOME Shell create just one instance. These are stored here. This file also handles dynamic workspaces (when you have no windows left on a workspace it is removed).

  • Some of the objects stored to be accessed by others (there are more, see main.js):

    • panel: this is the top panel. If you want to add buttons to the status area etc, you use this panel to add them to.
    • hotCorners: the hot corner(s), e.g. the top-left one (move your cursor over it and the Overview opens).
    • overview: the Overview.
    • runDialog: the dialog when you press Alt+F2.
    • lookingGlass: the looking glass.
    • messageTray: the message tray.
    • shellDBusService: GNOME-Shell's Dbus service.
    • magnifier: the accessibility magnifier.
    • keyboard: the accessibility on-screen keyboard.

  • Some handy functions (there are other functions in main.js too; these are just some handy one):

    • getThemeStylesheet(): gets the file path for the (custom) theme you are using for GNOME Shell, if any (e.g. $HOME/.themes/<themename>/gnome-shell/gnome-shell.css). If you are not using a custom gnome-shell theme, this will be null.
    • setThemeStylesheet(path): sets the file path for the custom theme for GNOME Shell (but doesn't actually cause a theme change; use loadTheme to reload the theme after doing this).
    • loadTheme(): reloads the style for GNOME Shell. It sets the getThemeStylesheet (any custom GNOME Shell theme if you have one, or just the default /usr/share/gnome-shell/themes/gnome-shell.css) as the top priority style sheet, and then loads all the extra stylesheets (e.g. extension stylesheets) at a lower priority. This is why if you set a style in your extension's stylesheet.css that conflicts with the a GNOME Shell style class, GNOME Shell will win.
    • notify(msg, details): creates a GNOME Shell notification (i.e. popup from the message tray) with title msg and text details.
    • notifyError(msg, details): calls notify(msg, details) to send a popup notification from the message tray
    • pushModal(actor, timestamp, options): Grabs all keyboard/mouse input to the stage and focuses actor. When the modal stack is empty we return focus to whatever had focus before pushModal was called. The Overview, Run Dialog, Looking Glass, and Modal Dialogs all use this (there are probably more too).
    • popModal(actor, timestamp): Opposite of pushModal (removes actor from the modal stack).
    • initializeDeferredWork(actor, callback, props): Sets up a callback to be invoked either when actor is mapped, or when the machine is idle - useful if your actor isn't always visible on the screen and you don't want to consume resources updating if the actor isn't actually visible. (The Overview actors are all examples of these). Returns a work ID that you can use with queueDeferredWork every time you update the actor.
    • queueDeferredWork(workId): Ensures that the work identified by workId will be run on map or timeout. It is called by default on initializeDeferredWork, call it again when (say) the data being displayed by the actor changes.

  • RestartMessage:

messageList.js

  • URLHighlighter: Class to markup URLs in notifications
  • ScaleLayout:
  • LabelExpanderLayout:
  • Message:
  • MessageListSection:

messageTray.js

messageTray.js

  • FocusGrabber: Grab and control the focus for the message tray. We need this because the focus acts diferently depending of the siutation for the message tray.
  • NotificationPolicy:
  • NotificationGenericPolicy:
  • NotificationApplicationPolicy:
  • Notification: Base class defining a notification - the UI element. A notification belongs to a Source and has a title and text. In banner mode, the notification shows an icont, title, and banner on a single line. If the notification has additional elements in it or the banner doesn't fit on a single line, the notification is expandable. See messageTray.js for much more in-depth documentation.
  • NotificationBanner:
  • SourceActor:
  • SourceActorWithLabel:
  • Source: Abstract class defining a notifications source. It provides the UI element of the icon + notification counter in the message tray
  • MessageTray: The MessageTray class
  • SystemNotificationSource: Define a system source. It is inherit from Source.

If you wish to create notifications, the MessageTray.Source is the class you subclass. You need to implement the createNotificationIcon function at a minimum. When you want to send a notification from that source, use source.notify(notification), where notification is a MessageTray.Notification or subclass thereof

modalDialog.js

  • ModalDialog: A handy class defining a modal dialog. Use .setButtons to add buttons to it, and open/close to show or hide it.

Examples endSessionDialog.js, extensionDownloader.js...

mpris.js

  • MediaMessage:
  • MprisPlayer:
  • MediaSection:

notificationDaemon.js

  • FdoNotificationDaemon:
  • FdoNotificationDaemonSource:
  • GtkNotificationDaemonNotification:
  • GtkNotificationDaemonAppSource:
  • GtkNotificationDaemon:
  • NotificationDaemon: GNOME Shell uses DBus to listen/send notifications; this handles that

osdMonitorLabeler.js

  • OsdMonitorLabel:
  • OsdMonitorLabeler:

osdWindow.js

  • LevelBar:
  • OsdWindowConstraint:
  • OsdWindow:
  • OsdWindowManager:

overviewControls.js

  • SlideLayout:
  • SlidingControl:
  • ThumbnailsSlider:
  • DashSlider:
  • DashSpacer:
  • ControlsLayout:
  • ControlsManager:

overview.js

overview.js

  • ShellInfo: Handles spawning notification for actions performed from the overview and undoing them
  • Overview: The Overview triggered when you press the Super key. Made up of various tabs defined in other classes. Code in here is to do with animation when the overview shows and hides, loading search providers, interaction with the overview and so on

See also viewSelector.js, the core Applications tab appDisplay.js and the core Windows tab workspacesView.WorkspaceDisplay

padOsd.js

  • KeybindingEntry:
  • ActionComboBox:
  • ActionEditor:
  • PadDiagram:
  • PadOsd:
  • PadOsdService:

panel.js

panel.js

The panel. Yellow: _leftBox, Green: _centerBox, Red: _rightBox

panel.js

AppMenuButton with its dropdown menu

panel.js

AggregateMenu

  • AppMenuButton: This is the top titlebar (stored in Main.panel._appMenu). Inherits from panelMenu.Button, so it has a dropdown menu (by default showing Quit)
  • ActivitiesButton: The Activities button on the Top Left that triggers the overview. It is a panelMenu.Button but without a menu. Contains the layout.HotCorner that triggers the overview
  • PanelCorner: The black rounded corners that extend down from the Top Panel on either side of the screen. They are painted onto the screen using the panel colour
  • AggregateLayout:
  • AggregateMenu: It is the Status Area button, it holds the network/location/power/brightness/volume/system/etc indicators
  • Panel: The Top Panel, stored in Main.panel. It is split into three boxes into which various panel elements are all placed:
    • _leftBox, Main.panel._leftBox: Contains the ActivitiesButton and the AppMenuButton
    • _centerBox, Main.panel._centerBox: Contains the dateMenu.DateMenuButton button
    • _rightBox, Main.panel._rightBox: Contains the AggregateMenu/Status Area. However when you want to insert icons into the Status Area you should use Main.panel.addToStatusArea(role, myButton, position) where role is the role that button performs (network, a11y, ...). There can only be one button performing each role in the Status Area

panelMenu.js

panelMenu.js

Example of a panelMenu.Button, being the indicator and menu where the indicator is an icon

  • ButtonBox: The base Button class for buttons in the Panel
  • Button: Inherits from panelMenu.ButtonBox - adds a menu. So this is an object for use in the Panel that will have a menu and some sort of display item (e.g. an icon), which you are responsible for defining and adding. The dateMenu.DateMenuButton is an example of this
  • SystemIndicator: This is just a Button with an icon. Feed it in an icon name (one of the stock icon names) and it will display it. Just about every icon you have in your Status Area is one of these

pointerWatcher.js

  • PointerWatch:
  • PointerWatcher:

popupMenu.js

popupMenu.js popupMenu.js

  • PopupBaseMenuItem: Base class for popup menu items - and empty popup menu item. Has an activate signal that gets fired when the item is activated. Use .addActor to add visual elements to it like a St.Label. All the other Popup*MenuItem classes inherit from this.
  • PopupMenuItem: A PopupBaseMenuItem that displays text in a St.Label.
  • PopupSeparatorMenuItem: A PopupBaseMenuItem that is a separator.
  • Switch: An on-off toggle switch
  • PopupSwitchMenuItem: A PopupBaseMenuItem containing a label/text and a Switch to the right. Use the toggled signal to determine when the user toggles it.
  • PopupImageMenuItem: A PopupBaseMenuItem containing a label/text and an icon to the right.
  • PopupMenuBase: The base class for a popup menu (The menu that appears when you click most of the items in the status area). You don't use this directly (unless you are extending it); use any of its child classes and use menu.addMenuItem to add a popup menu item/submenu to it.
  • PopupMenu: Extends PopupMenuBase to provide a popup menu. This is the main popup menu class. (The one that gets used for all the panelMenu.Buttons)
  • PopupDummyMenu:
  • PopupSubMenu: A popup submenu - designed to be nested within a PopupMenu, has a scrollbar in case the content is too long. If you want to add it to a PopupMenu as a collapsible menu section, use PopupSubMenuMenuItem
  • PopupMenuSection: This acts like a PopupSubMenu, but to the user just looks like a normal PopupMenu. It can be useful to add multiple PopupMenuSections to a single PopupMenu to group items together code-wise (and to the user it looks like a flat popup menu).
  • PopupSubMenuMenuItem: A PopupBaseMenuItem defining a collapsible submenu - click on it to expand/open the submenu and reveal the items inside. It is really just a PopupBaseMenuItem with label and a PopupSubMenu. Use myItem.menu.addMenuItem to add to its menu.
  • PopupMenuManager: Extracted from source Basic implementation of a menu manager. Call addMenu to add menus

remoteMenu.js

  • RemoteMenuSeparatorItemMapper:
  • RequestSubMenu:
  • RemoteMenuSubmenuItemMapper:
  • RemoteMenuItemMapper:
  • RemoteMenu:

remoteSearch.js

  • RemoteSearchProvider: A search provider that acts through DBus
  • RemoteSearchProvider2:

runDialog.js

runDialog.js

  • RunDialog: The run dialog that you get on ALT + F2. Type commands in here to have them executed. Also defines a couple of special commands:
    • lg: opens the Looking Glass
    • r, restart: Restarts GNOME Shel. Needed if you make changes to JS files [WARNING: Wayland doesn't support this command, you need to change to Xorg Display Server when you log into your account]
    • rt: Reloads the shell theme
    • debugexit: Quits the shell with debug info

screencast.js

  • ScreencastService:

screenShield.js

  • Clock:
  • NotificationsBox:
  • Arrow:
  • ScreenShield:

screenshot.js

  • ScreenshotService:
  • SelectArea:
  • Flashspot:

scripting.js

Documentation extracted from the source This module provides functionality for driving the shell user interface in an automated fashion. The primary current use case for this is automated performance testing (see runPerfScript()), but it could be applied to other forms of automation, such as testing for correctness as well.

When scripting an automated test we want to make a series of calls in a linear fashion, but we also want to be able to let the main loop run so actions can finish. For this reason we write the script as a generator function that yields when it want to let the main loop run.

yield Scripting.sleep(1000);
main.overview.show();
yield Scripting.waitLeisure();

While it isn't important to the person writing the script, the actual yielded result is a function that the caller uses to provide the callback for resuming the script.

Provides:

  • sleep(milliseconds): Used within an automation script to pause the the execution of the current script for the specified amount of time. Use as:
    yield Scripting.sleep(500);
  • waitLeisure(): Used within an automation script to pause the the execution of the current script until the shell is completely idle. Use as:
    yield Scripting.waitLeisure();
  • PerfHelper: DBus proxy for org.gnome.shell.PerfHelper
  • createTestWindow(width, height, alpha, maximized): Creates a window using gnome-shell-perf-helper for testing purposes. While this function can be used with yield in an automation script to pause until the DBus call to the helper process returns, because of the normal X asynchronous mapping process, to actually wait until the window has been mapped and exposed, use waitTestWindows()
  • waitTestWindows(): Used within an automation script to pause until all windows previously created with createTestWindow have been mapped and exposed.
  • destroyTestWindows(): Destroys all windows previously created with createTestWindow(). While this function can be used with yield in an automation script to pause until the D-Bus call to the helper process returns, this doesn't guarantee that Mutter has actually finished the destroy process because of normal X asynchronicity.
  • defineScriptEvent(name, description): Convenience function to define a zero-argument performance event within the script namespace that is reserved for events defined locally within a performance automation script.
  • scriptEvent(name): Convenience function to record a script-local performance event previously defined with defineScriptEvent
  • collectStatistics(): Convenience function to trigger statistics collection.
  • runPerfScript(scriptModule): module object with run and finish functions and event handlers. Runs a script for automated collection of performance data. The script is defined as a Javascript module with specified contents. See the scripting.js file for much more detail (it's documented in there).

See the source for full documentation.

search.js

  • MaxWidthBin:
  • SearchResult: Class representing a single result of a search in the Overview
  • ListSearchResult:
  • GridSearchResult:
  • SearchResultsBase:
  • ListSearchResults:
  • GridSearchResults:
  • SearchResults:
  • ProviderIcon:

See the source for full documentation.

separator.js

  • HorizontalSeparator:

sessionMode.js

  • SessionMode:

shellDBus.js

  • GnomeShell:
  • GnomeShellExtensions:
  • ScreenSaverDBus:

shellEntry.js

shellEntry.js

  • EntryMenu: A subclass of popupMenu.PopupMenu used to provide a context menu to a Clutter.Entry or St.Entry (text box). Do not use this class directly; instead use ShellEntry.addContextMenu(entry). The context menu acts like so: when the user right-click the entry, they get a popup menu with Paste/Copy and if it is a password dialog it will have a Show/Hide character item too

shellMountOperation.js

shellMountOperation.js

  • ListItem: A button displaying a particular application's icon and name, that will launch the application when clicked. These are used in the ShellProcessesDialog, one per application that impedes the removal of a device
  • ShellMountOperation:
  • ShellUnmountNotifier:
  • ShellMountQuestionDialog: Extends modalDialog.ModalDialog to provide a dialog that asks a question about a mount and offer choices
  • ShellMountPasswordDialog:
  • ShellProcessesDialog: Extends modalDialog.ModalDialog to provide a dialog that shows you which applications are impeding the removal of a device
  • GnomeShellMountOpHandler:

slider.js

  • Slider:

switcherPopup.js

  • SwitcherPopup:
  • SwitcherList:

tweener.js

  • ClutterFrameTicker:

See the source for full documentation.

unlockDialog.js

  • UnlockDialog:

userWidget.js

  • Avatar:
  • UserWidgetLabel:
  • UserWidget:

viewSelector.js

  • FocusTrap:
  • TouchpadShowOverviewAction:
  • ShowOverviewAction:
  • ViewSelector:

windowAttentionHandler.js

shellMountOperation.js

  • WindowAttentionHandler: Handles window-demands-attention signals from global.display and pops up the x is ready notification upon receiving it. When you start up and app it can take a while to load and in the meantime you move on to another window; when the window does actually load you get a notification letting you know the application is ready to be used
  • Source: A messageTray.Source tailored to window attention requests. If you focus the windows then the notification is no longer relevant so it will remove itself

windowManager.js

  • DisplayChangeDialog:
  • WindowDimmer: When created with an actor (for example a Meta.WindowActor), dims that actor. For example when you open a modal dialog from a window, that window is dimmed until you are finished with the modal dialog
  • WorkspaceTracker:
  • TilePreview:
  • TouchpadWorkspaceSwitchAction:
  • WorkspaceSwitchAction:
  • AppSwitchAction:
  • ResizePopup:
  • WindowManager: Extra bells and whistles on the undarlying window manager. This handles things like:
    • Showing the workspace switcher popup upon receiving a switch-to-workspace-* keybinding
    • Animating all your windows sliding off the screen when you switch workspaces
    • Adding animations to windows when they are Minimized/Maximized/Mapped/Destroyed
    • Dimming a parent window if you open a modal dialog for it and undimming when the dialog is dismissed
    • Showing the window switcher ALT + Tab popup, and
    • Showing the accesibility switcher CTRL + ALT + Tab popup

windowMenu.js

  • WindowMenu:
  • AppMenu:
  • WindowMenuManager:

workspace.js

workspace.js

  • WindowCloneLayout:
  • WindowClone: The thumbnail of a window that you see in the windows tab of the Overview. You can click to activate it, drag it to move it between workspaces. One per window actor
  • WindowOverlay: This defines items that are overlaid on the WindowsClone. In particular, The windows's caption and the close button that you see on each window in the Overview
  • LayoutStrategy:
  • UnalignedLayoutStrategy:
  • Workspace: Represents a collection of WindowOverlays in the Overview. Each one just looks after the overlays in its own workspace and monitor. It handles how to lay out its overlays. This is not the workspace preview you see in the workspaces sidebar, that is a workspaceThumbnail.WorkspaceThumbnail

workspacesView.js

  • WorkspacesViewBase:
  • WorkspacesView: A container for many workspace.Workspaces
  • ExtraWorkspaceView:
  • DelegateFocusNavigator:
  • WorkspacesDisplay: This is essentially the Windows tab in the Overview. On the right hand side it has a sidebar showing workspace thumbnails that you can choose; this is a workspaceThumbnail.ThumbnailsBox. The part that shows all the window thumbnails is a WorkspacesView. This class handles things like when the workspaces preview sidebar (ThumbnailsBox) should be slidden out and in. showing/animating the rectangle about the current workspace in the sidebar animating when dynamic workspaces are added/removed, changing workspaces on scrollin ove the sidebar, etc

workspaceSwitcherPopup.js

workspaceSwitcherPopup.js

  • WorkspaceSwitcherPopup: This is the popup that appears when you switch workspaces via keybindings, showing which workspace you've switched to

workspaceThumbnail.js

workspaceThumbnail.js

  • PrimaryActorLayout:
  • WindowClone: This is a thumbnail of a window (used in a WorkspaceThumbnail) - one per window. It can be dragged to another workspace to switch its workspace
  • WorkspaceThumbnail: This is a thumbnail of a workspace, one per workspace. Shows thumbnails of all the windows on that workspace. It is an up-to-date snapshot of its windows (updates when windows are Added/Removed/Minimized/State Changed)
  • ThumbnailsBox: This is a collection of workspace thumbnails (the workspaces sidebar you see in the Overview). Handles the sliding in or out of workspaces as they are Added/Destroyed, and also dragging windows to create new workspaces between existing ones

xdndHandler.js

  • XdndHandler: Sets up Xdnd and passes through signals. When a non-gnome-shell object is first dragged over a gnome-shell-object, tha handler fires a drag-begin signal. When the object being dragged leaves the gnome-shell-object, the drage-end signal is fired. The class somehow incorporates with dnd.js code too whereby a draggable target/object registered with dnd.js has the appropiate events called on it. Use Main.xdndHandler to access the instance of the handler and connect to its signals.

Components

automountManager.js

automountManager.js

  • AutomountManager: Uses ConsoleKit to listen for drives being added, removed, connected, disconnected, ejected, etc and automounts the drive

autorunManager.js

  • HotplugSniffer: Listens on the DBus for something...
  • ContentTypeDiscoverer: Guesses what content is on a media Filesystem/Photos/Documents/Media
  • AutorunManager: Master class that handles monitoring when volumens are mounted/dismounted, uses the other classes in the file to determine what content is on the media and send a notification with the right options for that media on it (If it is a camera card offer to view photos, if it is music offer to play it, ...)
  • AutorunDispatcher: Determines a mounted volumen's autorun settings for its transient notification
  • AutorunSource: Inherits from messageTray.Source. The notification source for the autorun notification that you get upon plugging in a device.
  • AutorunNotification: Inherits from messageTray.Notification. Handles the creation of the transient notification you get upon plugging in a device. This is the notification that says View photos with Shotwel, Play music, Browse Files, etc

init.js

  • ComponentManager:

keyring.js

keyring.js

networkAgent.js

networkAgent.js

  • NetworkSecretDialog: Dialog that pops up getting you to enter in your password for wifi
  • VPNRequestHandler: Handles authentication requests for VPN
  • NetworkAgent: Listens for NetworkAgent on DBus - handles authentication requests

polkitAgent.js

polkitAgent.js

  • AuthenticationDialog: The modalDialog.ModalDialog that appears when you have to enter your password to authenticate
  • AuthenticationAgent: Wrapper around Shell.PolkitAuthenticationAgent, listens for authentication requests and shows the AuthenticationDialog

telepathyClient.js

  • TelepathyClient:
  • ChatSource:
  • ChatNotification:
  • ChatLineBox:
  • ChatNotificationBanner:

See the source for full documentation.

Status Indicators

These files define the standar status indicators in the status are

accessibility.js

accessibility.js

bluetooth.js

bluetooth.js

brightness.js

brightness.js

keyboard.js 2

keyboard.js

  • LayoutMenuItem: Extends popupMenu.PopupMenuItem. Consists of text and an either label with the keyboard layout's abbreviation.
  • InputSource:
  • InputSourcePopup:
  • InputSourceSwitcher:
  • InputSourceSettings:
  • InputSourceSystemSettings:
  • InputSourceSessionSettings:
  • InputSourceManager:
  • InputSourceIndicator:

location.js

  • Indicator:
  • AppAuthorizer:
  • GeolocationDialog:

network.js

network.js

  • NMConnectionItem:
  • NMConnectionSection:
  • NMConnectionDevice:
  • NMDeviceWired: Extends NMConnectionDevice for wired connections. It will only display the On/Off switch if you only have one wired connection port - if you have more it will have a menu section with them all
  • NMDeviceModem: Extends NMConnectionDevice for modem Dial up/Brandband. Items for individual connections have text describing the connection with an icon for signal strength
  • NMDeviceBluetooth: Extends NMConnectionDevice for bluetooth.
  • NMWirelessDialogItem:
  • NMWirelessDialog:
  • NMDeviceWireless: Extends NMConnectionDevice for wireless connections.
  • NMVPNConnectionItem:
  • NMVPNSection:
  • DeviceCategory:
  • NMApplet: The panelMenu.SystemIndicator defining the network connections indicator. Contains the various NMConnectionDevice subclasses for each connection device you have.

Also contains functions for comparing SSIDs and converting signal strengths to a category excellent/good/ok/weak

power.js

power.js

  • Indicator: The panelMenu.SystemIndicator defining the power indicator. Displays an appropiate icon for your current power state as well as calculating estimated battery life, etc

rfkill.js

  • RfkillManager:
  • Indicator:

screencast.js

  • Indicator:

system.js

system.js

  • AltSwitcher:
  • Indicator:

volume.js

volume.js

  • StreamSlider:
  • OutputStreamSlider:
  • InputStreamSlider:
  • VolumeMenu:
  • Indicator: The panelMenu.SystemIndicator defining the volume indicator. Containst a slider.Slider for the volume of each of your sound devices and adjusts its icon according to the volume

Files imports.misc

config.js

Contains the constants:

  • PACKAGE_NAME: gnome-shell (non-localized name of the package).
  • PACKAGE_VERSION: your gnome-shell version, a string (e.g. '3.22.2').
  • HAVE_BLUETOOTH: whether gnome-bluetooth is available (1 or 0).
  • HAVE_NETWORKMANAGER: whether networkmanager is available (0 or 1)
  • GETTEXT_PACKAGE: gnome-shell. GNOME-shell's gettext package name.
  • LOCALEDIR: the locale directory (/usr/share/locale).
  • LIBEXECDIR: /usr/libexe/
  • SYSCONFDIR: /etc

extensionUtils.js

Contains the extensions object (maps UUID to extension object, described in createExtensionObject)

  • Helpful functions:

    • getCurrentExtension: call it from your extension file to get the current extension object (imports.misc.extensionUtils.getCurrentExtension()).
    • versionCheck: checks if the version in metadata.json is compatible with the current shell version.
    • isOutOfDate: checks if an extension is out of date.
    • createExtensionObject: creates an object representing an extension.

  • ExtensionFinder:

fileUtils.js

Functions:

  • deleteGFile: deletes a Gio file object ("work around delete being a keyword in JS" -- just calls file['delete'](null)).
  • recursivelyDeleteDir: recursively deletes a directory.
  • recursivelyMoveDir: recursively move a directory.

gnomeSession.js

history.js

  • HistoryManager: An object that remembers text up to 512 items DEFAULT_LIMIT and optionally saves them into a gsettings key

ibusManager.js

  • IBusManager:

jsParse.js

This is a set of functions doing some basic parsing of javascript code in order to provide sensible autocompletions.

The main function you will probably want to call from external modules (according to the source) is getCompletions(text, commandHeader, globalCompletionList). There are a whole bunch of other helper functions in there too.

See the source for full documentation.

keyboardManager.js

  • KeyboardManager:

loginManager.js

  • LoginManagerSystemd:
  • LoginManagerDummy:

modemManager.js

  • ModemGsm: Class for interacting with DBus interface org.freedesktop.ModemManager.Modem.Gsm.Network (mobile internet).
  • ModemCdma: Class for interacting with DBus interface org.freedesktop.ModemManager.Modem.Cdma (mobile internet).
  • BroadbandModem:

objectManager.js

  • ObjectManager:

params.js

Contains a handy function parse that parses user-provided parameters against default parameters (filling in with defaults if not supplied), and throwing an error if unrecognised parameters are given (if unrecognised parameters are not allowed). Used throughout the js/ui/*.js code.

smartcardManager.js

  • SmartcardManager:

util.js

  • Handful of utility functions:

    • findUrls: searches input string for URLs.
    • spawn: spawns a process specified by the argument in array form (e.g. ['ls', '-al', '$HOME']), handling errors by popping up a notification in the message tray.
    • spawnCommandLine: spawns a process specified by a string (e.g. ls -al $HOME), handling errors by popping up a notification in the message tray (using Main.notifyError(#main.notifyError)).

  • CloseButton:

See the source for full documentation.