GJS

https://gjs.guide
Admin
GJS is a JavaScript programming environment for GNOME that provides extensive bindings to GNOME...
Tokens:188,178
Snippets:1,537
Trust Score:7.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Generated example@gjs.guide.pot

Source: https://gjs.guide/extensions/development/translations.html

Example POT file generated by xgettext, showing the template structure with metadata and translatable strings.

```sh
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2023-08-10 19:00-0700\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"

#: extension.js:24
msgctxt "menu item"
msgid "Notify"
msgstr ""

#: extension.js:28
msgid "Notification"
msgstr ""

#: extension.js:31
#, javascript-format
msgid "You have been notified %d time"
msgid_plural "You have been notified %d times"
msgstr[0] ""
msgstr[1] ""
```

--------------------------------

### Run gnome-shell-test-tool with --extension

Source: https://gjs.guide/extensions/upgrading/gnome-shell-50.html

Install and enable an extension zip package before starting GNOME Shell for testing. The --extension option accepts the path to the extension package and the test script to run.

```bash
gnome-shell-test-tool --extension extension-package.zip tests/testMyExtension.js
```

--------------------------------

### Gtk.Button example

Source: https://gjs.guide/guides/gtk/3/07-buttons.html

Creates a simple button with a label and connects to the 'clicked' signal to log a message. The button is added to a window and the main loop is started.

```javascript
#!/usr/bin/env gjs

imports.gi.versions.Gtk = "3.0";
const { Gtk } = imports.gi;

Gtk.init(null);

const button = new Gtk.Button({ label: 'Click Me!' });
button.connect('clicked', () => {
    log('The button was clicked!');
});

const win = new Gtk.Window({ defaultHeight: 600, defaultWidth: 800 });
win.connect('destroy', () => { Gtk.main_quit(); });
win.add(button);
win.show_all();

Gtk.main();
```

--------------------------------

### Full GTK GJS example template

Source: https://gjs.guide/guides/gtk/3/04-running-gtk.html

The complete template for GTK examples in GJS. It includes the shebang, version and import statements, GTK initialization, widget creation, and the main loop. Use this as a starting point for any GTK GJS script.

```javascript
#!/usr/bin/env gjs

imports.gi.versions.Gtk = "3.0";
const { Gtk } = imports.gi;

Gtk.init(null);

/* create a widget to demonstrate */

let win = new Gtk.Window();
win.add(/* widget */);
win.show_all();

Gtk.main();
```

--------------------------------

### Full Gtk.Application example

Source: https://gjs.guide/guides/gtk/3/10-building-app.html

Complete final version of the Gtk.Application example, integrating all the pieces: imports, ImageViewerWindow class, Gtk.Application creation, 'activate' handler, and application.run().

```javascript
#!/usr/bin/env gjs

imports.gi.versions.Gtk = "3.0";
const { Gio, Gtk } = imports.gi;

class ImageViewerWindow {
    constructor(app) {
        this._app = app;
        this._window = null;
        this._box = null;
        this._image = null;
        this._fileChooserButton = null;
    }

    _buildUI() {
        this._window = new Gtk.ApplicationWindow({
            application: this._app,
            defaultHeight: 600,
            defaultWidth: 800
        });
        this._box = new Gtk.Box({
            orientation: Gtk.Orientation.VERTICAL
        });

        this._image = new Gtk.Image({
            vexpand: true
        });
        this._box.add(this._image);

        this._fileChooserButton = Gtk.FileChooserButton.new('Pick An Image', Gtk.FileChooserAction.OPEN);

        this._fileChooserButton.connect('file-set', (button) => {
            const fileName = button.get_filename();
            this._image.set_from_file(fileName);
        });

        this._box.add(this._fileChooserButton);
        this._box.show_all();

        this._window.add(this._box);
    }

    getWidget() {
        this._buildUI();
        return this._window;
    }
}

const application = new Gtk.Application({
    application_id: 'org.gnome.Sandbox.ImageViewerExample',
    flags: Gio.ApplicationFlags.FLAGS_NONE
});

application.connect('activate', app => {
    let activeWindow = app.activeWindow;

    if (!activeWindow) {
        let imageViewerWindow = new ImageViewerWindow(app);
        activeWindow = imageViewerWindow.getWidget();
    }

    activeWindow.present();
});

application.run(null);

```

--------------------------------

### Complete Example for GNOME Shell 44 or Earlier

