src/ash/sticky_keys/sticky_keys_controller.h

   1 // Copyright 2013 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 ASH_STICKY_KEYS_STICKY_KEYS_CONTROLLER_H_
   6 #define ASH_STICKY_KEYS_STICKY_KEYS_CONTROLLER_H_
   7
   8 #include "ash/ash_export.h"
   9 #include "ash/sticky_keys/sticky_keys_state.h"
  10 #include "base/memory/scoped_ptr.h"
  11 #include "ui/events/event_constants.h"
  12 #include "ui/events/event_handler.h"
  13
  14 namespace ui {
  15 class Event;
  16 class KeyEvent;
  17 class MouseEvent;
  18 }  // namespace ui
  19
  20 namespace aura {
  21 class Window;
  22 }  // namespace aura
  23
  24 namespace ash {
  25
  26 class StickyKeysOverlay;
  27 class StickyKeysHandler;
  28
  29 // StickyKeysController is an accessibility feature for users to be able to
  30 // compose key and mouse event with modifier keys without simultaneous key
  31 // press event. Instead they can compose events separately pressing each of the
  32 // modifier keys involved.
  33 // e.g. Composing Ctrl + T
  34 //       User Action   : The KeyEvent widget will receives
  35 // ----------------------------------------------------------
  36 // 1. Press Ctrl key   : Ctrl Keydown.
  37 // 2. Release Ctrl key : No event
  38 // 3. Press T key      : T keydown event with ctrl modifier.
  39 // 4.                  : Ctrl Keyup
  40 // 5. Release T key    : T keyup without ctrl modifier (Windows behavior)
  41 //
  42 // By typing same modifier keys twice, users can generate bunch of modified key
  43 // events.
  44 // e.g. To focus tabs consistently by Ctrl + 1, Ctrl + 2 ...
  45 //       User Action   : The KeyEvent widget will receives
  46 // ----------------------------------------------------------
  47 // 1. Press Ctrl key   : Ctrl Keydown
  48 // 2. Release Ctrl key : No event
  49 // 3. Press Ctrl key   : No event
  50 // 4. Release Ctrl key : No event
  51 // 5. Press 1 key      : 1 Keydown event with Ctrl modifier.
  52 // 6. Release 1 key    : 1 Keyup event with Ctrl modifier.
  53 // 7. Press 2 key      : 2 Keydown event with Ctrl modifier.
  54 // 8. Release 2 key    : 2 Keyup event with Ctrl modifier.
  55 // 9. Press Ctrl key   : No event
  56 // 10. Release Ctrl key: Ctrl Keyup
  57 //
  58 // In the case of Chrome OS, StickyKeysController supports Shift,Alt,Ctrl
  59 // modifiers. Each handling or state is performed independently.
  60 //
  61 // StickyKeysController is disabled by default.
  62 class ASH_EXPORT StickyKeysController : public ui::EventHandler {
  63  public:
  64   StickyKeysController();
  65   virtual ~StickyKeysController();
  66
  67   // Activate sticky keys to intercept and modify incoming events.
  68   void Enable(bool enabled);
  69
  70   void SetModifiersEnabled(bool mod3_enabled, bool altgr_enabled);
  71
  72   // Overridden from ui::EventHandler:
  73   virtual void OnKeyEvent(ui::KeyEvent* event) OVERRIDE;
  74   virtual void OnMouseEvent(ui::MouseEvent* event) OVERRIDE;
  75   virtual void OnScrollEvent(ui::ScrollEvent* event) OVERRIDE;
  76
  77   // Returns the StickyKeyOverlay used by the controller. Ownership is not
  78   // passed.
  79   StickyKeysOverlay* GetOverlayForTest();
  80
  81  private:
  82   // Handles keyboard event. Returns true if Sticky key consumes keyboard event.
  83   bool HandleKeyEvent(ui::KeyEvent* event);
  84
  85   // Handles mouse event. Returns true if sticky key consumes mouse event.
  86   bool HandleMouseEvent(ui::MouseEvent* event);
  87
  88   // Handles scroll event. Returns true if sticky key consumes scroll event.
  89   bool HandleScrollEvent(ui::ScrollEvent* event);
  90
  91   // Updates the overlay UI with the current state of the sticky keys.
  92   void UpdateOverlay();
  93
  94   // Whether sticky keys is activated and modifying events.
  95   bool enabled_;
  96
  97   // Whether the current layout has a mod3 key.
  98   bool mod3_enabled_;
  99
 100   // Whether the current layout has an altgr key.
 101   bool altgr_enabled_;
 102
 103   // Sticky key handlers.
 104   scoped_ptr<StickyKeysHandler> shift_sticky_key_;
 105   scoped_ptr<StickyKeysHandler> alt_sticky_key_;
 106   scoped_ptr<StickyKeysHandler> altgr_sticky_key_;
 107   scoped_ptr<StickyKeysHandler> ctrl_sticky_key_;
 108   scoped_ptr<StickyKeysHandler> mod3_sticky_key_;
 109
 110   scoped_ptr<StickyKeysOverlay> overlay_;
 111
 112   DISALLOW_COPY_AND_ASSIGN(StickyKeysController);
 113 };
 114
 115 // StickyKeysHandler handles key event and controls sticky keysfor specific
 116 // modifier keys. If monitored keyboard events are recieved, StickyKeysHandler
 117 // changes internal state. If non modifier keyboard events or mouse events are
 118 // received, StickyKeysHandler will append modifier based on internal state.
 119 // For other events, StickyKeysHandler does nothing.
 120 //
 121 // The DISABLED state is default state and any incoming non modifier keyboard
 122 // events will not be modified. The ENABLED state is one shot modification
 123 // state. Only next keyboard event will be modified. After that, internal state
 124 // will be back to DISABLED state with sending modifier keyup event. In the case
 125 // of LOCKED state, all incomming keyboard events will be modified. The LOCKED
 126 // state will be back to DISABLED state by next monitoring modifier key.
 127 //
 128 // The detailed state flow as follows:
 129 //                                     Current state
 130 //                  |   DISABLED    |    ENABLED     |    LOCKED   |
 131 // ----------------------------------------------------------------|
 132 // Modifier KeyDown |   noop        |    noop(*)     |    noop(*)  |
 133 // Modifier KeyUp   | To ENABLED(*) | To LOCKED(*)   | To DISABLED |
 134 // Normal KeyDown   |   noop        | To DISABLED(#) |    noop(#)  |
 135 // Normal KeyUp     |   noop        |    noop        |    noop(#)  |
 136 // Other KeyUp/Down |   noop        |    noop        |    noop     |
 137 // Mouse Press      |   noop        |    noop(#)     |    noop(#)  |
 138 // Mouse Release    |   noop        | To DISABLED(#) |    noop(#)  |
 139 // Mouse Wheel      |   noop        | To DISABLED(#) |    noop(#)  |
 140 // Other Mouse Event|   noop        |    noop        |    noop     |
 141 //
 142 // Here, (*) means key event will be consumed by StickyKeys, and (#) means event
 143 // is modified.
 144 class ASH_EXPORT StickyKeysHandler {
 145  public:
 146   class StickyKeysHandlerDelegate {
 147    public:
 148     StickyKeysHandlerDelegate();
 149     virtual ~StickyKeysHandlerDelegate();
 150
 151     // Dispatches keyboard event synchronously. |event| is an event that has
 152     // been previously dispatched.
 153     virtual void DispatchKeyEvent(ui::KeyEvent* event,
 154                                   aura::Window* target) = 0;
 155
 156     // Dispatches mouse event synchronously. |event| is an event that has
 157     // been previously dispatched.
 158     virtual void DispatchMouseEvent(ui::MouseEvent* event,
 159                                     aura::Window* target) = 0;
 160
 161     // Dispatches scroll event synchronously. |event| is an event that has
 162     // been previously dispatched.
 163     virtual void DispatchScrollEvent(ui::ScrollEvent* event,
 164                                      aura::Window* target) = 0;
 165   };
 166
 167   // This class takes an ownership of |delegate|.
 168   StickyKeysHandler(ui::EventFlags modifier_flag,
 169                     StickyKeysHandlerDelegate* delegate);
 170   ~StickyKeysHandler();
 171
 172   // Handles key event. Returns true if key is consumed.
 173   bool HandleKeyEvent(ui::KeyEvent* event);
 174
 175   // Handles a mouse event. Returns true if mouse event is consumed.
 176   bool HandleMouseEvent(ui::MouseEvent* event);
 177
 178   // Handles a scroll event. Returns true if scroll event is consumed.
 179   bool HandleScrollEvent(ui::ScrollEvent* event);
 180
 181   // Returns current internal state.
 182   StickyKeyState current_state() const { return current_state_; }
 183
 184  private:
 185   // Represents event type in Sticky Key context.
 186   enum KeyEventType {
 187     TARGET_MODIFIER_DOWN,  // The monitoring modifier key is down.
 188     TARGET_MODIFIER_UP,  // The monitoring modifier key is up.
 189     NORMAL_KEY_DOWN,  // The non modifier key is down.
 190     NORMAL_KEY_UP,  // The non modifier key is up.
 191     OTHER_MODIFIER_DOWN,  // The modifier key but not monitored key is down.
 192     OTHER_MODIFIER_UP,  // The modifier key but not monitored key is up.
 193   };
 194
 195   // Translates |event| to sticky keys event type.
 196   KeyEventType TranslateKeyEvent(ui::KeyEvent* event);
 197
 198   // Handles key event in DISABLED state.
 199   bool HandleDisabledState(ui::KeyEvent* event);
 200
 201   // Handles key event in ENABLED state.
 202   bool HandleEnabledState(ui::KeyEvent* event);
 203
 204   // Handles key event in LOCKED state.
 205   bool HandleLockedState(ui::KeyEvent* event);
 206
 207   // Dispatches |event| to its target and then dispatch a key released event
 208   // for the modifier key. This function is required to ensure that the events
 209   // are sent in the correct order when disabling sticky key after a key/mouse
 210   // button press.
 211   void DispatchEventAndReleaseModifier(ui::Event* event);
 212
 213   // Adds |modifier_flags_| to a native X11 event state mask.
 214   void AppendNativeEventMask(unsigned int* state);
 215
 216   // Adds |modifier_flags_| into |event|.
 217   void AppendModifier(ui::KeyEvent* event);
 218   void AppendModifier(ui::MouseEvent* event);
 219   void AppendModifier(ui::ScrollEvent* event);
 220
 221   // The modifier flag to be monitored and appended to events.
 222   const ui::EventFlags modifier_flag_;
 223
 224   // The current sticky key status.
 225   StickyKeyState current_state_;
 226
 227   // True if the received key event is sent by StickyKeyHandler.
 228   bool event_from_myself_;
 229
 230   // True if we received the TARGET_MODIFIER_DOWN event while in the DISABLED
 231   // state but before we receive the TARGET_MODIFIER_UP event. Normal
 232   // shortcuts (eg. ctrl + t) during this time will prevent a transition to
 233   // the ENABLED state.
 234   bool preparing_to_enable_;
 235
 236   // Tracks the scroll direction of the current scroll sequence. Sticky keys
 237   // stops modifying the scroll events of the sequence when the direction
 238   // changes. If no sequence is tracked, the value is 0.
 239   int scroll_delta_;
 240
 241   // The modifier up key event to be sent on non modifier key on ENABLED state.
 242   scoped_ptr<ui::KeyEvent> modifier_up_event_;
 243
 244   scoped_ptr<StickyKeysHandlerDelegate> delegate_;
 245
 246   DISALLOW_COPY_AND_ASSIGN(StickyKeysHandler);
 247 };
 248
 249 }  // namespace ash
 250
 251 #endif  // ASH_STICKY_KEYS_STICKY_KEYS_CONTROLLER_H_