Differences

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

--- gnome:extensions:prefs.js [2022/07/23 12:04] – created 194.32.120.89
+++ gnome:extensions:prefs.js [2022/07/23 12:25] (current) – 194.32.120.105
@@ Line 1: / Line 1: @@
 ====== Gnome - Extensions - prefs.js ======
+**prefs.js** is used to build a Gtk widget that will be inserted into a window and be used as the preferences dialog for your extension.
+  * If this file is not present, there will simply be no preferences button in GNOME Extensions or on https://extensions.gnome.org/local/.
+----
+<code javascript>
+const {Adw, GLib, Gtk} = imports.gi;
+// It is common practice to keep GNOME API and JS imports in separate blocks
+const ExtensionUtils = imports.misc.extensionUtils;
+const Me = ExtensionUtils.getCurrentExtension();
+/**
+ * Like `extension.js` this is used for any one-time setup like translations.
+ *
+ * @param {ExtensionMeta} meta - An extension meta object, described below.
+ */
+function init(meta) {
+    log(`initializing ${meta.metadata.name} Preferences`);
+}
+/**
+ * This function is called when the preferences window is first created to build
+ * and return a GTK widget.
+ *
+ * As of GNOME 42, the preferences window will be a `Adw.PreferencesWindow`.
+ * Intermediate `Adw.PreferencesPage` and `Adw.PreferencesGroup` widgets will be
+ * used to wrap the returned widget if necessary.
+ *
+ * @returns {Gtk.Widget} the preferences widget
+ */
+function buildPrefsWidget() {
+    // This could be any GtkWidget subclass, although usually you would choose
+    // something like a GtkGrid, GtkBox or GtkNotebook
+    const prefsWidget = new Gtk.Label({
+        label: Me.metadata.name,
+        visible: true,
+    });
+    // Add a widget to the group. This could be any GtkWidget subclass,
+    // although usually you would choose preferences rows such as AdwActionRow,
+    // AdwComboRow or AdwRevealerRow.
+    const label = new Gtk.Label({ label: `${Me.metadata.name}` });
+    group.add(label);
+    window.add(page);
+}
+/**
+ * This function is called when the preferences window is first created to fill
+ * the `Adw.PreferencesWindow`.
+ *
+ * This function will only be called by GNOME 42 and later. If this function is
+ * present, `buildPrefsWidget()` will never be called.
+ *
+ * @param {Adw.PreferencesWindow} window - The preferences window
+ */
+function fillPreferencesWindow(window) {
+    const prefsPage = new Adw.PreferencesPage({
+        name: 'general',
+        title: 'General',
+        icon_name: 'dialog-information-symbolic',
+    });
+    window.add(prefsPage);
+    const prefsGroup = new Adw.PreferencesGroup({
+        title: 'Appearance',
+        description: `Configure the appearance of ${Me.metadata.name}`,
+    });
+    prefsPage.add(prefsGroup);
+    const showIndicatorRow = new Adw.ActionRow({
+        title: 'Show Indicator',
+        subtitle: 'Whether to show the panel indicator',
+    });
+    prefsGroup.add(showIndicatorRow);
+    const showIndicatorSwitch = new Gtk.Switch();
+    showIndicatorRow.add_suffix(showIndicatorSwitch);
+    showIndicatorRow.set_activatable_widget(showIndicatorSwitch);
+}
+</code>
+<WRAP info>
+**NOTE:**  The code in **prefs.js** will be executed in a separate Gtk process.
+  * Here you will not have access to code running in GNOME Shell, but fatal errors or mistakes will be contained within that process.
+  * In this process you will be using the Gtk toolkit, not Clutter.
+  * You can open the preferences dialog for your extension manually with gnome-extensions prefs: <code bash>
+gnome-extensions prefs example@gjs.guide
+</code>
+</WRAP>
+----
+===== stylesheet.css =====
+**stylesheet.css** is CSS stylesheet which can apply custom styles to your St widgets in extension.js or GNOME Shell as a whole.
+For example, if you had the following widgets:
+<code javascript>
+// A standard StLabel
+let label = new St.Label({
+    text: 'LabelText',
+    style_class: 'example-style'
+});
+// An StLabel subclass with `CssName` set to "ExampleLabel"
+var ExampleLabel = GObject.registerClass({
+    GTypeName: 'ExampleLabel',
+    CssName: 'ExampleLabel'
+}, class ExampleLabel extends St.Label {
+});
+let exampleLabel = new ExampleLabel({
+    text: 'Label Text'
+});
+</code>
+You could have this in your stylesheet.css:
+<code css>
+/* This will change the color of all StLabel elements */
+StLabel {
+    color: red;
+}
+/* This will change the color of all elements with the "example-style" class */
+.example-style {
+    color: green;
+}
+/* This will change the color of StLabel elements with the "example-style" class */
+StLabel.example-style {
+    color: blue;
+}
+/* This will change the color of your StLabel subclass with the custom CssName */
+ExampleLabel {
+    color: yellow;
+}
+</code>
+----
+===== Preferences =====
+https://gjs.guide/extensions/overview/anatomy.html#prefs-js
+https://gjs.guide/extensions/development/preferences.html#preferences-window