Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / ash / sticky_keys / sticky_keys_controller.h
blob1ebe1d854975edbfdb5900f38b4ed7282f8643c5
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.
5 #ifndef ASH_STICKY_KEYS_STICKY_KEYS_CONTROLLER_H_
6 #define ASH_STICKY_KEYS_STICKY_KEYS_CONTROLLER_H_
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 #include "ui/events/event_rewriter.h"
14 #include "ui/events/keycodes/keyboard_codes.h"
16 namespace ui {
17 class Event;
18 class KeyEvent;
19 class MouseEvent;
20 } // namespace ui
22 namespace aura {
23 class Window;
24 } // namespace aura
26 namespace ash {
28 class StickyKeysOverlay;
29 class StickyKeysHandler;
31 // StickyKeysController is an accessibility feature for users to be able to
32 // compose key and mouse event with modifier keys without simultaneous key
33 // press event. Instead they can compose events separately pressing each of the
34 // modifier keys involved.
35 // e.g. Composing Ctrl + T
36 // User Action : The KeyEvent widget will receives
37 // ----------------------------------------------------------
38 // 1. Press Ctrl key : Ctrl Keydown.
39 // 2. Release Ctrl key : No event
40 // 3. Press T key : T keydown event with ctrl modifier.
41 // 4. : Ctrl Keyup
42 // 5. Release T key : T keyup without ctrl modifier (Windows behavior)
44 // By typing same modifier keys twice, users can generate bunch of modified key
45 // events.
46 // e.g. To focus tabs consistently by Ctrl + 1, Ctrl + 2 ...
47 // User Action : The KeyEvent widget will receives
48 // ----------------------------------------------------------
49 // 1. Press Ctrl key : Ctrl Keydown
50 // 2. Release Ctrl key : No event
51 // 3. Press Ctrl key : No event
52 // 4. Release Ctrl key : No event
53 // 5. Press 1 key : 1 Keydown event with Ctrl modifier.
54 // 6. Release 1 key : 1 Keyup event with Ctrl modifier.
55 // 7. Press 2 key : 2 Keydown event with Ctrl modifier.
56 // 8. Release 2 key : 2 Keyup event with Ctrl modifier.
57 // 9. Press Ctrl key : No event
58 // 10. Release Ctrl key: Ctrl Keyup
60 // In the case of Chrome OS, StickyKeysController supports Shift,Alt,Ctrl
61 // modifiers. Each handling or state is performed independently.
63 // StickyKeysController is disabled by default.
64 class ASH_EXPORT StickyKeysController {
65 public:
66 StickyKeysController();
67 virtual ~StickyKeysController();
69 // Activate sticky keys to intercept and modify incoming events.
70 void Enable(bool enabled);
72 void SetModifiersEnabled(bool mod3_enabled, bool altgr_enabled);
74 // Returns the StickyKeyOverlay used by the controller. Ownership is not
75 // passed.
76 StickyKeysOverlay* GetOverlayForTest();
78 // Handles keyboard event. Returns an |EventRewriteStatus|, and may
79 // modify |flags|:
80 // - Returns ui::EVENT_REWRITE_DISCARD, and leaves |flags| untouched,
81 // if the event is consumed (i.e. a sticky modifier press or release);
82 // - Returns ui::EVENT_REWRITE_REWRITTEN if the event needs to be modified
83 // according to the returned |flags| (i.e. a sticky-modified key);
84 // - Returns ui::EVENT_REWRITE_DISPATCH_ANOTHER if the event needs to be
85 // modified according to the returned |flags|, and there are delayed
86 // modifier-up events now to be retrieved using |NextDispatchEvent()|
87 // (i.e. a sticky-modified key that ends a sticky state);
88 // - Otherwise returns ui::EVENT_REWRITE_CONTINUE and leaves |flags|
89 // unchanged.
90 ui::EventRewriteStatus RewriteKeyEvent(const ui::KeyEvent& event,
91 ui::KeyboardCode key_code,
92 int* flags);
94 // Handles mouse event.
95 ui::EventRewriteStatus RewriteMouseEvent(const ui::MouseEvent& event,
96 int* flags);
98 // Handles scroll event.
99 ui::EventRewriteStatus RewriteScrollEvent(const ui::ScrollEvent& event,
100 int* flags);
102 // Obtains a pending modifier-up event. If the immediately previous
103 // call to |Rewrite...Event()| or |NextDispatchEvent()| returned
104 // ui::EVENT_REWRITE_DISPATCH_ANOTHER, this sets |new_event| and returns:
105 // - ui::EVENT_REWRITE_DISPATCH_ANOTHER if there is at least one more
106 // pending modifier-up event;
107 // - ui::EVENT_REWRITE_REWRITE if this is the last or only modifier-up event;
108 // Otherwise, there is no pending modifier-up event, and this function
109 // returns ui::EVENT_REWRITE_CONTINUE and sets |new_event| to NULL.
110 ui::EventRewriteStatus NextDispatchEvent(scoped_ptr<ui::Event>* new_event);
112 private:
113 // Handles keyboard event. Returns true if Sticky key consumes keyboard event.
114 // Adds to |mod_down_flags| any flag to be added to the key event.
115 // Sets |released| if any modifier is to be released after the key event.
116 bool HandleKeyEvent(const ui::KeyEvent& event,
117 ui::KeyboardCode key_code,
118 int* mod_down_flags,
119 bool* released);
121 // Handles mouse event. Returns true if Sticky key consumes keyboard event.
122 // Sets |released| if any modifier is to be released after the key event.
123 bool HandleMouseEvent(const ui::MouseEvent& event,
124 int* mod_down_flags,
125 bool* released);
127 // Handles scroll event. Returns true if Sticky key consumes keyboard event.
128 // Sets |released| if any modifier is to be released after the key event.
129 bool HandleScrollEvent(const ui::ScrollEvent& event,
130 int* mod_down_flags,
131 bool* released);
133 // Updates the overlay UI with the current state of the sticky keys.
134 void UpdateOverlay();
136 // Whether sticky keys is activated and modifying events.
137 bool enabled_;
139 // Whether the current layout has a mod3 key.
140 bool mod3_enabled_;
142 // Whether the current layout has an altgr key.
143 bool altgr_enabled_;
145 // Sticky key handlers.
146 scoped_ptr<StickyKeysHandler> shift_sticky_key_;
147 scoped_ptr<StickyKeysHandler> alt_sticky_key_;
148 scoped_ptr<StickyKeysHandler> altgr_sticky_key_;
149 scoped_ptr<StickyKeysHandler> ctrl_sticky_key_;
150 scoped_ptr<StickyKeysHandler> mod3_sticky_key_;
151 scoped_ptr<StickyKeysHandler> search_sticky_key_;
153 scoped_ptr<StickyKeysOverlay> overlay_;
155 DISALLOW_COPY_AND_ASSIGN(StickyKeysController);
158 // StickyKeysHandler handles key event and controls sticky keysfor specific
159 // modifier keys. If monitored keyboard events are recieved, StickyKeysHandler
160 // changes internal state. If non modifier keyboard events or mouse events are
161 // received, StickyKeysHandler will append modifier based on internal state.
162 // For other events, StickyKeysHandler does nothing.
164 // The DISABLED state is default state and any incoming non modifier keyboard
165 // events will not be modified. The ENABLED state is one shot modification
166 // state. Only next keyboard event will be modified. After that, internal state
167 // will be back to DISABLED state with sending modifier keyup event. In the case
168 // of LOCKED state, all incomming keyboard events will be modified. The LOCKED
169 // state will be back to DISABLED state by next monitoring modifier key.
171 // The detailed state flow as follows:
172 // Current state
173 // | DISABLED | ENABLED | LOCKED |
174 // ----------------------------------------------------------------|
175 // Modifier KeyDown | noop | noop(*) | noop(*) |
176 // Modifier KeyUp | To ENABLED(*) | To LOCKED(*) | To DISABLED |
177 // Normal KeyDown | noop | To DISABLED(#) | noop(#) |
178 // Normal KeyUp | noop | noop | noop(#) |
179 // Other KeyUp/Down | noop | noop | noop |
180 // Mouse Press | noop | noop(#) | noop(#) |
181 // Mouse Release | noop | To DISABLED(#) | noop(#) |
182 // Mouse Wheel | noop | To DISABLED(#) | noop(#) |
183 // Other Mouse Event| noop | noop | noop |
185 // Here, (*) means key event will be consumed by StickyKeys, and (#) means event
186 // is modified.
187 class ASH_EXPORT StickyKeysHandler {
188 public:
189 explicit StickyKeysHandler(ui::EventFlags modifier_flag);
190 ~StickyKeysHandler();
192 // Handles keyboard event. Returns true if Sticky key consumes keyboard event.
193 // Sets its own modifier flag in |mod_down_flags| if it is active and needs
194 // to be added to the event, and sets |released| if releasing it.
195 bool HandleKeyEvent(const ui::KeyEvent& event,
196 ui::KeyboardCode key_code,
197 int* mod_down_flags,
198 bool* released);
200 // Handles mouse event. Returns true if sticky key consumes mouse event.
201 // Sets its own modifier flag in |mod_down_flags| if it is active and needs
202 // to be added to the event, and sets |released| if releasing it.
203 bool HandleMouseEvent(const ui::MouseEvent& event,
204 int* mod_down_flags,
205 bool* released);
207 // Handles scroll event. Returns true if sticky key consumes scroll event.
208 // Sets its own modifier flag in |mod_down_flags| if it is active and needs
209 // to be added to the event, and sets |released| if releasing it.
210 bool HandleScrollEvent(const ui::ScrollEvent& event,
211 int* mod_down_flags,
212 bool* released);
214 // Fetches a pending modifier-up event if one exists and the return
215 // parameter |new_event| is available (i.e. not set). Returns the number
216 // of pending events still remaining to be returned.
217 int GetModifierUpEvent(scoped_ptr<ui::Event>* new_event);
219 // Returns current internal state.
220 StickyKeyState current_state() const { return current_state_; }
222 private:
223 // Represents event type in Sticky Key context.
224 enum KeyEventType {
225 TARGET_MODIFIER_DOWN, // The monitoring modifier key is down.
226 TARGET_MODIFIER_UP, // The monitoring modifier key is up.
227 NORMAL_KEY_DOWN, // The non modifier key is down.
228 NORMAL_KEY_UP, // The non modifier key is up.
229 OTHER_MODIFIER_DOWN, // The modifier key but not monitored key is down.
230 OTHER_MODIFIER_UP, // The modifier key but not monitored key is up.
233 // Translates event type and key code to sticky keys event type.
234 KeyEventType TranslateKeyEvent(ui::EventType type, ui::KeyboardCode key_code);
236 // Handles key event in DISABLED state. Returns true if sticky keys
237 // consumes the keyboard event.
238 bool HandleDisabledState(const ui::KeyEvent& event,
239 ui::KeyboardCode key_code);
241 // Handles key event in ENABLED state. Returns true if sticky keys
242 // consumes the keyboard event.
243 bool HandleEnabledState(const ui::KeyEvent& event,
244 ui::KeyboardCode key_code,
245 int* mod_down_flags,
246 bool* released);
248 // Handles key event in LOCKED state. Returns true if sticky keys
249 // consumes the keyboard event.
250 bool HandleLockedState(const ui::KeyEvent& event,
251 ui::KeyboardCode key_code,
252 int* mod_down_flags,
253 bool* released);
255 // The modifier flag to be monitored and appended to events.
256 const ui::EventFlags modifier_flag_;
258 // The current sticky key status.
259 StickyKeyState current_state_;
261 // True if we received the TARGET_MODIFIER_DOWN event while in the DISABLED
262 // state but before we receive the TARGET_MODIFIER_UP event. Normal
263 // shortcuts (eg. ctrl + t) during this time will prevent a transition to
264 // the ENABLED state.
265 bool preparing_to_enable_;
267 // Tracks the scroll direction of the current scroll sequence. Sticky keys
268 // stops modifying the scroll events of the sequence when the direction
269 // changes. If no sequence is tracked, the value is 0.
270 int scroll_delta_;
272 // The modifier up key event to be sent on non modifier key on ENABLED state.
273 scoped_ptr<ui::KeyEvent> modifier_up_event_;
275 DISALLOW_COPY_AND_ASSIGN(StickyKeysHandler);
278 } // namespace ash
280 #endif // ASH_STICKY_KEYS_STICKY_KEYS_CONTROLLER_H_