Source: https://gjs.guide/extensions/upgrading/legacy-documentation.html

A working extension example for GNOME Shell 44 or earlier. Creates a panel button with an icon and a preferences menu item, and properly cleans up in disable().

```javascript
const St = imports.gi.St;

const ExtensionUtils = imports.misc.extensionUtils;
const Me = ExtensionUtils.getCurrentExtension();
const Main = imports.ui.main;
const PanelMenu = imports.ui.panelMenu;

const {
    gettext: _,
} = ExtensionUtils;


class Extension {
    enable() {
        // Create a panel button
        this._indicator = new PanelMenu.Button(0.0, Me.metadata.name, false);

        // Add an icon
        const icon = new St.Icon({
            icon_name: 'face-laugh-symbolic',
            style_class: 'system-status-icon',
        });
        this._indicator.add_child(icon);

        // Add the indicator to the panel
        Main.panel.addToStatusArea(Me.metadata.uuid, this._indicator);

        // Add a menu item to open the preferences window
        this._indicator.menu.addAction(_('Preferences'),
            () => ExtensionUtils.openPrefs());

        this._count = 0;
    }

    disable() {
        if (this._indicator) {
            this._indicator.destroy();
            this._indicator = null;
        }
    }
}


function init() {
    ExtensionUtils.initTranslations();

    return new Extension();
}
```

--------------------------------

### Complete example with imports and regions for actions and action group

Source: https://gjs.guide/guides/gio/dbus.html

A full example that imports GLib and Gio, then defines the same actions and action group as above, using #region markers to separate the action creation and the action group export. This is the complete code for the section.

```javascript
import GLib from 'gi://GLib';
import Gio from 'gi://Gio';


// #region action
// This is the most basic an action can be. It has a name and can be activated
// with no parameters, which results in the callback being invoked.
const basicAction = new Gio.SimpleAction({
    name: 'basicAction',
});

basicAction.connect('activate', (action, _parameter) => {
    console.log(`${action.name} activated!`);
});

// An action with a parameter
const paramAction = new Gio.SimpleAction({
    name: 'paramAction',
    parameter_type: new GLib.VariantType('s'),
});

paramAction.connect('activate', (action, parameter) => {
    console.log(`${action.name} activated: ${parameter.unpack()}`);
});

// And a stateful action. The state type is set at construction from the initial
// value, and can't be changed afterwards.
const stateAction = new Gio.SimpleAction({
    name: 'stateAction',
    state: GLib.Variant.new_boolean(true),
});

stateAction.connect('notify::state', (action, _pspec) => {
    console.log(`${action.name} changed: ${action.state.print(true)}`);
});
// #endregion action


// #region action-group
// Adding actions to an action group
const actionGroup = new Gio.SimpleActionGroup();
actionGroup.add_action(basicAction);
actionGroup.add_action(paramAction);
actionGroup.add_action(stateAction);


// Exporting action groups on the session bus
const connection = Gio.DBus.session;
const groupId = connection.export_action_group('/guide/gjs/Test',
    actionGroup);
```

--------------------------------

### Adding widget and starting main loop

Source: https://gjs.guide/guides/gtk/3/04-running-gtk.html

Adds a widget to the window, shows the window and widget, and starts the GTK main loop with Gtk.main().

```javascript
...

let win = new Gtk.Window();
win.add(/* widget */);
win.show_all();

Gtk.main();
```

--------------------------------

### Makefile for building and packaging a GNOME Shell extension

Source: https://gjs.guide/extensions/development/typescript.html

Defines targets: all, pack, install, and clean. Run 'make' to compile and generate dist/extension.js and dist/prefs.js, installing dependencies if needed. 'make pack' creates my-extension.zip, 'make install' installs the extension, and 'make clean' removes generated files.

```makefile
NAME=my-extension
DOMAIN=example.com

.PHONY: all pack install clean

all: dist/extension.js

node_modules/.package-lock.json: package.json
	npm install

dist/extension.js dist/prefs.js: node_modules/.package-lock.json *.ts
	npm run build

schemas/gschemas.compiled: schemas/org.gnome.shell.extensions.$(NAME).gschema.xml
	glib-compile-schemas schemas

$(NAME).zip: dist/extension.js dist/prefs.js schemas/gschemas.compiled
	@cp -r schemas dist/
	@cp metadata.json dist/
	@(cd dist && zip ../$(NAME).zip -9r .)

pack: $(NAME).zip

install: $(NAME).zip
	gnome-extensions install --force $(NAME).zip

clean:
	@rm -rf dist node_modules $(NAME).zip

```

