♻️ Refactor how preferences pages are set up

docs/how-to-create-new-effects.md

@@ -138,8 +138,9 @@ var SimpleFade = class SimpleFade {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
     // Empty for now... Code is added here later in the tutorial!
+    return null;
   }
 
   // ---------------------------------------------------------------- API for extension.js
@@ -248,7 +249,7 @@ There should be two sliders in this example: The animation duration and the widt
 If your effect supports GNOME Shell 3.3x _and_ GNOME Shell 40+, you will have to provide two `*.ui` files for this.
 This is because starting with GNOME Shell 40, the preference dialog uses GTK4, before it used to use GTK3.
 Usually, there are only a few minor differences between the two files.
-We will load the respective file in the `initPreferences()` method of your new effect class.
+We will load the respective file in the `getPreferences()` method of your new effect class.
 
 Just save the code below to `resources/ui/gtk3/SimpleFade.ui` and `resources/ui/gtk4/SimpleFade.ui` respectively.
 Remember to replace any occurrence of `simple-fade` with your effect's nick-name!
@@ -528,10 +529,10 @@ Remember to replace any occurrence of `simple-fade` with your effect's nick-name
 
 ### Loading the Preferences Page
 
-In order to load the above `*.ui` files, add the following code to your effect's `initPreferences()` method.
+In order to load the above `*.ui` files, add the following code to your effect's `getPreferences()` method.
 
 ```javascript
-static initPreferences(dialog) {
+static getPreferences(dialog) {
 
   // Add the settings page to the builder.
   dialog.getBuilder().add_from_resource(`/ui/${utils.getGTKString()}/SimpleFade.ui`);
@@ -541,12 +542,9 @@ static initPreferences(dialog) {
   dialog.bindAdjustment('simple-fade-animation-time');
   dialog.bindAdjustment('simple-fade-width');
 
-  // Finally, append the settings page to the main stack.
+  // Finally, return the new settings page.
-  const stack = dialog.getBuilder().get_object('main-stack');
+  return dialog.getBuilder().get_object('simple-fade-prefs');
-  stack.add_titled(
+}
-      dialog.getBuilder().get_object(SimpleFade.getNick() + '-prefs'),
-      SimpleFade.getNick(), SimpleFade.getLabel());
-  }
 ```
 
 Once this is in place, you can kill the extension-preferences process and re-open the settings.

prefs.js

@@ -65,10 +65,14 @@ var PreferencesDialog = class PreferencesDialog {
     this.bindSwitch('destroy-dialogs');
 
     // Add all other effect pages.
+    const stack = this._builder.get_object('main-stack');
     ALL_EFFECTS.forEach(Effect => {
       const [minMajor, minMinor] = Effect.getMinShellVersion();
       if (utils.shellVersionIsAtLeast(minMajor, minMinor)) {
-        Effect.initPreferences(this);
+        const page = Effect.getPreferences(this);
+        if (page) {
+          stack.add_titled(page, Effect.getNick(), Effect.getLabel());
+        }
       }
     });
 

src/BrokenGlass.js

@@ -60,7 +60,7 @@ var BrokenGlass = class BrokenGlass {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource('/ui/gtk4/BrokenGlass.ui');
@@ -72,11 +72,8 @@ var BrokenGlass = class BrokenGlass {
     dialog.bindAdjustment('broken-glass-blow-force');
     dialog.bindSwitch('broken-glass-use-pointer');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('broken-glass-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('broken-glass-prefs'), BrokenGlass.getNick(),
-        BrokenGlass.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/EnergizeA.js

@@ -57,7 +57,7 @@ var EnergizeA = class EnergizeA {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource(`/ui/${utils.getGTKString()}/EnergizeA.ui`);
@@ -67,11 +67,8 @@ var EnergizeA = class EnergizeA {
     dialog.bindAdjustment('energize-a-scale');
     dialog.bindColorButton('energize-a-color');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('energize-a-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('energize-a-prefs'), EnergizeA.getNick(),
-        EnergizeA.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/EnergizeB.js

@@ -57,7 +57,7 @@ var EnergizeB = class EnergizeB {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource(`/ui/${utils.getGTKString()}/EnergizeB.ui`);
@@ -67,11 +67,8 @@ var EnergizeB = class EnergizeB {
     dialog.bindAdjustment('energize-b-scale');
     dialog.bindColorButton('energize-b-color');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('energize-b-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('energize-b-prefs'), EnergizeB.getNick(),
-        EnergizeB.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/Fire.js

@@ -61,7 +61,7 @@ var Fire = class Fire {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource(`/ui/${utils.getGTKString()}/Fire.ui`);
@@ -89,10 +89,8 @@ var Fire = class Fire {
     // Initialize the fire-preset dropdown.
     Fire._createFirePresets(dialog);
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('fire-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('fire-prefs'), Fire.getNick(), Fire.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/Matrix.js

@@ -61,7 +61,7 @@ var Matrix = class Matrix {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource('/ui/gtk4/Matrix.ui');
@@ -73,11 +73,8 @@ var Matrix = class Matrix {
     dialog.bindColorButton('matrix-trail-color');
     dialog.bindColorButton('matrix-tip-color');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('matrix-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('matrix-prefs'), Matrix.getNick(),
-        Matrix.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/TRexAttack.js

@@ -59,7 +59,7 @@ var TRexAttack = class TRexAttack {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource('/ui/gtk4/TRexAttack.ui');
@@ -71,11 +71,8 @@ var TRexAttack = class TRexAttack {
     dialog.bindAdjustment('claw-scratch-count');
     dialog.bindAdjustment('claw-scratch-warp');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('trex-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('trex-prefs'), TRexAttack.getNick(),
-        TRexAttack.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/TVEffect.js

@@ -59,7 +59,7 @@ var TVEffect = class TVEffect {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource(`/ui/${utils.getGTKString()}/TVEffect.ui`);
@@ -68,11 +68,8 @@ var TVEffect = class TVEffect {
     dialog.bindAdjustment('tv-animation-time');
     dialog.bindColorButton('tv-effect-color');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('tv-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('tv-prefs'), TVEffect.getNick(),
-        TVEffect.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js

src/Wisps.js

@@ -58,7 +58,7 @@ var Wisps = class Wisps {
   // This is called by the preferences dialog. It loads the settings page for this effect,
   // binds all properties to the settings and appends the page to the main stack of the
   // preferences dialog.
-  static initPreferences(dialog) {
+  static getPreferences(dialog) {
 
     // Add the settings page to the builder.
     dialog.getBuilder().add_from_resource(`/ui/${utils.getGTKString()}/Wisps.ui`);
@@ -68,10 +68,8 @@ var Wisps = class Wisps {
     dialog.bindAdjustment('wisps-scale');
     dialog.bindColorButton('wisps-color');
 
-    // Finally, append the settings page to the main stack.
+    // Finally, return the new settings page.
-    const stack = dialog.getBuilder().get_object('main-stack');
+    return dialog.getBuilder().get_object('wisps-prefs');
-    stack.add_titled(
-        dialog.getBuilder().get_object('wisps-prefs'), Wisps.getNick(), Wisps.getLabel());
   }
 
   // ---------------------------------------------------------------- API for extension.js