DO NOT COMMIT: [Mac] Refactor keyboard shortcut handling so it can be reused in Views.

ui/base/cocoa/command_dispatcher.h

+// Copyright 2015 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.
+
+#ifndef UI_BASE_COCOA_COMMAND_DISPATCHER_H_
+#define UI_BASE_COCOA_COMMAND_DISPATCHER_H_
+
+#import <Cocoa/Cocoa.h>
+
+#import "base/mac/scoped_nsobject.h"
+
+@protocol CommandDispatcherDelegate;
+@protocol CommandDispatchingWindow;
+@protocol UserInterfaceItemCommandHandler;
+
+// CommandDispatcher guides the processing of key events to ensure key commands
+// are executed in the appropriate order. In particular, it allows a first
+// responder implementing CommandDispatcherTarget to handle an event
+// asynchronously and return unhandled events via -redispatchKeyEvent. An
+// NSWindow can use CommandDispatcher by implementing CommandDispatchingWindow
+// and overriding -[NSWindow performKeyEquivalent:] and -[NSWindow sendEvent:]
+// to call the respective CommandDispatcher methods.
+@interface CommandDispatcher : NSObject
+
+@property(assign, nonatomic) id<CommandDispatcherDelegate> delegate;
+
+- (instancetype)initWithOwner:(NSWindow<CommandDispatchingWindow>*)owner;
+
+// The main entry point for key events. The CommandDispatchingWindow should
+// override -[NSResponder performKeyEquivalent:] and call this instead. Returns
+// YES if the event is handled.
+- (BOOL)performKeyEquivalent:(NSEvent*)event;
+
+// Sends a key event to -[NSApp sendEvent:]. This is used to allow default
+// AppKit handling of an event that comes back from CommandDispatcherTarget,
+// e.g. key equivalents in the menu, or window manager commands like Cmd+`. Once
+// the event returns to the window at -preSendEvent, handling will stop. The
+// event must be of type |NSKeyDown|, |NSKeyUp|, or |NSFlagsChanged|. Returns
+// YES if the event is handled.
+- (BOOL)redispatchKeyEvent:(NSEvent*)event;
+
+// The CommandDispatchingWindow should override -[NSWindow sendEvent:] and call
+// this before a native -sendEvent. Ensures that a redispatched event is not
+// reposted infinitely. Returns YES if the event is handled.
+- (BOOL)preSendEvent:(NSEvent*)event;
+
+@end
+
+// If the NSWindow's firstResponder implements CommandDispatcherTarget, it is
+// given the first opportunity to process a command.
+@protocol CommandDispatcherTarget
+
+// To handle an event asynchronously, return YES. If the event is ultimately not
+// handled, return the event to the CommandDispatchingWindow via -[[event
+// window] redispatchKeyEvent:event].
+- (BOOL)performKeyEquivalent:(NSEvent*)event;
+
+@end
+
+// Provides CommandDispatcher with the means to redirect key equivalents at
+// different stages of event handling.
+@protocol CommandDispatcherDelegate<NSObject>
+
+// Called before any other event handling, and possibly again if an unhandled
+// event comes back from CommandDispatcherTarget.
+- (BOOL)eventHandledByExtensionCommand:(NSEvent*)event
+                          isRedispatch:(BOOL)isRedispatch;
+
+// Called before the default -performKeyEquivalent, but after the
+// CommandDispatcherTarget has had a chance to intercept it. |window| is the
+// CommandDispatchingWindow that owns CommandDispatcher.
+- (BOOL)prePerformKeyEquivalent:(NSEvent*)event window:(NSWindow*)window;
+
+// Called after the default -performKeyEquivalent. |window| is the
+// CommandDispatchingWindow that owns CommandDispatcher.
+- (BOOL)postPerformKeyEquivalent:(NSEvent*)event window:(NSWindow*)window;
+
+@end
+
+// The set of methods an NSWindow subclass needs to implement to use
+// CommandDispatcher.
+@protocol CommandDispatchingWindow<NSUserInterfaceValidations>
+
+@property(assign, nonatomic) id<UserInterfaceItemCommandHandler> commandHandler;
+
+// This can be implemented with -[CommandDispatcher redispatchKeyEvent:]. It's
+// so that callers can simply return events to the NSWindow.
+- (BOOL)redispatchKeyEvent:(NSEvent*)event;
+
+// Short-circuit to the default -[NSResponder performKeyEquivalent:] which
+// CommandDispatcher calls as part of its -performKeyEquivalent flow.
+- (BOOL)defaultPerformKeyEquivalent:(NSEvent*)event;
+
+// AppKit will call -[NSUserInterfaceValidations validateUserInterfaceItem:] to
+// validate UI items. Any item whose target is FirstResponder, or nil, will
+// traverse the responder chain looking for a responder that implements the
+// item's selector. Thus NSWindow is usually the last to be checked and will
+// handle any items that are not validated elsewhere in the chain. Implement the
+// following so that menu items with these selectors are validated by
+// CommandDispatchingWindow.
+- (void)commandDispatch:(id)sender;
+- (void)commandDispatchUsingKeyModifiers:(id)sender;
+
+@end
+
+// Used by CommandDispatchingWindow to implement UI item validation.
+@protocol UserInterfaceItemCommandHandler
+
+// Called by CommandDispatchingWindow to validate menu and toolbar items. All
+// the items we care about have been set with the -commandDispatch or
+// -commandDispatchUsingKeyModifiers selectors and a target of FirstResponder in
+// IB. If it's not one of those, it should be handled elsewhere in the responder
+// chain.
+- (BOOL)validateUserInterfaceItem:(id<NSValidatedUserInterfaceItem>)item
+                           window:(NSWindow*)window;
+
+// Called by CommandDispatchingWindow to execute commands. This assumes that the
+// command is supported and doesn't check, otherwise it would have been disabled
+// in the UI in validateUserInterfaceItem:.
+- (void)commandDispatch:(id)sender window:(NSWindow*)window;
+
+// Same as |-commandDispatch:|, but executes commands using a disposition
+// determined by the key flags. If the window is in the background and the
+// command key is down, ignore the command key, but process any other modifiers.
+- (void)commandDispatchUsingKeyModifiers:(id)sender window:(NSWindow*)window;
+
+@end
+
+#endif  // UI_BASE_COCOA_COMMAND_DISPATCHER_H_