--------------------------------

### Extension Installation Folder Path

Source: https://gjs.guide/extensions/overview/anatomy.html

Shows the required installation folder path for an extension, which must match the extension's UUID.

```sh
~/.local/share/gnome-shell/extensions/example@gjs.guide/

```

--------------------------------

### Start nested GNOME Shell (GNOME 48 and earlier)

Source: https://gjs.guide/extensions/development/debugging.html

Command to start a nested GNOME Shell instance for development on GNOME 48 and earlier.

```bash
dbus-run-session gnome-shell --nested --wayland
```

--------------------------------

### Get Prefs Window and Resize it

Source: https://gjs.guide/extensions/upgrading/gnome-shell-40.html

In GNOME 40, use `get_root()` instead of `get_toplevel()` to get the prefs window. `resize()` is removed in GTK4; use `default_width` and `default_height` to set the default size.

```javascript
prefsWidget.connect('realize', () => {
    let window = prefsWidget.get_root();
    window.default_width = 700;
    window.default_height = 900;
    // window.resize(700, 900);
});
```

--------------------------------

### Start nested GNOME Shell (GNOME 49+)

Source: https://gjs.guide/extensions/development/debugging.html

Command to start a nested GNOME Shell instance for development on GNOME 49 and later.

```bash
dbus-run-session gnome-shell --devkit --wayland
```

--------------------------------

### Example SearchProvider class

Source: https://gjs.guide/extensions/upgrading/legacy-documentation.html

A complete example of a search provider class with appInfo, canLaunchSearch, id, activateResult, and launchSearch methods. Extensions typically return null for appInfo, false for canLaunchSearch, and their UUID for id.

```javascript
class SearchProvider {
    /**
     * The application of the provider.
     *
     * Applications will return a `Gio.AppInfo` representing themselves.
     * Extensions will usually return `null`.
     *
     * @type {Gio.AppInfo}
     */
    get appInfo() {
        return null;
    }

    /**
     * Whether the provider offers detailed results.
     *
     * Applications will return `true` if they have a way to display more
     * detailed or complete results. Extensions will usually return `false`.
     *
     * @type {boolean}
     */
    get canLaunchSearch() {
        return false;
    }

    /**
     * The unique ID of the provider.
     *
     * Applications will return their application ID. Extensions will usually
     * return their UUID.
     *
     * @type {string}
     */
    get id() {
        return imports.misc.extensionUtils.getCurrentExtension().uuid;
    }

    /**
     * Launch the search result.
     *
     * This method is called when a search provider result is activated.
     *
     * @param {string} result - The result identifier
     * @param {string[]} terms - The search terms
     */
    activateResult(result, terms) {
        console.debug(`activateResult(${result}, [${terms}])`);
    }

    /**
     * Launch the search provider.
     *
     * This method is called when a search provider is activated. A provider can
     * only be activated if the `appInfo` property holds a valid `Gio.AppInfo`
     * and the `canLaunchSearch` property is `true`.
     *
     * Applications will typically open a window to display more detailed or
     * complete results.
     *
     * @param {string[]} terms - The search terms
     */
    launchSearch(terms) {
        console.debug(`launchSearch([${terms}])`);
    }
}
```

--------------------------------

### Example metadata.json for a GNOME Shell extension

Source: https://gjs.guide/extensions/review-guidelines/review-guidelines.html

Shows a well-formed metadata.json with required keys: uuid, name, description, shell-version, url, and session-modes. The uuid uses the form extension-id@namespace, and the description includes a bullet point list. This example omits deprecated or unnecessary keys like version and donations.

```json
{
    "uuid": "color-button@my-account.github.io",
    "name": "ColorButton",
    "description": "ColorButton adds a colored button to the panel.\n\nIt is a fork of MonochromeButton.",
    "shell-version": [ "3.38", "40", "41.alpha" ],
    "url": "https://github.com/my-account/color-button",
    "session-modes":  [ "unlock-dialog", "user" ]
}
```

--------------------------------

### Get GType name with $gtype.name

Source: https://gjs.guide/guides/gobject/gtype.html

Shows how to get the GType name as a string using the `name` property of a GType object. The example defines a subclass with `GObject.registerClass()` and logs the default GType names for `GObject.Object` and the subclass, which are prefixed with `Gjs_`.

