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/.

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);
}

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:

// 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'
});

You could have this in your stylesheet.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;
}

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

https://gjs.guide/extensions/development/preferences.html#preferences-window