1 // Copyright (c) 2012 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 UI_EVENTS_EVENT_TARGET_H_
6 #define UI_EVENTS_EVENT_TARGET_H_
7 
8 #include <memory>
9 #include <vector>
10 
11 #include "base/compiler_specific.h"
12 #include "base/macros.h"
13 #include "ui/events/event_handler.h"
14 #include "ui/events/events_export.h"
15 #include "ui/gfx/geometry/point.h"
16 #include "ui/gfx/geometry/point_f.h"
17 
18 namespace ui {
19 
20 class EventDispatcher;
21 class EventTargeter;
22 class EventTargetIterator;
23 class LocatedEvent;
24 
25 class EVENTS_EXPORT EventTarget {
26  public:
27   class DispatcherApi {
28    public:
DispatcherApi(EventTarget * target)29     explicit DispatcherApi(EventTarget* target) : target_(target) {}
30 
31    private:
32     DispatcherApi();
33     EventTarget* target_;
34 
35     DISALLOW_COPY_AND_ASSIGN(DispatcherApi);
36   };
37 
38   EventTarget();
39   virtual ~EventTarget();
40 
41   virtual bool CanAcceptEvent(const Event& event) = 0;
42 
43   // Returns the parent EventTarget in the event-target tree.
44   virtual EventTarget* GetParentTarget() = 0;
45 
46   // Returns an iterator an EventTargeter can use to iterate over the list of
47   // child EventTargets.
48   virtual std::unique_ptr<EventTargetIterator> GetChildIterator() const = 0;
49 
50   // Returns the EventTargeter that should be used to find the target for an
51   // event in the subtree rooted at this EventTarget.
52   virtual EventTargeter* GetEventTargeter() = 0;
53 
54   // Updates the states in |event| (e.g. location) to be suitable for |target|,
55   // so that |event| can be dispatched to |target|.
56   virtual void ConvertEventToTarget(const EventTarget* target,
57                                     LocatedEvent* event) const;
58 
59   // Get |event|'s screen location, using the EventTarget's screen location.
60   virtual gfx::PointF GetScreenLocationF(const LocatedEvent& event) const;
61   gfx::Point GetScreenLocation(const LocatedEvent& event) const;
62 
63   // Priority levels for PreTargetHandlers.
64   enum class Priority {
65     // The Accessibility level is the highest, and gets events before
66     // other priority levels. This allows accessibility features to
67     // modify events directly from the user.
68     kAccessibility,
69 
70     // System priority EventHandlers get events before default level, and
71     // should be used for drag and drop, menus, etc.
72     kSystem,
73 
74     // The default level should be used by most EventHandlers.
75     kDefault,
76   };
77 
78   // Adds a handler to receive events before the target. The handler must be
79   // explicitly removed from the target before the handler is destroyed. The
80   // EventTarget does not take ownership of the handler.
81   void AddPreTargetHandler(EventHandler* handler,
82                            Priority priority = Priority::kDefault);
83   void RemovePreTargetHandler(EventHandler* handler);
84 
85   // Adds a handler to receive events after the target. The handler must be
86   // explicitly removed from the target before the handler is destroyed. The
87   // EventTarget does not take ownership of the handler.
88   void AddPostTargetHandler(EventHandler* handler);
89   void RemovePostTargetHandler(EventHandler* handler);
90 
91   // Returns true if the event pre target list is empty.
92   bool IsPreTargetListEmpty() const;
93 
94   // Sets |target_handler| as |target_handler_| and returns the old handler.
95   EventHandler* SetTargetHandler(EventHandler* target_handler);
96 
HasTargetHandler()97   bool HasTargetHandler() const { return target_handler_ != nullptr; }
98 
99  protected:
target_handler()100   EventHandler* target_handler() { return target_handler_; }
101 
102  private:
103   friend class EventDispatcher;
104   friend class EventTargetTestApi;
105 
106   // A handler with a priority.
107   struct PrioritizedHandler {
108     EventHandler* handler = nullptr;
109     Priority priority = Priority::kDefault;
110 
111     bool operator<(const PrioritizedHandler& ph) const {
112       return priority < ph.priority;
113     }
114   };
115   using EventHandlerPriorityList = std::vector<PrioritizedHandler>;
116 
117   // Returns the list of handlers that should receive the event before the
118   // target. The handlers from the outermost target are first in the list, and
119   // the handlers on |this| are the last in the list.
120   void GetPreTargetHandlers(EventHandlerList* list);
121 
122   // Returns the list of handlers that should receive the event after the
123   // target. The handlers from the outermost target are last in the list, and
124   // the handlers on |this| are the first in the list.
125   void GetPostTargetHandlers(EventHandlerList* list);
126 
127   EventHandlerPriorityList pre_target_list_;
128   EventHandlerList post_target_list_;
129   EventHandler* target_handler_ = nullptr;
130 
131   DISALLOW_COPY_AND_ASSIGN(EventTarget);
132 };
133 
134 }  // namespace ui
135 
136 #endif  // UI_EVENTS_EVENT_TARGET_H_
137