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"
#include "ui/base/ui_base_export.h"

@protocol CommandDispatcherDelegate;
@protocol CommandDispatchingWindow;

// 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.
UI_BASE_EXPORT @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

// 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;

@end

#endif  // UI_BASE_COCOA_COMMAND_DISPATCHER_H_