keybindings: Clean up captured-event handler, use ActionModes for

mtwebster · mtwebster · commit 1568ae0827b3 · 2026-02-27T11:52:09.000-05:00
built-in keybindings.

This gets rid of a big mess in Main._stageEventHandler and makes
keybinding handling more consistent.

- Add setBuiltinHandler in KeybindingManager to replace muffin's
  Meta.keybindings_set_custom_handler() and allow specifying an
  ActionMode.
- Update windowManager.js to use the new method.
- Update workspace keybinding handling to incorporate special
  behavior during POPUP modes.
- Update expo to handle special key handling behavior while active.
- Remove unused LOGIN action mode, add EXPO.
- Add ActionMode enum to docs.
diff --git a/docs/reference/cinnamon/cinnamon-docs.sgml b/docs/reference/cinnamon/cinnamon-docs.sgml
@@ -40,6 +40,7 @@
     <xi:include href="xml/cinnamon-global.xml"/>
     <xi:include href="xml/cinnamon-wm.xml"/>
     <xi:include href="xml/cinnamon-util.xml"/>
+    <xi:include href="xml/cinnamon-action-mode.xml"/>
   </chapter>
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
diff --git a/js/ui/expo.js b/js/ui/expo.js
@@ -173,6 +173,10 @@ Expo.prototype = {
                         }
                         return true;
                     }
+                    if (symbol === Clutter.KEY_Super_L || symbol === Clutter.KEY_Super_R) {
+                        this.hide();
+                        return true;
+                    }
                 }
                 return false;
             }));