```js
const ExampleSubclass = GObject.registerClass({
}, class ExampleSubclass extends GObject.Object {
});

const objectInstance = new GObject.Object();
const subclassInstance = new ExampleSubclass();

// expected output: 'GObject'
console.log(GObject.Object.$gtype.name);
console.log(objectInstance.constructor.$gtype.name);

// expected output: 'Gjs_MySubclass'
console.log(ExampleSubclass.$gtype.name);
console.log(subclassInstance.constructor.$gtype.name);
```

--------------------------------

### System Indicator: ExampleIndicator class

Source: https://gjs.guide/extensions/upgrading/legacy-documentation.html

Creates a QuickSettings.SystemIndicator that shows an icon in the panel and manages quick setting items. Binds the indicator's visibility to a GSettings key, adds the toggle to the indicator, and cleans up on destroy. Adds the indicator to the panel and the toggle to the menu.

```javascript
const ExampleIndicator = GObject.registerClass(
class ExampleIndicator extends QuickSettings.SystemIndicator {
    _init() {
        super._init();

        // Create the icon for the indicator
        this._indicator = this._addIndicator();
        this._indicator.icon_name = 'selection-mode-symbolic';

        // Showing the indicator when the feature is enabled
        this._settings = ExtensionUtils.getSettings();
        this._settings.bind('feature-enabled',
            this._indicator, 'visible',
            Gio.SettingsBindFlags.DEFAULT);

        // Create the toggle and associate it with the indicator, being sure to
        // destroy it along with the indicator
        this.quickSettingsItems.push(new ExampleToggle());

        this.connect('destroy', () => {
            this.quickSettingsItems.forEach(item => item.destroy());
        });

        // Add the indicator to the panel and the toggle to the menu
        QuickSettingsMenu._indicators.add_child(this);
        QuickSettingsMenu._addItems(this.quickSettingsItems);
    }
});
```

--------------------------------

### Run gnome-extensions create --interactive

Source: https://gjs.guide/extensions/development/creating.html

Starts the interactive extension creation wizard. Run from any directory; the extension will be created in ~/.local/share/gnome-shell/extensions.

```sh
$ gnome-extensions create --interactive
```

--------------------------------

### Promise Wrappers for Gio File Operations

Source: https://gjs.guide/guides/gio/file-operations.html

Sets up promise wrappers for asynchronous Gio methods used throughout the guide. This is required before using the async methods in the examples.

```js
import Gio from 'gi://Gio';


/* Gio.File */
Gio._promisify(Gio.File.prototype, 'copy_async');
Gio._promisify(Gio.File.prototype, 'create_async');
Gio._promisify(Gio.File.prototype, 'delete_async');
Gio._promisify(Gio.File.prototype, 'enumerate_children_async');
Gio._promisify(Gio.File.prototype, 'load_contents_async');
Gio._promisify(Gio.File.prototype, 'make_directory_async');
Gio._promisify(Gio.File.prototype, 'move_async');
Gio._promisify(Gio.File.prototype, 'open_readwrite_async');
Gio._promisify(Gio.File.prototype, 'query_info_async');
Gio._promisify(Gio.File.prototype, 'replace_contents_async');
Gio._promisify(Gio.File.prototype, 'replace_contents_bytes_async',
    'replace_contents_finish');
Gio._promisify(Gio.File.prototype, 'trash_async');

/* Gio.FileEnumerator */
Gio._promisify(Gio.FileEnumerator.prototype, 'next_files_async');

/* Gio.InputStream */
Gio._promisify(Gio.InputStream.prototype, 'read_bytes_async');

/* Gio.OutputStream */
Gio._promisify(Gio.OutputStream.prototype, 'write_bytes_async');
```

--------------------------------

### Query Signal Information with GObject.signal_query()

Source: https://gjs.guide/guides/gobject/advanced.html

Pass a signal ID to GObject.signal_query() to get a GObject.SignalQuery object. The example checks that the result is not null and logs the interface name and signal name.

```js
const destroyQuery = GObject.signal_query(destroyId);

if (destroyQuery !== null)
    console.log(`Found signal: ${destroyQuery.itype.name}::${destroyQuery.signal_name}`);
```

--------------------------------

### Build project with Ninja

Source: https://gjs.guide/guides/gtk/3/12-app-dev.html

