Differences

This shows you the differences between two versions of the page.

--- gnome:extensions:extension.js [2022/07/23 10:32] – created 194.32.120.110
+++ gnome:extensions:extension.js [2022/07/23 12:24] (current) – 194.32.120.105
@@ Line 4: / Line 4: @@
   * 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