ui/base/cocoa/command_dispatcher.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef UI_BASE_COCOA_COMMAND_DISPATCHER_H_
   6 #define UI_BASE_COCOA_COMMAND_DISPATCHER_H_
   7
   8 #import <Cocoa/Cocoa.h>
   9
  10 #import "base/mac/scoped_nsobject.h"
  11 #include "ui/base/ui_base_export.h"
  12
  13 @protocol CommandDispatcherDelegate;
  14 @protocol CommandDispatchingWindow;
  15 @protocol UserInterfaceItemCommandHandler;
  16
  17 // CommandDispatcher guides the processing of key events to ensure key commands
  18 // are executed in the appropriate order. In particular, it allows a first
  19 // responder implementing CommandDispatcherTarget to handle an event
  20 // asynchronously and return unhandled events via -redispatchKeyEvent:. An
  21 // NSWindow can use CommandDispatcher by implementing CommandDispatchingWindow
  22 // and overriding -[NSWindow performKeyEquivalent:] and -[NSWindow sendEvent:]
  23 // to call the respective CommandDispatcher methods.
  24 UI_BASE_EXPORT @interface CommandDispatcher : NSObject
  25
  26 @property(assign, nonatomic) id<CommandDispatcherDelegate> delegate;
  27
  28 - (instancetype)initWithOwner:(NSWindow<CommandDispatchingWindow>*)owner;
  29
  30 // The main entry point for key events. The CommandDispatchingWindow should
  31 // override -[NSResponder performKeyEquivalent:] and call this instead. Returns
  32 // YES if the event is handled.
  33 - (BOOL)performKeyEquivalent:(NSEvent*)event;
  34
  35 // Sends a key event to -[NSApp sendEvent:]. This is used to allow default
  36 // AppKit handling of an event that comes back from CommandDispatcherTarget,
  37 // e.g. key equivalents in the menu, or window manager commands like Cmd+`. Once
  38 // the event returns to the window at -preSendEvent:, handling will stop. The
  39 // event must be of type |NSKeyDown|, |NSKeyUp|, or |NSFlagsChanged|. Returns
  40 // YES if the event is handled.
  41 - (BOOL)redispatchKeyEvent:(NSEvent*)event;
  42
  43 // The CommandDispatchingWindow should override -[NSWindow sendEvent:] and call
  44 // this before a native -sendEvent:. Ensures that a redispatched event is not
  45 // reposted infinitely. Returns YES if the event is handled.
  46 - (BOOL)preSendEvent:(NSEvent*)event;
  47
  48 @end
  49
  50 // If the NSWindow's firstResponder implements CommandDispatcherTarget, it is
  51 // given the first opportunity to process a command.
  52 @protocol CommandDispatcherTarget
  53
  54 // To handle an event asynchronously, return YES. If the event is ultimately not
  55 // handled, return the event to the CommandDispatchingWindow via -[[event
  56 // window] redispatchKeyEvent:event].
  57 - (BOOL)performKeyEquivalent:(NSEvent*)event;
  58
  59 @end
  60
  61 // Provides CommandDispatcher with the means to redirect key equivalents at
  62 // different stages of event handling.
  63 @protocol CommandDispatcherDelegate<NSObject>
  64
  65 // Called before any other event handling, and possibly again if an unhandled
  66 // event comes back from CommandDispatcherTarget.
  67 - (BOOL)eventHandledByExtensionCommand:(NSEvent*)event
  68                           isRedispatch:(BOOL)isRedispatch;
  69
  70 // Called before the default -performKeyEquivalent:, but after the
  71 // CommandDispatcherTarget has had a chance to intercept it. |window| is the
  72 // CommandDispatchingWindow that owns CommandDispatcher.
  73 - (BOOL)prePerformKeyEquivalent:(NSEvent*)event window:(NSWindow*)window;
  74
  75 // Called after the default -performKeyEquivalent:. |window| is the
  76 // CommandDispatchingWindow that owns CommandDispatcher.
  77 - (BOOL)postPerformKeyEquivalent:(NSEvent*)event window:(NSWindow*)window;
  78
  79 @end
  80
  81 // The set of methods an NSWindow subclass needs to implement to use
  82 // CommandDispatcher.
  83 @protocol CommandDispatchingWindow
  84
  85 // If set, NSUserInterfaceItemValidations for -commandDispatch: and
  86 // -commandDispatchUsingKeyModifiers: will be redirected to the command handler.
  87 // Retains |commandHandler|.
  88 -(void)setCommandHandler:(id<UserInterfaceItemCommandHandler>) commandHandler;
  89
  90 // This can be implemented with -[CommandDispatcher redispatchKeyEvent:]. It's
  91 // so that callers can simply return events to the NSWindow.
  92 - (BOOL)redispatchKeyEvent:(NSEvent*)event;
  93
  94 // Short-circuit to the default -[NSResponder performKeyEquivalent:] which
  95 // CommandDispatcher calls as part of its -performKeyEquivalent: flow.
  96 - (BOOL)defaultPerformKeyEquivalent:(NSEvent*)event;
  97
  98 // AppKit will call -[NSUserInterfaceValidations validateUserInterfaceItem:] to
  99 // validate UI items. Any item whose target is FirstResponder, or nil, will
 100 // traverse the responder chain looking for a responder that implements the
 101 // item's selector. Thus NSWindow is usually the last to be checked and will
 102 // handle any items that are not validated elsewhere in the chain. Implement the
 103 // following so that menu items with these selectors are validated by
 104 // CommandDispatchingWindow.
 105 - (void)commandDispatch:(id)sender;
 106 - (void)commandDispatchUsingKeyModifiers:(id)sender;
 107
 108 @end
 109
 110 #endif  // UI_BASE_COCOA_COMMAND_DISPATCHER_H_