Run these commands to create a build directory, enter it, and build the project using Ninja.

```bash
mkdir build && cd build && ninja && ninja build

```

--------------------------------

### Lookup extension object by UUID or URL

Source: https://gjs.guide/extensions/upgrading/gnome-shell-45.html

Demonstrates the static methods Extension.lookupByUUID() and Extension.lookupByURL() to retrieve the extension object from any module. The example shows how to get settings and metadata from the extension object.

```javascript
import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';


let extensionObject, extensionSettings;

// Getting the extension object by UUID
extensionObject = Extension.lookupByUUID('example@gjs.guide');
extensionSettings = extensionObject.getSettings();
console.log(extensionObject.metadata);

// Getting the extension object by URL
extensionObject = Extension.lookupByURL(import.meta.url);
extensionSettings = extensionObject.getSettings();
console.log(extensionObject.metadata);
```

--------------------------------

### List and Lookup Signal IDs with GObject.signal_list_ids() and GObject.signal_lookup()

Source: https://gjs.guide/guides/gobject/advanced.html

Use GObject.signal_list_ids() to iterate over signal IDs for a class, and GObject.signal_lookup() to get a signal ID by name. The example checks that the lookup result is non-zero before logging.

```js
for (const signalId of GObject.signal_list_ids(Gtk.Widget))
    console.log(`Found signal: ${signalId}`);

const notifyId = GObject.signal_lookup('notify', GObject.Object);

if (notifyId !== 0)
    console.log(`Found signal: ${notifyId}`);
```

--------------------------------

### Open extension preferences with gnome-extensions prefs

Source: https://gjs.guide/extensions/overview/anatomy.html

Opens the preferences dialog for the extension identified by `example@gjs.guide`. Run from a terminal.

```sh
$ gnome-extensions prefs example@gjs.guide
```

--------------------------------

### Access GType with $gtype and GObject.type_from_name()

Source: https://gjs.guide/guides/gobject/gtype.html

Shows how to get the GType of a class or instance using the static `$gtype` property and `GObject.type_from_name()`. The example creates a `Gio.ThemedIcon` and compares its constructor's `$gtype` with the class's `$gtype` and the result of `GObject.type_from_name('GThemedIcon')`, logging when they are equivalent.

```js
const icon = new Gio.ThemedIcon({name: 'dialog-information'});

if (icon.constructor.$gtype === Gio.ThemedIcon.$gtype)
    console.log('These values are exactly equivalent');

if (icon.constructor.$gtype === GObject.type_from_name('GThemedIcon'))
    console.log('These values are exactly equivalent');
```

--------------------------------

### pkg.initFormat()

Source: https://gjs.guide/guides/gtk/application-packaging.html

Initializes the format module. After calling, String.prototype.format becomes available.

```APIDOC
## pkg.initFormat()

### Description
Initializes the format module. After calling, `String.prototype.format` becomes available.

### Method
Function call

### Endpoint
`pkg.initFormat()`

### Parameters
None

### Response
#### Success Response
No return value.

#### Response Example
```
undefined
```
```

--------------------------------

### pkg.initGettext()

Source: https://gjs.guide/guides/gtk/application-packaging.html

Initializes gettext. After calling, window._, window.C_ and window.N_ become available.

```APIDOC
## pkg.initGettext()

### Description
Initializes gettext. After calling, `window._`, `window.C_` and `window.N_` become available.

### Method
Function call

### Endpoint
`pkg.initGettext()`

### Parameters
None

### Response
#### Success Response
No return value.

#### Response Example
```
undefined
```
```

--------------------------------

### Example stack trace output

Source: https://gjs.guide/extensions/development/debugging.html

An example of the stack trace printed to the terminal when SHELL_DEBUG is enabled.

```text
(gnome-shell:37007): libmutter-WARNING **: 11:08:37.446: (../src/backends/meta-barrier.c:283):init_barrier_impl: runtime check failed: (priv->impl)
== Stack trace for context 0x55cf122c0ce0 ==
#0   55cf1238c058 i   resource:///org/gnome/shell/ui/layout.js:590 (12915b5d6560 @ 281)
#1   55cf1238bfc8 i   resource:///org/gnome/shell/ui/layout.js:569 (12915b5d64c0 @ 22)
#2   55cf1238bf38 i   resource:///org/gnome/shell/ui/init.js:21 (12915b570ba0 @ 48)
```

--------------------------------

