ios/chrome/browser/ui/keyboard/UIKeyCommand+Chrome.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 IOS_CHROME_BROWSER_UI_KEYBOARD_UIKEYCOMMAND_CHROME_H_
   6 #define IOS_CHROME_BROWSER_UI_KEYBOARD_UIKEYCOMMAND_CHROME_H_
   7
   8 #import <Foundation/Foundation.h>
   9 #import <UIKit/UIKit.h>
  10
  11 NS_ASSUME_NONNULL_BEGIN
  12
  13 // Protocol UIResponder subclasses can implement to intercept key commands.
  14 // The implementer must be in the responder chain and be the first to respond to
  15 // this method to be called.
  16 @protocol ChromeKeyCommandHandler
  17
  18 // Called when a registered key command was detected and the receiver is the
  19 // first responder implementing this method in the responder chain.
  20 - (void)cr_handleKeyCommand:(UIKeyCommand*)keyCommand;
  21
  22 @end
  23
  24 // UIApplication is always the last responder. By making it implement the
  25 // ChromeKeyCommandHandler protocol, it catches by default all key commands
  26 // and calls their cr_action.
  27 @interface UIApplication (ChromeKeyCommandHandler)<ChromeKeyCommandHandler>
  28 @end
  29
  30 typedef void (^UIKeyCommandAction)(void);
  31
  32 // Addition to the set of predefined modifier flags.
  33 extern UIKeyModifierFlags Cr_UIKeyModifierNone;
  34
  35 // Defines a set of one-liner factory methods taking a key command block.
  36 // That way, responders willing to declare and respond to key commands can do it
  37 // in only one place:
  38 //
  39 // foo.mm:
  40 //
  41 // - (NSArray*)keyCommands {
  42 //   base::WeakNSObject<AccountsTableViewController> weakSelf(self);
  43 //   return @[
  44 //     [UIKeyCommand cr_keyCommandWithInput:UIKeyInputEscape
  45 //                           modifierFlags:Cr_UIKeyModifierNone
  46 //                                   title:@"Exit"
  47 //                                  action:^{ [[Bar sharedInstance] exit]; }],
  48 //     [UIKeyCommand cr_keyCommandWithInput:@"t"
  49 //                            modifierFlags:UIKeyModifierCommand
  50 //                                    title:@"New Tab"
  51 //                                   action:^{
  52 //       base::scoped_nsobject<Foo> strongSelf([weakSelf retain]);
  53 //       if (!strongSelf)
  54 //         return;
  55 //       [strongSelf openNewTab];
  56 //     }],
  57 //   ];
  58 // }
  59 //
  60 // Or in a UIViewController:
  61 //
  62 // baz_view_controller.mm:
  63 //
  64 // - (void)viewDidLoad {
  65 //   …
  66 //   [self addKeyCommand:[UIKeyCommand cr_keyCommandWithInput:input
  67 //                                             modifierFlags:modifierFlags
  68 //                                                     title:title
  69 //                                                    action:action]];
  70 //   …
  71 // }
  72 //
  73 // Note: this is implemented as a category on UIKeyCommand because UIKeyCommand
  74 // can't be subclassed as of iOS 9 beta 4. http://crbug.com/510970
  75 @interface UIKeyCommand (Chrome)
  76
  77 // Block to call when the key command is fired.
  78 @property(nonatomic, copy, setter=cr_setAction:) UIKeyCommandAction cr_action;
  79 // Returns a symbolic description of the key command. For example: ⇧⌘T.
  80 @property(nonatomic, readonly) NSString* cr_symbolicDescription;
  81
  82 // Returns a key command to return in -[UIResponder keyCommands] or to pass to
  83 // -[UIViewController addKeyCommand:].
  84 + (instancetype)cr_keyCommandWithInput:(NSString*)input
  85                          modifierFlags:(UIKeyModifierFlags)modifierFlags
  86                                  title:(nullable NSString*)discoveryTitle
  87                                 action:(UIKeyCommandAction)action;
  88
  89 @end
  90
  91 NS_ASSUME_NONNULL_END
  92
  93 #endif  // IOS_CHROME_BROWSER_UI_KEYBOARD_UIKEYCOMMAND_CHROME_H_