====== 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