### Setting up Gtk.Application imports

Source: https://gjs.guide/guides/gtk/3/10-building-app.html

Initial imports for the Gtk.Application example. It sets the Gtk version to 3.0 and imports Gio (needed for Gtk.Application) in addition to Gtk.

```javascript
#!/usr/bin/env gjs

imports.gi.versions.Gtk = "3.0";
const { Gio, Gtk } = imports.gi;

...

```

--------------------------------

### Set and get a string on a GObject.Value

Source: https://gjs.guide/guides/gobject/gvalue.html

Shows how to set and get a string value on an initialized GObject.Value.

```js
const stringValue = new GObject.Value();
stringValue.init(GObject.TYPE_STRING);

// Set and get the value contents
stringValue.set_string('string value');
console.log(stringValue.get_string());
```

--------------------------------

### Run the application

Source: https://gjs.guide/guides/gtk/3/12-app-dev.html

Execute the built application from the run directory.

```bash
./run/**your.app.name**

```

--------------------------------

### Install gtk4-builder-tool

Source: https://gjs.guide/extensions/upgrading/gnome-shell-40.html

Installs gtk4-builder-tool via dnf on Fedora. Required for validating and converting GTK3 XML to GTK4.

```sh
sudo dnf install gtk4-devel
```

--------------------------------

### PopupMenu.removeAll()

Source: https://gjs.guide/extensions/topics/popup-menu.html

Removes all items from the menu. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenu.removeAll()

### Description
Removes all items from the menu. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

### Method
removeAll()

### Parameters
None

### Example
```js
menu.removeAll();
```
```

--------------------------------

### Complete metadata.json with All Optional Fields

Source: https://gjs.guide/extensions/overview/anatomy.html

A complete metadata.json example demonstrating all current optional fields, including gettext-domain, settings-schema, session-modes, donations, version, and version-name.

```json
{
    "uuid": "example@gjs.guide",
    "name": "Example Extension",
    "description": "An example extension",
    "shell-version": [ "3.38", "45" ],
    "url": "https://gjs.guide/extensions",
    "gettext-domain": "example@gjs.guide",
    "settings-schema": "org.gnome.shell.extensions.example",
    "session-modes": ["user", "unlock-dialog"],
    "donations": {
        "github": "john_doe",
        "custom": ["https://example.com/1/", "https://example.com/2/"]
    },
    "version": 2,
    "version-name": "1.1"
}

```

--------------------------------

### Initialize Meson build

Source: https://gjs.guide/guides/gtk/3/12-app-dev.html

Run this command in your project's root directory to initialize Meson with a custom prefix for your project directory.

```bash
meson --set-prefix=***/your/project/directory***/run/

```

--------------------------------

### PopupMenu.close(animation)

Source: https://gjs.guide/extensions/topics/popup-menu.html

Closes the menu with an optional animation. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenu.close(animation)

### Description
Closes the menu with an optional animation. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

### Method
close(animation)

### Parameters
- **animation** (`BoxPointer.PopupAnimation`) - Optional - The animation to use when closing.

### Example
```js
menu.close(BoxPointer.PopupAnimation.NONE);
```
```

--------------------------------

### extension.js: ExampleExtension class with enable() and disable()

Source: https://gjs.guide/extensions/overview/anatomy.html

Required file for every extension. Must export a subclass of the base Extension and implement enable() and disable(). If overriding constructor(), must call super() with the metadata argument. Do not modify GNOME Shell in constructor; setup UI and connect signals in enable(); undo all changes in disable().

```javascript
import {Extension} from 'resource:///org/gnome/shell/extensions/extension.js';


export default class ExampleExtension extends Extension {
    /**
     * This class is constructed once when your extension is loaded, not
     * enabled. This is a good time to setup translations or anything else you
     * only do once.
     *
     * You MUST NOT make any changes to GNOME Shell, connect any signals or add
     * any event sources here.
     *
     * @param {ExtensionMeta} metadata - An extension meta object
     */
    constructor(metadata) {
        super(metadata);

        console.debug(`constructing ${this.metadata.name}`);
    }

    /**
     * This function is called when your extension is enabled, which could be
     * done in GNOME Extensions, when you log in or when the screen is unlocked.
     *
     * This is when you should setup any UI for your extension, change existing
     * widgets, connect signals or modify GNOME Shell's behavior.
     */
    enable() {
        console.debug(`enabling ${this.metadata.name}`);
    }

    /**
     * This function is called when your extension is uninstalled, disabled in
     * GNOME Extensions or when the screen locks.
     *
     * Anything you created, modified or setup in enable() MUST be undone here.
     * Not doing so is the most common reason extensions are rejected in review!
     */
    disable() {
        console.debug(`disabling ${this.metadata.name}`);
    }
}
```

