====== Gnome - Extensions - extension.js ======

**extension.js** is a mandatory file for every extension.

  * It is the core of the extension and contains the function hooks **init()**, **enable()** and **disable()** used by GNOME Shell to load, enable and disable your extension.


----

===== extension.js =====

The file can use top-level functions, or an extension object.

  * Use whichever pattern best suits.


==== Using top-level functions ====

<file javascript extension.js>
const ExtensionUtils = imports.misc.extensionUtils;
const Me = ExtensionUtils.getCurrentExtension();


function init(meta) {
    log(`initializing ${meta.metadata.name}`);
}


function enable() {
    log(`enabling ${Me.metadata.name}`);
}


function disable() {
    log(`disabling ${Me.metadata.name}`);
}
</file>

----

==== Using extension object ====

<file javascript extension.js>
// This is a handy import we'll use to grab our extension's object
const ExtensionUtils = imports.misc.extensionUtils;
const Me = ExtensionUtils.getCurrentExtension();


class Extension {
    constructor() {
    }
    
    /**
     * 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() {
        log(`enabling ${Me.metadata.name}`);
    }
    

    /**
     * This function is called when your extension is uninstalled, disabled in
     * GNOME Extensions, when you log out 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() {
        log(`disabling ${Me.metadata.name}`);
    }
}


/**
 * This function is called 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
 * MainLoop sources here.
 *
 * @param {ExtensionMeta} meta - An extension meta object, described below.
 * @returns {Object} an object with enable() and disable() methods
 */
function init(meta) {
    log(`initializing ${meta.metadata.name}`);
    
    return new Extension();
}
</file>

----

<WRAP info>
**NOTE:**  The code in **extension.js** is executed in the same process as gnome-shell.

  * You will have access to live code running in GNOME Shell, but fatal errors or mistakes will affect the stability of the desktop.

  * It also means you will be using the [[https://gjs-docs.gnome.org/#q=clutter|Clutter]] and [[https://gjs-docs.gnome.org/st10/|St]] toolkits, although you may still use utility functions and classes from Gtk.

</WRAP>


----


===== Extension Meta Object =====

An object describing the extension and various properties is available for extensions to use.

  * This is passed to the **init()** function when an extension is loaded and can be retrieved by calling **ExtensionUtils.getCurrentExtension()**.

<code javascript>
/**
 * @typedef ExtensionMeta
 * @type {object}
 * @property {object} metadata - the metadata.json file, parsed as JSON
 * @property {string} uuid - the extension UUID
 * @property {number} type - the extension type; `1` for system, `2` for user
 * @property {Gio.File} dir - the extension directory
 * @property {string} path - the extension directory path
 * @property {string} error - an error message or an empty string if no error
 * @property {boolean} hasPrefs - whether the extension has a preferences dialog
 * @property {boolean} hasUpdate - whether the extension has a pending update
 * @property {boolean} canChange - whether the extension can be enabled/disabled
 * @property {string[]} sessionModes - a list of supported session modes
 */
</code>

<WRAP important>
**WARNING:**  Some properties may only be available in some versions of GNOME Shell.

  * All properties should be considered read-only.

</WRAP>


----

===== References =====

https://wiki.gnome.org/Attic/GnomeShell/Extensions/Writing

https://gjs.guide/extensions/overview/anatomy.html#extension-js-required