@@ -267,7 +271,7 @@ Expo.prototype = {
             return;
         this.beforeShow();
         // Do this manually instead of using _syncInputMode, to handle failure
-        if (!Main.pushModal(this._group, undefined, undefined, Cinnamon.ActionMode.OVERVIEW))
+        if (!Main.pushModal(this._group, undefined, undefined, Cinnamon.ActionMode.EXPO))
             return;
         this._modal = true;
         this._animateVisible();
@@ -389,7 +393,7 @@ Expo.prototype = {
 
         if (this._shown) {
             if (!this._modal) {
-                if (Main.pushModal(this._group, undefined, undefined, Cinnamon.ActionMode.OVERVIEW))
+                if (Main.pushModal(this._group, undefined, undefined, Cinnamon.ActionMode.EXPO))
                     this._modal = true;
                 else
                     this.hide();
diff --git a/js/ui/keybindings.js b/js/ui/keybindings.js
@@ -426,11 +426,32 @@ KeybindingManager.prototype = {
         this._proxy.HandleKeybindingRemote(action);
     },
 
+    _onBuiltinKeyPressed: function(display, window, binding, actionId) {
+        let entry = this.bindings.get(actionId);
+
+        if (entry === undefined || Main._shouldFilterKeybinding(entry))
+            return;
+
+        entry.callback(display, window, binding);
+    },
+
+    setBuiltinHandler: function(name, actionId, callback, allowedModes=Cinnamon.ActionMode.NORMAL) {
+        Meta.keybindings_set_custom_handler(name,
+            (display, window, binding) => this._onBuiltinKeyPressed(display, window, binding, actionId)
+        );
+
+        this.bindings.set(actionId, {
+            name: name,
+            bindings: [],
+            callback: callback,
+            allowedModes: allowedModes
+        });
+    },
+
     invoke_keybinding_action_by_id: function(id) {
-        const binding = this.bindings.get(id);
-        if (binding !== undefined) {
-            // log(`invoke_keybinding_action_by_id: ${binding.name}, bindings: ${binding.bindings} - action id: ${id}`);
-            binding.callback(null, null, null);
+        const entry = this.bindings.get(id);
+        if (entry !== undefined) {
+            entry.callback(null, null, { get_name: () => entry.name });
         }
     }
 };
diff --git a/js/ui/main.js b/js/ui/main.js
@@ -263,11 +263,12 @@ function _initUserSession() {
 
     systrayManager = new Systray.SystrayManager();
 
-    Meta.keybindings_set_custom_handler('panel-run-dialog', function() {
-        if (!lockdownSettings.get_boolean('disable-command-line')) {
-            getRunDialog().open();
-        }
-    });
+    keybindingManager.setBuiltinHandler('panel-run-dialog', Meta.KeyBindingAction.PANEL_RUN_DIALOG,
+        function() {
+            if (!lockdownSettings.get_boolean('disable-command-line')) {
+                getRunDialog().open();
+            }
+        }, Cinnamon.ActionMode.NORMAL);
 }
 
 function _loadOskLayouts() {
@@ -1251,71 +1252,27 @@ function _shouldFilterKeybinding(entry) {
 function _stageEventHandler(actor, event) {
     if (modalCount == 0)
         return false;
-    // log("Stage event handler........." + event.type() + "..." + event.get_source() + "...flags: "+event.get_flags());
 
     if (event.type() != Clutter.EventType.KEY_PRESS) {
         if(!popup_rendering_actor || event.type() != Clutter.EventType.BUTTON_RELEASE)
             return false;
         return (event.get_source() && popup_rendering_actor.contains(event.get_source()));
     }
 
-    let symbol = event.get_key_symbol();
     let keyCode = event.get_key_code();
     let modifierState = Cinnamon.get_event_state(event);
 
     let action = global.display.get_keybinding_action(keyCode, modifierState);
     if (!(event.get_source() instanceof Clutter.Text && (event.get_flags() & Clutter.EventFlags.INPUT_METHOD))) {
-        // This relies on the fact that Clutter.ModifierType is the same as Gdk.ModifierType
         if (action > 0) {
-            // Check if this keybinding should be filtered based on ActionMode
             let entry = keybindingManager.getBindingById(action);
             if (!_shouldFilterKeybinding(entry)) {
                 keybindingManager.invoke_keybinding_action_by_id(action);
+                return true;
             }
         }
     }
 
-    // Other bindings are only available when the overview is up and no modal dialog is present
-    if (((!overview.visible && !expo.visible) || modalCount > 1))
-        return false;
-
-    // This isn't a Meta.KeyBindingAction yet
-    if (symbol === Clutter.KEY_Super_L || symbol === Clutter.KEY_Super_R) {
-        if (expo.visible) {
-            expo.hide();
-            return true;
-        }
-    }
-
-    if (action == Meta.KeyBindingAction.SWITCH_PANELS) {
-        //Used to call the ctrlalttabmanager in Gnome Shell
-        return true;
-    }
-
-    switch (action) {
-        // left/right would effectively act as synonyms for up/down if we enabled them;
-        // but that could be considered confusing; we also disable them in the main view.
-        case Meta.KeyBindingAction.WORKSPACE_LEFT:
-            wm.actionMoveWorkspaceLeft();
-            return true;
-        case Meta.KeyBindingAction.WORKSPACE_RIGHT:
-            wm.actionMoveWorkspaceRight();
-            return true;
-        case Meta.KeyBindingAction.WORKSPACE_UP:
-            overview.hide();
-            expo.hide();
-            return true;
-        case Meta.KeyBindingAction.WORKSPACE_DOWN:
-            overview.hide();
-            expo.hide();
-            return true;
-        case Meta.KeyBindingAction.PANEL_RUN_DIALOG:
-            if (!lockdownSettings.get_boolean('disable-command-line')) {
-                getRunDialog().open();
-            }
-            return true;
-    }
-
     return false;
 }
 
diff --git a/js/ui/screenRecorder.js b/js/ui/screenRecorder.js
@@ -11,7 +11,8 @@ var ScreenRecorder = class ScreenRecorder {
         this.recorder = null;
         this.recorderSettings = new Gio.Settings({ schema_id: 'org.cinnamon.recorder' });
 
-        Meta.keybindings_set_custom_handler('toggle-recording', () => this.toggle_recording());
+        Main.keybindingManager.setBuiltinHandler('toggle-recording', Meta.KeyBindingAction.TOGGLE_RECORDING,
+            () => this.toggle_recording(), Cinnamon.ActionMode.NORMAL);
     }
 
     get recording() {
diff --git a/js/ui/windowManager.js b/js/ui/windowManager.js
@@ -357,19 +357,36 @@ var WindowManager = class WindowManager {
         this._cinnamonwm.connect('filter-keybinding', this._filterKeybinding.bind(this));
         global.window_manager.connect('switch-workspace', (c, f, t, d) => this._switchWorkspace(c, f, t, d));
 
-        Meta.keybindings_set_custom_handler('move-to-workspace-left', (d, w, b) => this._moveWindowToWorkspaceLeft(d, w, b));
-        Meta.keybindings_set_custom_handler('move-to-workspace-right', (d, w, b) => this._moveWindowToWorkspaceRight(d, w, b));
-
-        Meta.keybindings_set_custom_handler('switch-to-workspace-left', (d, w, b) => this._showWorkspaceSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-to-workspace-right', (d, w, b) => this._showWorkspaceSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-to-workspace-up', (d, w, b) => this._showWorkspaceSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-to-workspace-down', (d, w, b) => this._showWorkspaceSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-windows', (d, w, b) => this._startAppSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-group', (d, w, b) => this._startAppSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-windows-backward', (d, w, b) => this._startAppSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-group-backward', (d, w, b) => this._startAppSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-panels', (d, w, b) => this._startAppSwitcher(d, w, b));
-        Meta.keybindings_set_custom_handler('switch-panels-backward', (d, w, b) => this._startAppSwitcher(d, w, b));
+        let kbm = Main.keybindingManager;
+        let WORKSPACE_MODES = Cinnamon.ActionMode.NORMAL |
+                              Cinnamon.ActionMode.OVERVIEW |
+                              Cinnamon.ActionMode.EXPO;
+
+        kbm.setBuiltinHandler('move-to-workspace-left', Meta.KeyBindingAction.MOVE_TO_WORKSPACE_LEFT,
+            (d, w, b) => this._moveWindowToWorkspaceLeft(d, w, b), Cinnamon.ActionMode.NORMAL);
+        kbm.setBuiltinHandler('move-to-workspace-right', Meta.KeyBindingAction.MOVE_TO_WORKSPACE_RIGHT,
+            (d, w, b) => this._moveWindowToWorkspaceRight(d, w, b), Cinnamon.ActionMode.NORMAL);
+
+        kbm.setBuiltinHandler('switch-to-workspace-left', Meta.KeyBindingAction.WORKSPACE_LEFT,
+            (d, w, b) => this._showWorkspaceSwitcher(d, w, b), WORKSPACE_MODES);
+        kbm.setBuiltinHandler('switch-to-workspace-right', Meta.KeyBindingAction.WORKSPACE_RIGHT,
+            (d, w, b) => this._showWorkspaceSwitcher(d, w, b), WORKSPACE_MODES);
+        kbm.setBuiltinHandler('switch-to-workspace-up', Meta.KeyBindingAction.WORKSPACE_UP,
+            (d, w, b) => this._showWorkspaceSwitcher(d, w, b), WORKSPACE_MODES);
+        kbm.setBuiltinHandler('switch-to-workspace-down', Meta.KeyBindingAction.WORKSPACE_DOWN,
+            (d, w, b) => this._showWorkspaceSwitcher(d, w, b), WORKSPACE_MODES);
+        kbm.setBuiltinHandler('switch-windows', Meta.KeyBindingAction.SWITCH_WINDOWS,
+            (d, w, b) => this._startAppSwitcher(d, w, b), Cinnamon.ActionMode.NORMAL);
+        kbm.setBuiltinHandler('switch-group', Meta.KeyBindingAction.SWITCH_GROUP,
+            (d, w, b) => this._startAppSwitcher(d, w, b), Cinnamon.ActionMode.NORMAL);
+        kbm.setBuiltinHandler('switch-windows-backward', Meta.KeyBindingAction.SWITCH_WINDOWS_BACKWARD,
+            (d, w, b) => this._startAppSwitcher(d, w, b), Cinnamon.ActionMode.NORMAL);
+        kbm.setBuiltinHandler('switch-group-backward', Meta.KeyBindingAction.SWITCH_GROUP_BACKWARD,
+            (d, w, b) => this._startAppSwitcher(d, w, b), Cinnamon.ActionMode.NORMAL);
+        kbm.setBuiltinHandler('switch-panels', Meta.KeyBindingAction.SWITCH_PANELS,
+            (d, w, b) => this._startAppSwitcher(d, w, b), Cinnamon.ActionMode.NORMAL);
+        kbm.setBuiltinHandler('switch-panels-backward', Meta.KeyBindingAction.SWITCH_PANELS_BACKWARD,
+            (d, w, b) => this._startAppSwitcher(d, w, b), Cinnamon.ActionMode.NORMAL);
 
         global.display.connect('show-resize-popup', this._showResizePopup.bind(this));
         this._cinnamonwm.connect('create-close-dialog', this._createCloseDialog.bind(this));
@@ -835,15 +852,9 @@ var WindowManager = class WindowManager {
     }
 
     _filterKeybinding(shellwm, binding) {
-        // Builtin keybindings (defined by Muffin) work in NORMAL mode by default
-        if (Main.actionMode == Cinnamon.ActionMode.NORMAL && binding.is_builtin())
-            return false;
-
-        // Look up the binding in our keybinding manager
         let bindingName = binding.get_name();
-        let [action_id, entry] = Main.keybindingManager._lookupEntry(bindingName);
+        let [, entry] = Main.keybindingManager._lookupEntry(bindingName);
 
-        // Use the common filtering logic from main.js
         return Main._shouldFilterKeybinding(entry);
     }
 
@@ -1382,12 +1393,23 @@ var WindowManager = class WindowManager {
 
     _showWorkspaceSwitcher(display, window, binding) {
         let bindingName = binding.get_name();
+
         if (bindingName === 'switch-to-workspace-up') {
-            Main.expo.toggle();
+            if (Main.overview.visible || Main.expo.visible) {
+                Main.overview.hide();
+                Main.expo.hide();
+            } else {
+                Main.expo.toggle();
+            }
             return;
         }
         if (bindingName === 'switch-to-workspace-down') {
-            Main.overview.toggle();
+            if (Main.overview.visible || Main.expo.visible) {
+                Main.overview.hide();
+                Main.expo.hide();
+            } else {
+                Main.overview.toggle();
+            }
             return;
         }
 
diff --git a/src/cinnamon-action-mode.h b/src/cinnamon-action-mode.h
@@ -14,6 +14,7 @@
  *     dialog (e.g. authentication or session dialogs) is open
  * @CINNAMON_ACTION_MODE_LOOKING_GLASS: allow action in looking glass
  * @CINNAMON_ACTION_MODE_POPUP: allow action while a shell menu is open
+ * @CINNAMON_ACTION_MODE_EXPO: allow action while the expo is active
  * @CINNAMON_ACTION_MODE_ALL: always allow action
  *
  * Controls in which Cinnamon states an action (like keybindings and gestures)
@@ -23,9 +24,9 @@ typedef enum {
   CINNAMON_ACTION_MODE_NONE          = 0,
   CINNAMON_ACTION_MODE_NORMAL        = 1 << 0,
   CINNAMON_ACTION_MODE_OVERVIEW      = 1 << 1,
-  CINNAMON_ACTION_MODE_LOCK_SCREEN   = 1 << 2,
-  CINNAMON_ACTION_MODE_UNLOCK_SCREEN = 1 << 3,
-  CINNAMON_ACTION_MODE_LOGIN_SCREEN  = 1 << 4,
+  CINNAMON_ACTION_MODE_EXPO          = 1 << 2,
+  CINNAMON_ACTION_MODE_LOCK_SCREEN   = 1 << 3,
+  CINNAMON_ACTION_MODE_UNLOCK_SCREEN = 1 << 4,
   CINNAMON_ACTION_MODE_SYSTEM_MODAL  = 1 << 5,
   CINNAMON_ACTION_MODE_LOOKING_GLASS = 1 << 6,
   CINNAMON_ACTION_MODE_POPUP         = 1 << 7,

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,8 @@ var ScreenRecorder = class ScreenRecorder {`
`11`	`11`	`this.recorder = null;`
`12`	`12`	`this.recorderSettings = new Gio.Settings({ schema_id: 'org.cinnamon.recorder' });`
`13`	`13`
`14`		`- Meta.keybindings_set_custom_handler('toggle-recording', () => this.toggle_recording());`
	`14`	`+ Main.keybindingManager.setBuiltinHandler('toggle-recording', Meta.KeyBindingAction.TOGGLE_RECORDING,`
	`15`	`+ () => this.toggle_recording(), Cinnamon.ActionMode.NORMAL);`
`15`	`16`	`}`
`16`	`17`
`17`	`18`	`get recording() {`