dom/events/GlobalKeyListener.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef mozilla_GlobalKeyListener_h_
   8 #define mozilla_GlobalKeyListener_h_
   9
  10 #include "mozilla/EventForwards.h"
  11 #include "mozilla/layers/KeyboardMap.h"
  12 #include "nsIDOMEventListener.h"
  13 #include "nsIWeakReferenceUtils.h"
  14
  15 class nsAtom;
  16
  17 namespace mozilla {
  18 class EventListenerManager;
  19 class WidgetKeyboardEvent;
  20 struct IgnoreModifierState;
  21
  22 namespace layers {
  23 class KeyboardMap;
  24 }
  25
  26 namespace dom {
  27 class Element;
  28 class EventTarget;
  29 class KeyboardEvent;
  30 }  // namespace dom
  31
  32 class KeyEventHandler;
  33
  34 /**
  35  * A generic listener for key events.
  36  *
  37  * Maintains a list of shortcut handlers and is registered as a listener for DOM
  38  * key events from a target. Responsible for executing the appropriate handler
  39  * when a keyboard event is received.
  40  */
  41 class GlobalKeyListener : public nsIDOMEventListener {
  42  public:
  43   explicit GlobalKeyListener(dom::EventTarget* aTarget);
  44
  45   void InstallKeyboardEventListenersTo(
  46       EventListenerManager* aEventListenerManager);
  47   void RemoveKeyboardEventListenersFrom(
  48       EventListenerManager* aEventListenerManager);
  49
  50   NS_DECL_ISUPPORTS
  51   NS_DECL_NSIDOMEVENTLISTENER
  52
  53  protected:
  54   virtual ~GlobalKeyListener() = default;
  55
  56   MOZ_CAN_RUN_SCRIPT
  57   void WalkHandlers(dom::KeyboardEvent* aKeyEvent);
  58
  59   // walk the handlers, looking for one to handle the event
  60   MOZ_CAN_RUN_SCRIPT
  61   bool WalkHandlersInternal(dom::KeyboardEvent* aKeyEvent, bool aExecute,
  62                             bool* aOutReservedForChrome = nullptr);
  63
  64   // walk the handlers for aEvent, aCharCode and aIgnoreModifierState. Execute
  65   // it if aExecute = true.
  66   MOZ_CAN_RUN_SCRIPT
  67   bool WalkHandlersAndExecute(dom::KeyboardEvent* aKeyEvent, uint32_t aCharCode,
  68                               const IgnoreModifierState& aIgnoreModifierState,
  69                               bool aExecute,
  70                               bool* aOutReservedForChrome = nullptr);
  71
  72   // HandleEvent function for the capturing phase in the default event group.
  73   MOZ_CAN_RUN_SCRIPT
  74   void HandleEventOnCaptureInDefaultEventGroup(dom::KeyboardEvent* aEvent);
  75   // HandleEvent function for the capturing phase in the system event group.
  76   MOZ_CAN_RUN_SCRIPT
  77   void HandleEventOnCaptureInSystemEventGroup(dom::KeyboardEvent* aEvent);
  78
  79   // Check if any handler would handle the given event. Optionally returns
  80   // whether the command handler for the event is marked with the "reserved"
  81   // attribute.
  82   MOZ_CAN_RUN_SCRIPT
  83   bool HasHandlerForEvent(dom::KeyboardEvent* aEvent,
  84                           bool* aOutReservedForChrome = nullptr);
  85
  86   // Returns true if the key would be reserved for the given handler. A reserved
  87   // key is not sent to a content process or single-process equivalent.
  88   bool IsReservedKey(WidgetKeyboardEvent* aKeyEvent, KeyEventHandler* aHandler);
  89
  90   // lazily load the handlers. Overridden to handle being attached
  91   // to a particular element rather than the document
  92   virtual void EnsureHandlers() = 0;
  93
  94   virtual bool CanHandle(KeyEventHandler* aHandler, bool aWillExecute) const {
  95     return true;
  96   }
  97
  98   virtual bool IsDisabled() const { return false; }
  99
 100   virtual already_AddRefed<dom::EventTarget> GetHandlerTarget(
 101       KeyEventHandler* aHandler) {
 102     return do_AddRef(mTarget);
 103   }
 104
 105   dom::EventTarget* mTarget;  // weak ref;
 106
 107   KeyEventHandler* mHandler;  // Linked list of event handlers.
 108 };
 109
 110 /**
 111  * A listener for shortcut keys defined in XUL keyset elements.
 112  *
 113  * Listens for keyboard events from the document object and triggers the
 114  * appropriate XUL key elements.
 115  */
 116 class XULKeySetGlobalKeyListener final : public GlobalKeyListener {
 117  public:
 118   explicit XULKeySetGlobalKeyListener(dom::Element* aElement,
 119                                       dom::EventTarget* aTarget);
 120
 121   static void AttachKeyHandler(dom::Element* aElementTarget);
 122   static void DetachKeyHandler(dom::Element* aElementTarget);
 123
 124  protected:
 125   virtual ~XULKeySetGlobalKeyListener();
 126
 127   // Returns the element which was passed as a parameter to the constructor,
 128   // unless the element has been removed from the document. Optionally returns
 129   // whether the disabled attribute is set on the element (assuming the element
 130   // is non-null).
 131   dom::Element* GetElement(bool* aIsDisabled = nullptr) const;
 132
 133   virtual void EnsureHandlers() override;
 134
 135   virtual bool CanHandle(KeyEventHandler* aHandler,
 136                          bool aWillExecute) const override;
 137   virtual bool IsDisabled() const override;
 138   virtual already_AddRefed<dom::EventTarget> GetHandlerTarget(
 139       KeyEventHandler* aHandler) override;
 140
 141   /**
 142    * GetElementForHandler() retrieves an element for the handler.  The element
 143    * may be a command element or a key element.
 144    *
 145    * @param aHandler           The handler.
 146    * @param aElementForHandler Must not be nullptr.  The element is returned to
 147    *                           this.
 148    * @return                   true if the handler is valid.  Otherwise, false.
 149    */
 150   bool GetElementForHandler(KeyEventHandler* aHandler,
 151                             dom::Element** aElementForHandler) const;
 152
 153   /**
 154    * IsExecutableElement() returns true if aElement is executable.
 155    * Otherwise, false. aElement should be a command element or a key element.
 156    */
 157   bool IsExecutableElement(dom::Element* aElement) const;
 158
 159   // Using weak pointer to the DOM Element.
 160   nsWeakPtr mWeakPtrForElement;
 161 };
 162
 163 /**
 164  * Listens for built-in shortcut keys.
 165  *
 166  * Listens to DOM keyboard events from the window or text input and runs the
 167  * built-in shortcuts (see dom/events/keyevents) as necessary.
 168  */
 169 class RootWindowGlobalKeyListener final : public GlobalKeyListener {
 170  public:
 171   explicit RootWindowGlobalKeyListener(dom::EventTarget* aTarget);
 172
 173   static void AttachKeyHandler(dom::EventTarget* aTarget);
 174
 175   static layers::KeyboardMap CollectKeyboardShortcuts();
 176
 177  protected:
 178   // Is an HTML editable element focused
 179   static bool IsHTMLEditorFocused();
 180
 181   virtual void EnsureHandlers() override;
 182 };
 183
 184 }  // namespace mozilla
 185
 186 #endif