event_rewriter.h 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. // Copyright 2014 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. #ifndef UI_EVENTS_EVENT_REWRITER_H_
  5. #define UI_EVENTS_EVENT_REWRITER_H_
  6. #include <memory>
  7. #include "base/memory/weak_ptr.h"
  8. #include "ui/events/event_dispatcher.h"
  9. #include "ui/events/events_export.h"
  10. namespace ui {
  11. class Event;
  12. class EventRewriterContinuation;
  13. class EventSource; // TODO(kpschoedel): Remove with old API.
  14. // Return status of EventRewriter operations; see that class below.
  15. // TODO(kpschoedel): Remove old API.
  16. enum EventRewriteStatus {
  17. // Nothing was done; no rewritten event returned. Pass the original
  18. // event to later rewriters, or send it to the EventSink if this
  19. // was the final rewriter.
  20. //
  21. // TODO(kpschoedel): Replace old API uses of
  22. // return EVENT_REWRITE_CONTINUE;
  23. // with new API
  24. // return SendEvent(continuation, &incoming_event);
  25. EVENT_REWRITE_CONTINUE,
  26. // The event has been rewritten. Send the rewritten event to the
  27. // EventSink instead of the original event (without sending
  28. // either to any later rewriters).
  29. //
  30. // TODO(kpschoedel): Replace old API uses of
  31. // *rewritten_event = std::move(replacement_event);
  32. // return EVENT_REWRITE_REWRITTEN;
  33. // with new API
  34. // return SendEventFinally(continuation, replacement_event);
  35. EVENT_REWRITE_REWRITTEN,
  36. // The event should be discarded, neither passing it to any later
  37. // rewriters nor sending it to the EventSink.
  38. //
  39. // TODO(kpschoedel): Replace old API uses of
  40. // return EVENT_REWRITE_DISCARD;
  41. // with new API
  42. // return DiscardEvent(continuation);
  43. EVENT_REWRITE_DISCARD,
  44. // The event has been rewritten. As for EVENT_REWRITE_REWRITTEN,
  45. // send the rewritten event to the EventSink instead of the original
  46. // event (without sending either to any later rewriters).
  47. // In addition the rewriter has one or more additional new events
  48. // to be retrieved using |NextDispatchEvent()| and sent to the
  49. // EventSink.
  50. //
  51. // TODO(kpschoedel): Replace old API uses of
  52. // *rewritten_event = std::move(new_event_1);
  53. // // record new_event_2 … new_event_N
  54. // return EVENT_REWRITE_DISPATCH_ANOTHER;
  55. // with new API
  56. // details = SendEventFinally(new_event_1);
  57. // ⋮
  58. // return SendEventFinally(new_event_N);
  59. EVENT_REWRITE_DISPATCH_ANOTHER,
  60. };
  61. // EventRewriter provides a mechanism for Events to be rewritten
  62. // before being dispatched from EventSource to EventSink.
  63. class EVENTS_EXPORT EventRewriter {
  64. public:
  65. // Copyable opaque type, to be used only as an argument to SendEvent(),
  66. // SendEventFinally(), or DiscardEvent(). The current implementation is
  67. // a WeakPtr because some EventRewriters outlive their registration and
  68. // can try to send events through an absent source (e.g. from a timer).
  69. using Continuation = base::WeakPtr<EventRewriterContinuation>;
  70. EventRewriter() = default;
  71. EventRewriter(const EventRewriter&) = delete;
  72. EventRewriter& operator=(const EventRewriter&) = delete;
  73. virtual ~EventRewriter() = default;
  74. // Potentially rewrites (replaces) an event, possibly with multiple events,
  75. // or causes it to be discarded.
  76. //
  77. // To accept the supplied event without change,
  78. // return SendEvent(continuation, &event)
  79. //
  80. // To replace the supplied event with a new event, call either
  81. // return SendEvent(continuation, new_event)
  82. // or
  83. // return SendEventFinally(continuation, new_event)
  84. // depending on whether or not |new_event| should be provided to any
  85. // later rewriters. These functions can be called more than once to
  86. // replace an incoming event with multiple new events; when doing so,
  87. // check |details.dispatcher_destroyed| after each call.
  88. //
  89. // To discard the incoming event without replacement,
  90. // return DiscardEvent()
  91. //
  92. // In the common case of one event at a time, the EventDispatchDetails
  93. // from the above calls can and should be returned directly by RewriteEvent().
  94. // When a rewriter generates multiple events synchronously, it should
  95. // typically bail and return on a non-vacuous EventDispatchDetails.
  96. // When a rewriter generates events asynchronously (e.g. from a timer)
  97. // there is no opportunity to return the result directly, but a rewriter
  98. // can consider retaining it for the next call.
  99. //
  100. // The supplied WeakPtr<Continuation> can be saved in order to respond
  101. // asynchronously, e.g. after a double-click timeout. Normally, with
  102. // EventRewriters subordinate to EventSources, the Continuation lives as
  103. // long as the EventRewriter remains registered. If the continuation is not
  104. // valid, the Send functions will return with |details.dispatcher_destroyed|.
  105. //
  106. // Design note: We need to pass the continuation state explicitly because
  107. // Ash registers some EventRewriter instances with multiple EventSources.
  108. //
  109. virtual EventDispatchDetails RewriteEvent(const Event& event,
  110. const Continuation continuation);
  111. // Potentially rewrites (replaces) an event, or requests it be discarded.
  112. // or discards an event. If the rewriter wants to rewrite an event, and
  113. // dispatch another event once the rewritten event is dispatched, it should
  114. // return EVENT_REWRITE_DISPATCH_ANOTHER, and return the next event to
  115. // dispatch from |NextDispatchEvent()|.
  116. // TODO(kpschoedel): Remove old API.
  117. virtual EventRewriteStatus RewriteEvent(
  118. const Event& event,
  119. std::unique_ptr<Event>* rewritten_event);
  120. // Supplies an additional event to be dispatched. It is only valid to
  121. // call this after the immediately previous call to |RewriteEvent()|
  122. // or |NextDispatchEvent()| has returned EVENT_REWRITE_DISPATCH_ANOTHER.
  123. // Should only return either EVENT_REWRITE_REWRITTEN or
  124. // EVENT_REWRITE_DISPATCH_ANOTHER; otherwise the previous call should not
  125. // have returned EVENT_REWRITE_DISPATCH_ANOTHER.
  126. // TODO(kpschoedel): Remove old API.
  127. virtual EventRewriteStatus NextDispatchEvent(
  128. const Event& last_event,
  129. std::unique_ptr<Event>* new_event);
  130. protected:
  131. // Forwards an event, through any subsequent rewriters.
  132. [[nodiscard]] static EventDispatchDetails SendEvent(
  133. const Continuation continuation,
  134. const Event* event);
  135. // Forwards an event, skipping any subsequent rewriters.
  136. [[nodiscard]] static EventDispatchDetails SendEventFinally(
  137. const Continuation continuation,
  138. const Event* event);
  139. // Discards an event, so that it will not be passed to the sink.
  140. [[nodiscard]] static EventDispatchDetails DiscardEvent(
  141. const Continuation continuation);
  142. // A helper that calls a protected EventSource function, which sends the event
  143. // to subsequent event rewriters on the source and onto its event sink.
  144. // TODO(kpschoedel): Replace with SendEvent(continuation, event).
  145. EventDispatchDetails SendEventToEventSource(EventSource* source,
  146. Event* event) const;
  147. };
  148. } // namespace ui
  149. #endif // UI_EVENTS_EVENT_REWRITER_H_