Mac global keybindings

chrome/browser/extensions/global_shortcut_listener_mac.mm

+// Copyright (c) 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#include "chrome/browser/extensions/global_shortcut_listener_mac.h"
+
+#include <ApplicationServices/ApplicationServices.h>
+#import <Cocoa/Cocoa.h>
+#include <IOKit/hidsystem/ev_keymap.h>
+
+#import "base/mac/foundation_util.h"
+#include "chrome/browser/extensions/api/commands/command_service.h"
+#include "content/public/browser/browser_thread.h"
+#include "ui/base/accelerators/accelerator.h"
+#include "ui/events/event.h"
+#import "ui/events/keycodes/keyboard_code_conversion_mac.h"
+
+using content::BrowserThread;
+using extensions::GlobalShortcutListenerMac;
+
+namespace {
+
+// The media keys subtype. No official docs found, but widely known.
+// http://lists.apple.com/archives/cocoa-dev/2007/Aug/msg00499.html
+const int kSystemDefinedEventMediaKeysSubtype = 8;
+
+ui::KeyboardCode MediaKeyCodeToKeyboardCode(int key_code) {
+  switch (key_code) {
+    case NX_KEYTYPE_PLAY:
+      return ui::VKEY_MEDIA_PLAY_PAUSE;
+    case NX_KEYTYPE_PREVIOUS:
+    case NX_KEYTYPE_REWIND:
+      return ui::VKEY_MEDIA_PREV_TRACK;
+    case NX_KEYTYPE_NEXT:
+    case NX_KEYTYPE_FAST:
+      return ui::VKEY_MEDIA_NEXT_TRACK;
+  }
+  return ui::VKEY_UNKNOWN;
+}
+
+}  // namespace
+
+namespace extensions {
+
+// static
+GlobalShortcutListener* GlobalShortcutListener::GetInstance() {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+  static GlobalShortcutListenerMac *g_instance =

[Mark Mentovai, 2013/12/11 02:55:02]

This is no longer global, you don’t need the g_ prefix. Just “instance” is fine.

[smus, 2013/12/11 17:52:07]

Done.

+      new GlobalShortcutListenerMac();
+  return g_instance;
+}
+
+GlobalShortcutListenerMac::GlobalShortcutListenerMac()
+    : is_listening_(false),
+      hot_key_id_(0),
+      event_tap_(NULL),
+      event_tap_source_(NULL),
+      event_handler_(NULL) {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+}
+
+GlobalShortcutListenerMac::~GlobalShortcutListenerMac() {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+
+  // By this point, UnregisterAccelerator should have been called for all
+  // keyboard shortcuts.
+  if (event_handler_)
+    StopListening();

[Mark Mentovai, 2013/12/11 02:55:02]

If event_handler_ is true, then hot_key_ids_ will be non-empty, and this will
trigger a DCHECK in StopListening. How do you want this to behave? This code
here contradicts the assertions.

[smus, 2013/12/11 17:52:07]

The comment above:

  // By this point, UnregisterAccelerator should have been called for all
  // keyboard shortcuts.

Suggests that by this point event_handler_ should never be true. But I think
it's worthwhile calling StopListening just in case, for parity with other
platforms' implementations. I've brought it back to use is_listening_ which we
should keep for similar reasons.

+
+  // If media keys are still registered, make sure we stop the tap.
+  if (IsAnyMediaKeyRegistered())
+    StopWatchingMediaKeys();
+}
+
+void GlobalShortcutListenerMac::StartListening() {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+
+  DCHECK(!hot_key_ids_.empty());  // Don't start if no hot key registered.

[Mark Mentovai, 2013/12/11 02:55:02]

It’s not really “don’t start,” it’s “this should never happen and is fatal in a
debug build.”

[smus, 2013/12/11 17:52:07]

I think “this should never happen and is fatal in a debug build" is implied by
the DCHECK. Removed comment.

+  DCHECK(!id_hot_keys_.empty());
+  DCHECK(!is_listening_);
+
+  is_listening_ = true;
+}
+
+void GlobalShortcutListenerMac::StopListening() {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+
+  DCHECK(hot_key_ids_.empty());  // Make sure the set is clean.
+  DCHECK(id_hot_keys_.empty());
+  DCHECK(is_listening_);
+
+  is_listening_ = false;
+}
+
+void GlobalShortcutListenerMac::OnHotKeyEvent(EventHotKeyID hot_key_id) {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+
+  // This hot key should be registered.
+  DCHECK(id_hot_keys_.find(hot_key_id.id) != id_hot_keys_.end());
+  // Look up the accelerator based on this hot key ID.
+  const ui::Accelerator& accelerator = id_hot_keys_[hot_key_id.id];
+  NotifyKeyPressed(accelerator);
+}
+
+bool GlobalShortcutListenerMac::OnMediaKeyEvent(int media_key_code) {
+  CHECK(BrowserThread::CurrentlyOn(BrowserThread::UI));
+  ui::KeyboardCode key_code = MediaKeyCodeToKeyboardCode(media_key_code);
+  // Create an accelerator corresponding to the keyCode.
+  ui::Accelerator accelerator(key_code, 0);
+  // Look for a match with a bound hot_key.
+  if (hot_key_ids_.find(accelerator) != hot_key_ids_.end()) {
+    // If matched, callback to the event handling system.
+    NotifyKeyPressed(accelerator);
+    return true;
+  }
+  return false;
+}
+
+void GlobalShortcutListenerMac::RegisterAccelerator(
+    const ui::Accelerator& accelerator,
+    GlobalShortcutListener::Observer* observer) {
+  if (hot_key_ids_.find(accelerator) != hot_key_ids_.end()) {
+    // The shortcut has already been registered. Some shortcuts, such as
+    // MediaKeys can have multiple targets, all keyed off of the same

[Mark Mentovai, 2013/12/11 02:55:02]

I hadn’t noticed this property before, but now that I’m reading this comment
more closely…

Seems like the desired behavior here is to allow RegisterAccelerator to be
called multiple times with the same accelerator and different observers. True?

If so, what’s supposed to happen if you RegisterAccelerator twice for the same
accelerator with two different observers (A and B), and then
UnregisterAccelerator the accelerator with only one observer (B)?

It would seem to me that the desired behavior under this regime would be to
leave the accelerator hooked up and attached to observer A. But in reality, the
implementation in UnregisterAccelerator seems like it’ll stop listening for this
accelerator altogether, and although A is still hooked up in the base class,
system events for that keystroke will never fire if a hot key, or events will be
dropped in this class if a media key.

If the desired behavior is in fact to only allow one observer to be registered
for an accelerator, then I would think that you’d need to provide some mechanism
(return value?) for this method to signal whether the accelerator was
successfully registered or not. Otherwise, the caller has no way to know whether
it needs to call UnregisterAccelerator. With the existing structure, something
could wind up unregistering someone else’s accelerator or triggering a DCHECK
failure or a crash if that happened.

How’s it supposed to work?

[smus, 2013/12/11 17:52:07]

Looks like I copied this code directly from the other implementations (Win,
X11). So I don't understand how this is supposed to work either. 

Why are media keys the exception? Can't hot keys also be requested by multiple
targets? How does this work in other platforms?

[Finnur, 2013/12/11 18:43:36]

This should work the same way on all platforms: MediaKeys have multiple targets,
other keys do not. Here's why:

Lets assume you have two extensions, A and B, that have two wildly differing
feature sets. A does a FindInPage replacement, the other replaces all images on
the page with cat images. It doesn't make sense to bind the same shortcut (say
Ctrl+F) to both of those features because you'd want them mutually exclusive --
It would be weird for all the images to turn to cats *and* the Find box to open
at the same time. 

For MediaKeys that's a different story because they have special predefined
system functions that are of interest to many extensions. You might have more
than one recipient who wants to listen for say VolumeUp (Example: a music app
and a video player, to name two). Exclusivity doesn't make sense in that
scenario because it would mean you'd have to manually specify who is allowed to
receive the event, and switch as you change apps.

[Finnur, 2013/12/11 19:21:41]

And to clarify...

If a second extension comes in and says "hey, I also want to listen to
MediaStop" it is fine to return early here because we've already setup the
listening framework for MediaStop. There's no need to have two of those. 

The base class keeps track of who wants to get notified about MediaStop and it
is the responsibility of the base class to notify them (See
GlobalShortcutListener::NotifyKeyPressed, which is called from OnHotKeyEvent and
OnMediaKeyEvent above).

+    // accelerator.
+    return;
+  }
+
+  if (CommandService::IsMediaKey(accelerator)) {
+    if (!IsAnyMediaKeyRegistered()) {
+      // If this is the first media key registered, start the event tap.
+      StartWatchingMediaKeys();
+    }
+  } else {
+    // Register hot_key if they are non-media keyboard shortcuts.
+    RegisterHotKey(accelerator, hot_key_id_);
+  }
+
+  // Store the hotkey-ID mappings we will need for lookup later.
+  id_hot_keys_[hot_key_id_] = accelerator;
+  hot_key_ids_[accelerator] = hot_key_id_;
+  ++hot_key_id_;
+  GlobalShortcutListener::RegisterAccelerator(accelerator, observer);
+}
+
+void GlobalShortcutListenerMac::UnregisterAccelerator(
+    const ui::Accelerator& accelerator,
+    GlobalShortcutListener::Observer* observer) {
+  // Ensure this accelerator is registered.
+  DCHECK(hot_key_ids_.find(accelerator) != hot_key_ids_.end());
+
+  // Unregister the hot_key if it's a keyboard shortcut.
+  if (!CommandService::IsMediaKey(accelerator))
+    UnregisterHotKey(accelerator);
+
+  // Remove hot_key from the mappings.
+  HotKeyId id = hot_key_ids_[accelerator];
+  id_hot_keys_.erase(id);
+  hot_key_ids_.erase(accelerator);
+  GlobalShortcutListener::UnregisterAccelerator(accelerator, observer);
+
+  // If we unregistered a media key, and now if no media keys are registered,
+  // stop the media key tap.
+  if (CommandService::IsMediaKey(accelerator) && !IsAnyMediaKeyRegistered()) {
+    StopWatchingMediaKeys();
+  }
+}
+
+void GlobalShortcutListenerMac::RegisterHotKey(
+    const ui::Accelerator& accelerator, HotKeyId hot_key_id) {
+  DVLOG(0) << "RegisterHotKey";
+  EventHotKeyID event_hot_key_id;
+
+  // Signature uniquely identifies the application that owns this hot_key.
+  event_hot_key_id.signature = base::mac::CreatorCodeForApplication();
+  event_hot_key_id.id = hot_key_id;
+
+  // Translate ui::Accelerator modifiers to cmdKey, altKey, etc.
+  int modifiers = 0;
+  modifiers |= (accelerator.IsShiftDown() ? shiftKey : 0);
+  modifiers |= (accelerator.IsCtrlDown() ? controlKey : 0);
+  modifiers |= (accelerator.IsAltDown() ? optionKey : 0);
+  modifiers |= (accelerator.IsCmdDown() ? cmdKey : 0);
+
+  int key_code = ui::MacKeyCodeForWindowsKeyCode(accelerator.key_code(), 0,
+      NULL, NULL);
+
+  // Register the event hot key.
+  EventHotKeyRef hot_key_ref;
+  RegisterEventHotKey(key_code, modifiers, event_hot_key_id,
+      GetApplicationEventTarget(), 0, &hot_key_ref);
+
+  id_hot_key_refs_[hot_key_id] = hot_key_ref;
+
+  // If there is no event handler, install it.
+  if (!event_handler_) {
+    DVLOG(0) << "Installing event handler";
+    EventHandlerUPP hot_key_function = NewEventHandlerUPP(HotKeyHandler);
+    EventTypeSpec event_type;
+    event_type.eventClass = kEventClassKeyboard;
+    event_type.eventKind = kEventHotKeyPressed;
+    InstallApplicationEventHandler(
+        hot_key_function, 1, &event_type, this, &event_handler_);
+  }
+}
+
+void GlobalShortcutListenerMac::UnregisterHotKey(
+    const ui::Accelerator& accelerator) {
+  // Ensure this accelerator is already registered.
+  DCHECK(hot_key_ids_.find(accelerator) != hot_key_ids_.end());
+  // Get the ref corresponding to this accelerator.
+  HotKeyId id = hot_key_ids_[accelerator];
+  EventHotKeyRef ref = id_hot_key_refs_[id];
+  // Unregister the event hot key.
+  UnregisterEventHotKey(ref);
+
+  // Remove the event from the mapping.
+  id_hot_key_refs_.erase(id);
+
+  // If no more hot keys are registered, remove the event handler.

[Mark Mentovai, 2013/12/11 02:55:02]

The comment says “if no more hot keys are registered,” but the code doesn’t seem
to do that. The first UnregisterHotKey will cause any other registered hot keys
to stop responding until a subsequent RegisterHotKey. It doesn’t seem like you
tested this.

[smus, 2013/12/11 17:52:07]

Done.

+  if (event_handler_) {
+    DVLOG(0) << "Removing event handler";
+    RemoveEventHandler(event_handler_);
+    event_handler_ = NULL;
+  }
+}
+
+void GlobalShortcutListenerMac::StartWatchingMediaKeys() {
+  // Make sure there's no existing event tap.
+  DCHECK(event_tap_ == NULL);
+  DCHECK(event_tap_source_ == NULL);
+
+  // Add an event tap to intercept the system defined media key events.
+  event_tap_ = CGEventTapCreate(kCGSessionEventTap,
+      kCGHeadInsertEventTap,
+      kCGEventTapOptionDefault,
+      CGEventMaskBit(NX_SYSDEFINED),
+      EventTapCallback,
+      this);
+  if (event_tap_ == NULL) {
+    LOG(ERROR) << "Error: failed to create event tap.";
+    return;
+  }
+
+  event_tap_source_ = CFMachPortCreateRunLoopSource(kCFAllocatorSystemDefault,
+      event_tap_, 0);
+  if (event_tap_source_ == NULL) {
+    LOG(ERROR) << "Error: failed to create new run loop source.";
+    return;
+  }
+
+  CFRunLoopAddSource(CFRunLoopGetCurrent(), event_tap_source_,
+      kCFRunLoopCommonModes);
+}
+
+void GlobalShortcutListenerMac::StopWatchingMediaKeys() {
+  CFRunLoopRemoveSource(CFRunLoopGetCurrent(), event_tap_source_,
+      kCFRunLoopCommonModes);
+  // Ensure both event tap and source are initialized.
+  DCHECK(event_tap_ != NULL);
+  DCHECK(event_tap_source_ != NULL);
+
+  // Invalidate the event tap.
+  CFMachPortInvalidate(event_tap_);
+  CFRelease(event_tap_);
+  event_tap_ = NULL;
+
+  // Release the event tap source.
+  CFRelease(event_tap_source_);
+  event_tap_source_ = NULL;
+}
+
+bool GlobalShortcutListenerMac::IsAnyMediaKeyRegistered() {
+  // Iterate through registered accelerators, looking for media keys.
+  HotKeyIdMap::iterator iter;
+  for (iter = hot_key_ids_.begin(); iter != hot_key_ids_.end(); ++iter) {
+    if (CommandService::IsMediaKey(iter->first))
+      return true;
+  }
+  return false;
+}
+
+bool GlobalShortcutListenerMac::IsAnyHotKeyRegistered() {

[Mark Mentovai, 2013/12/11 02:55:02]

Who calls this? It seems like you could use this to decide whether to
Start/StopWatchingHotKeys if such methods existed. Did you intend to call this
from UnregisterHotKey? The Start/StopWatchingHotKeys function isn’t a bad idea,
as a nice parallel to Start/StopWatchingMediaKeys.

[smus, 2013/12/11 17:52:07]

Done.

+  HotKeyIdMap::iterator iter;
+  for (iter = hot_key_ids_.begin(); iter != hot_key_ids_.end(); ++iter) {
+    if (!CommandService::IsMediaKey(iter->first))
+      return true;
+  }
+  return false;
+}
+
+// Processed events should propagate if they aren't handled by any listeners.
+// For events that don't matter, this handler should return as quickly as
+// possible.
+// Returning event causes the event to propagate to other applications.
+// Returning NULL prevents the event from propagating.
+// static
+CGEventRef GlobalShortcutListenerMac::EventTapCallback(
+    CGEventTapProxy proxy, CGEventType type, CGEventRef event, void* refcon) {
+  GlobalShortcutListenerMac* shortcut_listener =
+      static_cast<GlobalShortcutListenerMac*>(refcon);
+
+  // Handle the timeout case by re-enabling the tap.
+  if (type == kCGEventTapDisabledByTimeout) {
+    CGEventTapEnable(shortcut_listener->event_tap_, TRUE);
+    return event;
+  }
+
+  // Convert the CGEvent to an NSEvent for access to the data1 field.
+  NSEvent* ns_event = [NSEvent eventWithCGEvent:event];
+  if (ns_event == nil) {
+    return event;
+  }
+
+  // Ignore events that are not system defined media keys.
+  if (type != NX_SYSDEFINED ||
+      [ns_event type] != NSSystemDefined ||
+      [ns_event subtype] != kSystemDefinedEventMediaKeysSubtype) {
+    return event;
+  }
+
+  NSInteger data1 = [ns_event data1];
+  // Ignore media keys that aren't previous, next and play/pause.
+  // Magical constants are from http://weblog.rogueamoeba.com/2007/09/29/
+  int key_code = (data1 & 0xFFFF0000) >> 16;
+  if (key_code != NX_KEYTYPE_PLAY && key_code != NX_KEYTYPE_NEXT &&
+      key_code != NX_KEYTYPE_PREVIOUS && key_code != NX_KEYTYPE_FAST &&
+      key_code != NX_KEYTYPE_REWIND) {
+    return event;
+  }
+
+  int key_flags = data1 & 0x0000FFFF;
+  bool is_key_pressed = ((key_flags & 0xFF00) >> 8) == 0xA;
+
+  // If the key wasn't pressed (eg. was released), ignore this event.
+  if (!is_key_pressed)
+    return event;
+
+  // Now we have a media key that we care about. Send it to the caller.
+  bool was_handled = shortcut_listener->OnMediaKeyEvent(key_code);
+
+  // Prevent event from proagating to other apps if handled by Chrome.
+  if (was_handled)
+    return NULL;
+
+  // By default, pass the event through.
+  return event;
+}
+
+// static
+OSStatus GlobalShortcutListenerMac::HotKeyHandler(
+    EventHandlerCallRef next_handler, EventRef event, void* user_data) {
+  // Extract the hotkey from the event.
+  EventHotKeyID hot_key_id;
+  OSStatus result = GetEventParameter(event, kEventParamDirectObject,
+      typeEventHotKeyID, NULL, sizeof(hot_key_id), NULL, &hot_key_id);
+  if (result != noErr)
+    return result;
+
+  GlobalShortcutListenerMac* shortcut_listener =
+      static_cast<GlobalShortcutListenerMac*>(user_data);
+  shortcut_listener->OnHotKeyEvent(hot_key_id);
+  return noErr;
+}
+
+
+}  // namespace extensions