--------------------------------

### GNOME 44 and earlier Extension class with init()

Source: https://gjs.guide/extensions/review-guidelines/review-guidelines.html

Shows the pattern for GNOME 44 and earlier: init() initializes translations and returns a new Extension instance; constructor must not create objects; enable() and disable() handle setup and cleanup.

```javascript
const ExtensionUtils = imports.misc.extensionUtils;

class Extension {
    constructor() {
        // DO NOT create objects, connect signals or add main loop sources here
    }

    enable() {
        // Create objects, connect signals, create main loop sources, etc.
    }

    disable() {
        // Destroy objects, disconnect signals, remove main loop sources, etc.
    }
}

function init() {
    // Initialize translations before returning the extension object
    ExtensionUtils.initTranslations();

    return new Extension();
}
```

--------------------------------

### PopupMenu.open(animation)

Source: https://gjs.guide/extensions/topics/popup-menu.html

Opens the menu with an optional animation. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenu.open(animation)

### Description
Opens the menu with an optional animation. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

### Method
open(animation)

### Parameters
- **animation** (`BoxPointer.PopupAnimation`) - Optional - The animation to use when opening.

### Example
```js
menu.open(BoxPointer.PopupAnimation.FADE);
```
```

--------------------------------

### PopupMenuSection.addAction(label, callback)

Source: https://gjs.guide/extensions/topics/popup-menu.html

Adds an action item to the section. This method is used in the example but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenuSection.addAction(label, callback)

### Description
Adds an action item to the section. This method is used in the example but not explicitly documented in the source; it is inferred from the example usage.

### Method
addAction(label, callback)

### Parameters
- **label** (`String`) - Required - The label for the menu item.
- **callback** (`Function`) - Required - The callback to invoke when the item is activated.

### Example
```js
section.addAction('Menu Item', () => console.log('activated'));
```
```

--------------------------------

### Create and Add a SystemIndicator with addExternalIndicator

Source: https://gjs.guide/extensions/topics/quick-settings.html

These two snippets together show how to create a system indicator with QuickSettings.SystemIndicator and add it to the quick settings area. The first defines the indicator class, binding a settings key to control icon visibility and pushing a toggle to quickSettingsItems; the second registers it via addExternalIndicator in the extension's enable() and destroys it in disable(). An instance of this class is required for all extensions with quick settings, even without an icon.

```js
const ExampleIndicator = GObject.registerClass(
class ExampleIndicator extends QuickSettings.SystemIndicator {
    constructor(extensionObject) {
        super();

        // Create an icon for the indicator
        this._indicator = this._addIndicator();
        this._indicator.icon_name = 'selection-mode-symbolic';

        // Showing an indicator when the feature is enabled
        this._settings = extensionObject.getSettings();
        this._settings.bind('feature-enabled',
            this._indicator, 'visible',
            Gio.SettingsBindFlags.DEFAULT);

        // Add a toggle to the quick settings items
        this.quickSettingsItems.push(new ExampleToggle(extensionObject));
    }

    destroy() {
        this.quickSettingsItems.forEach(item => item.destroy());
        super.destroy();
    }
});
```

```js
export default class ExampleExtension extends Extension {
    enable() {
        this._indicator = new ExampleIndicator(this);

        Main.panel.statusArea.quickSettings.addExternalIndicator(this._indicator);
    }

    disable() {
        this._indicator.destroy();
        this._indicator = null;
    }
}
```

--------------------------------

### Importing versioned GI libraries (Soup 3.0) before and after GNOME 45

Source: https://gjs.guide/extensions/upgrading/gnome-shell-45.html

Demonstrates setting the version before importing in the old way and using the ?version= query parameter in the new ESM import.

```javascript
// Before GNOME 45
imports.gi.versions.Soup = '3.0';
const Soup = imports.gi.Soup;

// GNOME 45
import Soup from 'gi://Soup?version=3.0';
```

--------------------------------

### PopupMenu.addMenuItem(menuItem, position)

Source: https://gjs.guide/extensions/topics/popup-menu.html

