GUACAMOLE-2207: Add support for CMD+Click.

sschiffli · sschiffli · commit 43e62147ea87 · 2026-01-30T09:44:14.000-08:00
diff --git a/guacamole-common-js/src/main/webapp/modules/Keyboard.js b/guacamole-common-js/src/main/webapp/modules/Keyboard.js
@@ -285,8 +285,10 @@ Guacamole.Keyboard = function Keyboard(element) {
             this.keysym = keysym_from_key_identifier(this.keyIdentifier, this.location, this.modifiers.shift);
 
         // If a key is pressed while meta is held down, the keyup will
-        // never be sent in Chrome (bug #108404)
-        if (this.modifiers.meta && this.keysym !== 0xFFE7 && this.keysym !== 0xFFE8)
+        // never be sent in Chrome (bug #108404). Modifier keys are excluded
+        // from this workaround as they have reliable keyup events and need
+        // to be held down simultaneously with Meta.
+        if (this.modifiers.meta && !isModifierKey(this.keysym))
             this.keyupReliable = false;
 
         // We cannot rely on receiving keyup for Caps Lock on certain platforms
@@ -578,6 +580,37 @@ Guacamole.Keyboard = function Keyboard(element) {
         "ZenkakuHankaku": [0xFF2A]
     };
 
+    /**
+     * All modifier key keysyms, grouped by modifier type.
+     *
+     * @private
+     * @type {!Object.<string, number[]>}
+     */
+    var modifierKeysymsByType = {
+        shift: [0xFFE1, 0xFFE2],           // Left shift, Right shift
+        ctrl:  [0xFFE3, 0xFFE4],           // Left ctrl, Right ctrl
+        alt:   [0xFFE9, 0xFFEA, 0xFE03],   // Left alt, Right alt, AltGr
+        meta:  [0xFFE7, 0xFFE8],           // Left meta, Right meta
+        hyper: [0xFFEB, 0xFFEC]            // Left super/hyper, Right super/hyper
+    };
+
+    /**
+     * All modifier key keysyms for quick lookup.
+     *
+     * @private
+     * @type {!Object.<number, boolean>}
+     */
+    var modifierKeysyms = (function() {
+        var lookup = {};
+        for (var modifier in modifierKeysymsByType) {
+            var keysyms = modifierKeysymsByType[modifier];
+            for (var i = 0; i < keysyms.length; i++) {
+                lookup[keysyms[i]] = true;
+            }
+        }
+        return lookup;
+    })();
+
     /**
      * All keysyms which should not repeat when held down.
      *
@@ -706,6 +739,34 @@ Guacamole.Keyboard = function Keyboard(element) {
 
     };
 
+    /**
+     * Returns true if the given keysym corresponds to a Meta key (left or
+     * right Meta/Command/Windows key).
+     *
+     * @param {!number} keysym
+     *     The keysym to check.
+     *
+     * @returns {!boolean}
+     *     true if the given keysym corresponds to a Meta key, false otherwise.
+     */
+    var isMetaKey = function isMetaKey(keysym) {
+        return modifierKeysymsByType.meta.indexOf(keysym) !== -1;
+    };
+
+    /**
+     * Returns true if the given keysym corresponds to a modifier key
+     * (Shift, Ctrl, Alt, Meta, Hyper, AltGr).
+     *
+     * @param {!number} keysym
+     *     The keysym to check.
+     *
+     * @returns {!boolean}
+     *     true if the given keysym corresponds to a modifier key, false otherwise.
+     */
+    var isModifierKey = function isModifierKey(keysym) {
+        return modifierKeysyms[keysym] === true;
+    };
+
     function keysym_from_key_identifier(identifier, location, shifted) {
 
         if (!identifier)
@@ -926,6 +987,39 @@ Guacamole.Keyboard = function Keyboard(element) {
 
     };
 
+    /**
+     * Handles a mouse event to resolve deferred Meta key events. When a Meta
+     * key is pressed, it is deferred to determine if it's being used as a
+     * modifier or as a standalone key. A mouse click with Meta held provides
+     * the context needed to resolve this, enabling Cmd+Click functionality.
+     *
+     * @param {Guacamole.Mouse.Event} mouseEvent
+     *     The mouse event that occurred.
+     */
+    this.handleMouseEvent = function(mouseEvent) {
+
+        // Only process mouse events that have meta modifier pressed
+        if (!mouseEvent.modifiers.meta)
+            return;
+
+        // Check if there's a pending Meta key waiting for context
+        var hasPendingMeta = eventLog.length > 0 &&
+                             eventLog[0] instanceof KeydownEvent &&
+                             isMetaKey(eventLog[0].keysym);
+
+        // Only add mouse event if there's a pending Meta key
+        if (hasPendingMeta) {
+            // Push mouse event onto the event log to provide context for the
+            // deferred Meta key. The mouse event will be silently dropped when
+            // processed as it's not a KeyEvent type.
+            eventLog.push(mouseEvent);
+
+            // Process the event log, which will now resolve the deferred Meta
+            // key using the mouse event's modifier state as context
+            interpret_events();
+        }
+    };
+
     /**
      * Resynchronizes the remote state of the given modifier with its
      * corresponding local modifier state, as dictated by
@@ -1004,36 +1098,12 @@ Guacamole.Keyboard = function Keyboard(element) {
      */
     var syncModifierStates = function syncModifierStates(keyEvent) {
 
-        // Resync state of alt
-        updateModifierState('alt', [
-            0xFFE9, // Left alt
-            0xFFEA, // Right alt
-            0xFE03  // AltGr
-        ], keyEvent);
-
-        // Resync state of shift
-        updateModifierState('shift', [
-            0xFFE1, // Left shift
-            0xFFE2  // Right shift
-        ], keyEvent);
-
-        // Resync state of ctrl
-        updateModifierState('ctrl', [
-            0xFFE3, // Left ctrl
-            0xFFE4  // Right ctrl
-        ], keyEvent);
-
-        // Resync state of meta
-        updateModifierState('meta', [
-            0xFFE7, // Left meta
-            0xFFE8  // Right meta
-        ], keyEvent);
-
-        // Resync state of hyper
-        updateModifierState('hyper', [
-            0xFFEB, // Left super/hyper
-            0xFFEC  // Right super/hyper
-        ], keyEvent);
+        // Resync state of all modifiers
+        updateModifierState('alt', modifierKeysymsByType.alt, keyEvent);
+        updateModifierState('shift', modifierKeysymsByType.shift, keyEvent);
+        updateModifierState('ctrl', modifierKeysymsByType.ctrl, keyEvent);
+        updateModifierState('meta', modifierKeysymsByType.meta, keyEvent);
+        updateModifierState('hyper', modifierKeysymsByType.hyper, keyEvent);
 
         // Update state
         guac_keyboard.modifiers = keyEvent.modifiers;
@@ -1152,7 +1222,7 @@ Guacamole.Keyboard = function Keyboard(element) {
             // Defer handling of Meta until it is known to be functioning as a
             // modifier (it may otherwise actually be an alternative method for
             // pressing a single key, such as Meta+Left for Home on ChromeOS)
-            if (first.keysym === 0xFFE7 || first.keysym === 0xFFE8) {
+            if (isMetaKey(first.keysym)) {
 
                 // Defer handling until further events exist to provide context
                 if (eventLog.length === 1)
diff --git a/guacamole-common-js/src/main/webapp/modules/Mouse.js b/guacamole-common-js/src/main/webapp/modules/Mouse.js
@@ -510,6 +510,81 @@ Guacamole.Mouse.State.Buttons = {
 
 };
 
+/**
+ * The state of all supported keyboard modifiers. This is the same structure
+ * used for keyboard modifier state tracking.
+ * @constructor
+ */
+Guacamole.Mouse.ModifierState = function() {
+
+    /**
+     * Whether shift is currently pressed.
+     *
+     * @type {!boolean}
+     */
+    this.shift = false;
+
+    /**
+     * Whether ctrl is currently pressed.
+     *
+     * @type {!boolean}
+     */
+    this.ctrl = false;
+
+    /**
+     * Whether alt is currently pressed.
+     *
+     * @type {!boolean}
+     */
+    this.alt = false;
+
+    /**
+     * Whether meta (apple key) is currently pressed.
+     *
+     * @type {!boolean}
+     */
+    this.meta = false;
+
+    /**
+     * Whether hyper (windows key) is currently pressed.
+     *
+     * @type {!boolean}
+     */
+    this.hyper = false;
+
+};
+
+/**
+ * Returns the modifier state applicable to the mouse event given.
+ *
+ * @param {!MouseEvent} e
+ *     The mouse event to read.
+ *
+ * @returns {!Guacamole.Mouse.ModifierState}
+ *     The current state of keyboard modifiers.
+ */
+Guacamole.Mouse.ModifierState.fromMouseEvent = function(e) {
+
+    var state = new Guacamole.Mouse.ModifierState();
+
+    // Assign states from old flags
+    state.shift = e.shiftKey;
+    state.ctrl  = e.ctrlKey;
+    state.alt   = e.altKey;
+    state.meta  = e.metaKey;
+
+    // Use DOM3 getModifierState() for others
+    if (e.getModifierState) {
+        state.hyper = e.getModifierState("OS")
+                   || e.getModifierState("Super")
+                   || e.getModifierState("Hyper")
+                   || e.getModifierState("Win");
+    }
+
+    return state;
+
+};
+
 /**
  * Base event type for all mouse events. The mouse producing the event may be
  * the user's local mouse (as with {@link Guacamole.Mouse}) or an emulated
@@ -547,6 +622,16 @@ Guacamole.Mouse.Event = function MouseEvent(type, state, events) {
      */
     this.state = state;
 
+    /**
+     * The state of all modifier keys at the time this event was received.
+     * If the original DOM event is not a MouseEvent or modifier state is
+     * otherwise unavailable, the state of all modifiers will be false.
+     *
+     * @type {!Guacamole.Mouse.ModifierState}
+     */
+    var firstEvent = Array.isArray(events) ? events[0] : events;
+    this.modifiers = firstEvent ? Guacamole.Mouse.ModifierState.fromMouseEvent(firstEvent) : new Guacamole.Mouse.ModifierState();
+
     /**
      * @inheritdoc
      */
diff --git a/guacamole/src/main/frontend/src/app/client/directives/guacClient.js b/guacamole/src/main/frontend/src/app/client/directives/guacClient.js
@@ -243,6 +243,11 @@ angular.module('client').directive('guacClient', [function guacClient() {
             if (!client || !display)
                 return;
 
+            // Broadcast mousedown event before sending to allow keyboard to resolve
+            // deferred modifier keys (especially CMD+click)
+            if (event.type === 'mousedown')
+                $rootScope.$broadcast('guacBeforeClientMouseDown', event, client);
+
             event.stopPropagation();
             event.preventDefault();
 
@@ -303,6 +308,11 @@ angular.module('client').directive('guacClient', [function guacClient() {
             if (!client || !display)
                 return;
 
+            // Broadcast mousedown event before sending to allow keyboard to resolve
+            // deferred modifier keys (especially CMD+click)
+            if (event.type === 'mousedown')
+                $rootScope.$broadcast('guacBeforeClientMouseDown', event, client);
+
             event.stopPropagation();
             event.preventDefault();
 
diff --git a/guacamole/src/main/frontend/src/app/index/controllers/indexController.js b/guacamole/src/main/frontend/src/app/index/controllers/indexController.js
@@ -183,6 +183,11 @@ angular.module('index').controller('indexController', ['$scope', '$injector',
     var keyboard = new Guacamole.Keyboard($document[0]);
     keyboard.listenTo(sink.getElement());
 
+    // Resolve deferred Meta key events on mouse click to enable Cmd+Click
+    $scope.$on('guacBeforeClientMouseDown', function(event, mouseEvent, client) {
+        keyboard.handleMouseEvent(mouseEvent);
+    });
+
     // Broadcast keydown events
     keyboard.onkeydown = function onkeydown(keysym) {
 
