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_dom_UserAcitvation_h
8 #define mozilla_dom_UserAcitvation_h
9 
10 #include "mozilla/EventForwards.h"
11 #include "mozilla/TimeStamp.h"
12 
13 namespace mozilla {
14 namespace dom {
15 
16 class UserActivation final {
17  public:
18   enum class State : uint8_t {
19     // Not activated.
20     None,
21     // It is considered as has-been-activated, but not transient-activated given
22     // that it is being consumed.
23     HasBeenActivated,
24     // It is considered as has-been-activated, and also transient-activated if
25     // haven't timed out.
26     FullActivated,
27     EndGuard_
28   };
29 
30   /**
31    * Returns true if the current code is being executed as a result of
32    * user input or keyboard input.  The former includes anything that is
33    * initiated by user, with the exception of page load events or mouse
34    * over events.  And the latter returns true when one of the user inputs
35    * is an input from keyboard.  If these methods are called from asynchronously
36    * executed code, such as during layout reflows, it will return false.
37    */
38   static bool IsHandlingUserInput();
39   static bool IsHandlingKeyboardInput();
40 
41   /**
42    * Returns true if the event is considered as user interaction event. I.e.,
43    * enough obvious input to allow to open popup, etc. Otherwise, returns false.
44    */
45   static bool IsUserInteractionEvent(const WidgetEvent* aEvent);
46 
47   /**
48    * StartHandlingUserInput() is called when we start to handle a user input.
49    * StopHandlingUserInput() is called when we finish handling a user input.
50    * If the caller knows which input event caused that, it should set
51    * aMessage to the event message.  Otherwise, set eVoidEvent.
52    * Note that StopHandlingUserInput() caller should call it with exactly same
53    * event message as its corresponding StartHandlingUserInput() call because
54    * these methods may count the number of specific event message.
55    */
56   static void StartHandlingUserInput(EventMessage aMessage);
57   static void StopHandlingUserInput(EventMessage aMessage);
58 
59   static TimeStamp GetHandlingInputStart();
60 
61   /**
62    * Get the timestamp at which the latest user input was handled.
63    *
64    * Guaranteed to be monotonic. Until the first user input, return
65    * the epoch.
66    */
67   static TimeStamp LatestUserInputStart();
68 };
69 
70 /**
71  * This class is used while processing real user input. During this time, popups
72  * are allowed. For mousedown events, mouse capturing is also permitted.
73  */
74 class MOZ_RAII AutoHandlingUserInputStatePusher final {
75  public:
76   explicit AutoHandlingUserInputStatePusher(bool aIsHandlingUserInput,
77                                             WidgetEvent* aEvent = nullptr);
78   ~AutoHandlingUserInputStatePusher();
79 
80  protected:
81   EventMessage mMessage;
82   bool mIsHandlingUserInput;
83 };
84 
85 }  // namespace dom
86 }  // namespace mozilla
87 
88 #endif  // mozilla_dom_UserAcitvation_h
89