main: Introduce global workspaces adjustment

And a way to derive "sub"-adjustments from the main one.

The main and private StAdjustment properly represents
workspaces, and has all relevant properties (lower, upper,
and value) set by the workspace manager.

The main adjustment is not bound to any particular actor,
which means we cannot call the 'ease' method directly.

Consumers of this API should create adjustments using
Main.createWorkspacesAdjustment(), and this new adjustment
is bound to the actor that the consumer passed. Consumers
must not change any property of the derived adjustment other
than the 'value' property.

The 'value' property is synchronized between all adjustments
created, which guarantees that all elements that represent
workspaces can have a shared and up-to-date understanding of
where in the workspace layout we are.

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/2881>

js/ui/main.js

@@ -97,6 +97,7 @@ let _cssStylesheet = null;
 let _themeResource = null;
 let _oskResource = null;
 let _iconResource = null;
+let _workspacesAdjustment = null;
 
 Gio._promisify(Gio.File.prototype, 'delete_async');
 Gio._promisify(Gio.File.prototype, 'touch_async');
@@ -191,6 +192,7 @@ async function _initializeUI() {
     _loadIcons();
     _loadOskLayouts();
     _loadDefaultStylesheet();
+    _loadWorkspacesAdjustment();
 
     new AnimationsSettings();
 
@@ -443,6 +445,62 @@ function _loadDefaultStylesheet() {
     loadTheme();
 }
 
+function _loadWorkspacesAdjustment() {
+    const {workspaceManager} = global;
+    const activeWorkspaceIndex = workspaceManager.get_active_workspace_index();
+
+    _workspacesAdjustment = new St.Adjustment({
+        value: activeWorkspaceIndex,
+        lower: 0,
+        page_increment: 1,
+        page_size: 1,
+        step_increment: 0,
+        upper: workspaceManager.n_workspaces,
+    });
+
+    workspaceManager.bind_property('n-workspaces',
+        _workspacesAdjustment, 'upper',
+        GObject.BindingFlags.SYNC_CREATE);
+
+    _workspacesAdjustment.connect('notify::upper', () => {
+        const newActiveIndex = workspaceManager.get_active_workspace_index();
+
+        // A workspace might have been inserted or removed before the active
+        // one, causing the adjustment to go out of sync, so update the value
+        _workspacesAdjustment.remove_transition('value');
+        _workspacesAdjustment.value = newActiveIndex;
+    });
+}
+
+/**
+ * Creates an adjustment that has its lower, upper, and value
+ * properties set for the number of available workspaces. Consumers
+ * of the returned adjustment must only change the 'value' property,
+ * and only that.
+ *
+ * @param {Clutter.Actor} actor
+ *
+ * @returns {St.Adjustment} - an adjustment representing the
+ * current workspaces layout
+ */
+export function createWorkspacesAdjustment(actor) {
+    const adjustment = new St.Adjustment({actor});
+
+    const properties = [
+        ['lower', GObject.BindingFlags.SYNC_CREATE],
+        ['page-increment', GObject.BindingFlags.SYNC_CREATE],
+        ['page-size', GObject.BindingFlags.SYNC_CREATE],
+        ['step-increment', GObject.BindingFlags.SYNC_CREATE],
+        ['upper', GObject.BindingFlags.SYNC_CREATE],
+        ['value', GObject.BindingFlags.SYNC_CREATE | GObject.BindingFlags.BIDIRECTIONAL],
+    ];
+
+    for (const [propName, flags] of properties)
+        _workspacesAdjustment.bind_property(propName, adjustment, propName, flags);
+
+    return adjustment;
+}
+
 /**
  * Get the theme CSS file that the shell will load
  *