blob: 61a675acb88de5b25a2c436e0d34c26743e4d2fd [file] [log] [blame]
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <memory>
#include "base/macros.h"
#include "base/memory/weak_ptr.h"
#include "ui/events/event_dispatcher.h"
#include "ui/events/events_export.h"
namespace ui {
class Event;
class EventRewriterContinuation;
class EventSource; // TODO(kpschoedel): Remove with old API.
// Return status of EventRewriter operations; see that class below.
// TODO(kpschoedel): Remove old API.
enum EventRewriteStatus {
// Nothing was done; no rewritten event returned. Pass the original
// event to later rewriters, or send it to the EventSink if this
// was the final rewriter.
// TODO(kpschoedel): Replace old API uses of
// with new API
// return SendEvent(continuation, &incoming_event);
// The event has been rewritten. Send the rewritten event to the
// EventSink instead of the original event (without sending
// either to any later rewriters).
// TODO(kpschoedel): Replace old API uses of
// *rewritten_event = std::move(replacement_event);
// with new API
// return SendEventFinally(continuation, replacement_event);
// The event should be discarded, neither passing it to any later
// rewriters nor sending it to the EventSink.
// TODO(kpschoedel): Replace old API uses of
// with new API
// return DiscardEvent(continuation);
// The event has been rewritten. As for EVENT_REWRITE_REWRITTEN,
// send the rewritten event to the EventSink instead of the original
// event (without sending either to any later rewriters).
// In addition the rewriter has one or more additional new events
// to be retrieved using |NextDispatchEvent()| and sent to the
// EventSink.
// TODO(kpschoedel): Replace old API uses of
// *rewritten_event = std::move(new_event_1);
// // record new_event_2 … new_event_N
// with new API
// details = SendEventFinally(new_event_1);
// ⋮
// return SendEventFinally(new_event_N);
// EventRewriter provides a mechanism for Events to be rewritten
// before being dispatched from EventSource to EventSink.
class EVENTS_EXPORT EventRewriter {
// Copyable opaque type, to be used only as an argument to SendEvent(),
// SendEventFinally(), or DiscardEvent(). The current implementation is
// a WeakPtr because some EventRewriters outlive their registration and
// can try to send events through an absent source (e.g. from a timer).
using Continuation = base::WeakPtr<EventRewriterContinuation>;
EventRewriter() = default;
virtual ~EventRewriter() = default;
// Potentially rewrites (replaces) an event, possibly with multiple events,
// or causes it to be discarded.
// To accept the supplied event without change,
// return SendEvent(continuation, &event)
// To replace the supplied event with a new event, call either
// return SendEvent(continuation, new_event)
// or
// return SendEventFinally(continuation, new_event)
// depending on whether or not |new_event| should be provided to any
// later rewriters. These functions can be called more than once to
// replace an incoming event with multiple new events; when doing so,
// check |details.dispatcher_destroyed| after each call.
// To discard the incoming event without replacement,
// return DiscardEvent()
// In the common case of one event at a time, the EventDispatchDetails
// from the above calls can and should be returned directly by RewriteEvent().
// When a rewriter generates multiple events synchronously, it should
// typically bail and return on a non-vacuous EventDispatchDetails.
// When a rewriter generates events asynchronously (e.g. from a timer)
// there is no opportunity to return the result directly, but a rewriter
// can consider retaining it for the next call.
// The supplied WeakPtr<Continuation> can be saved in order to respond
// asynchronously, e.g. after a double-click timeout. Normally, with
// EventRewriters subordinate to EventSources, the Continuation lives as
// long as the EventRewriter remains registered. If the continuation is not
// valid, the Send functions will return with |details.dispatcher_destroyed|.
// Design note: We need to pass the continuation state explicitly because
// Ash registers some EventRewriter instances with multiple EventSources.
virtual EventDispatchDetails RewriteEvent(const Event& event,
const Continuation continuation);
// Potentially rewrites (replaces) an event, or requests it be discarded.
// or discards an event. If the rewriter wants to rewrite an event, and
// dispatch another event once the rewritten event is dispatched, it should
// return EVENT_REWRITE_DISPATCH_ANOTHER, and return the next event to
// dispatch from |NextDispatchEvent()|.
// TODO(kpschoedel): Remove old API.
virtual EventRewriteStatus RewriteEvent(
const Event& event,
std::unique_ptr<Event>* rewritten_event);
// Supplies an additional event to be dispatched. It is only valid to
// call this after the immediately previous call to |RewriteEvent()|
// or |NextDispatchEvent()| has returned EVENT_REWRITE_DISPATCH_ANOTHER.
// Should only return either EVENT_REWRITE_REWRITTEN or
// EVENT_REWRITE_DISPATCH_ANOTHER; otherwise the previous call should not
// TODO(kpschoedel): Remove old API.
virtual EventRewriteStatus NextDispatchEvent(
const Event& last_event,
std::unique_ptr<Event>* new_event);
// Forwards an event, through any subsequent rewriters.
static EventDispatchDetails SendEvent(const Continuation continuation,
const Event* event) WARN_UNUSED_RESULT;
// Forwards an event, skipping any subsequent rewriters.
static EventDispatchDetails SendEventFinally(const Continuation continuation,
const Event* event)
// Discards an event, so that it will not be passed to the sink.
static EventDispatchDetails DiscardEvent(const Continuation continuation)
// A helper that calls a protected EventSource function, which sends the event
// to subsequent event rewriters on the source and onto its event sink.
// TODO(kpschoedel): Replace with SendEvent(continuation, event).
EventDispatchDetails SendEventToEventSource(EventSource* source,
Event* event) const;
} // namespace ui