Adds a menu item to the menu. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenu.addMenuItem(menuItem, position)

### Description
Adds a menu item to the menu. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

### Method
addMenuItem(menuItem, position)

### Parameters
- **menuItem** (`PopupBaseMenuItem`) - Required - The menu item to add.
- **position** (`Number`) - Optional - The index at which to insert the item.

### Example
```js
const menuItem2 = new PopupMenu.PopupMenuItem('Item 2');
menu.addMenuItem(menuItem2, 0);
```
```

--------------------------------

### Creating a GLib.MainLoop with a timeout source

Source: https://gjs.guide/guides/gjs/asynchronous-programming.html

Demonstrates initializing a main loop and adding a timeout source that executes a callback after one second. Note that this example will not exit on its own as the loop is never instructed to quit.

```javascript
import GLib from 'gi://GLib';


// Here we're creating an event loop, to iterate the main context
const loop = new GLib.MainLoop(null, false);

// Here we're adding a timeout source to the main context that executes a
// callback after one second. The returned ID can be used to remove the source.
const sourceId = GLib.timeout_add_seconds(
    GLib.PRIORITY_DEFAULT,           // priority of the source
    1,                               // seconds to wait
    () => {                          // the callback to invoke
        return GLib.SOURCE_CONTINUE; // the return value; to recurse or not?
    }
);

// Here we're starting the loop, instructing it to process sources (events)
await loop.runAsync();
```

--------------------------------

### PopupMenu.addAction(label, callback)

Source: https://gjs.guide/extensions/topics/popup-menu.html

Adds an action item to the menu. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenu.addAction(label, callback)

### Description
Adds an action item to the menu. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

### Method
addAction(label, callback)

### Parameters
- **label** (`String`) - Required - The label for the menu item.
- **callback** (`Function`) - Required - The callback to invoke when the item is activated.

### Example
```js
menu.addAction('Item 1', () => console.log('activated'));
```
```

--------------------------------

### Get and Set D-Bus Properties with Gio.DBus.session.call

Source: https://gjs.guide/guides/gio/dbus.html

Shows how to get and set a property on a D-Bus service using the standard org.freedesktop.DBus.Properties interface. The Get call retrieves the ShellVersion property, and the Set call sets OverviewActive to true. Both calls use Gio.DBus.session.call() with GLib.Variant arguments and handle Gio.DBusError.

```javascript
import GLib from 'gi://GLib';
import Gio from 'gi://Gio';


/*
 * Getting a property value
 */
try {
    const reply = await Gio.DBus.session.call(
        'org.gnome.Shell',
        '/org/gnome/Shell',
        'org.freedesktop.DBus.Properties',
        'Get',
        new GLib.Variant('(ss)', [
            'org.gnome.Shell',
            'ShellVersion',
        ]),
        null,
        Gio.DBusCallFlags.NONE,
        -1,
        null);

    const [version] = reply.recursiveUnpack();

    console.log(`GNOME Shell Version: ${version}`);
} catch (e) {
    if (e instanceof Gio.DBusError)
        Gio.DBusError.strip_remote_error(e);

    logError(e);
}

/*
 * Setting a property value
 */
try {
    await Gio.DBus.session.call(
        'org.gnome.Shell',
        '/org/gnome/Shell',
        'org.freedesktop.DBus.Properties',
        'Set',
        new GLib.Variant('(ssv)', [
            'org.gnome.Shell',
            'OverviewActive',
            GLib.Variant.new_boolean(true),
        ]),
        null,
        Gio.DBusCallFlags.NONE,
        -1,
        null);
} catch (e) {
    if (e instanceof Gio.DBusError)
        Gio.DBusError.strip_remote_error(e);

    logError(e);
}
```

--------------------------------

### PopupMenu.moveMenuItem(menuItem, position)

Source: https://gjs.guide/extensions/topics/popup-menu.html

Moves a menu item to a new position. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

```APIDOC
## PopupMenu.moveMenuItem(menuItem, position)

### Description
Moves a menu item to a new position. This method is used in the examples but not explicitly documented in the source; it is inferred from the example usage.

### Method
moveMenuItem(menuItem, position)

### Parameters
- **menuItem** (`PopupBaseMenuItem`) - Required - The menu item to move.
- **position** (`Number`) - Required - The new index for the item.

### Example
```js
menu.moveMenuItem(menuItem2, 1);
```
```
Tokens:
Raw