diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
tree | f435a8308119effd964b339f76abb83a57c29483 /gfx/layers/apz/src/FocusState.h | |
parent | Initial commit. (diff) | |
download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'gfx/layers/apz/src/FocusState.h')
-rw-r--r-- | gfx/layers/apz/src/FocusState.h | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/gfx/layers/apz/src/FocusState.h b/gfx/layers/apz/src/FocusState.h new file mode 100644 index 0000000000..4b5ec6b71e --- /dev/null +++ b/gfx/layers/apz/src/FocusState.h @@ -0,0 +1,180 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* vim: set ts=8 sts=2 et sw=2 tw=80: */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#ifndef mozilla_layers_FocusState_h +#define mozilla_layers_FocusState_h + +#include <unordered_map> // for std::unordered_map +#include <unordered_set> // for std::unordered_set + +#include "mozilla/layers/FocusTarget.h" // for FocusTarget +#include "mozilla/layers/ScrollableLayerGuid.h" // for ViewID +#include "mozilla/Mutex.h" // for Mutex + +namespace mozilla { +namespace layers { + +/** + * This class is used for tracking chrome and content focus targets and + * calculating global focus information from them for use by APZCTreeManager + * for async keyboard scrolling. + * + * # Calculating the element to scroll + * + * Chrome and content processes have independently focused elements. This makes + * it difficult to calculate the global focused element and its scrollable + * frame from the chrome or content side. So instead we send the local focus + * information from each process to here and then calculate the global focus + * information. This local information resides in a `focus target`. + * + * A focus target indicates that either: + * 1. The focused element is a remote browser along with its layer tree ID + * 2. The focused element is not scrollable + * 3. The focused element is scrollable along with the ViewID's of its + scrollable layers + * + * Using this information we can determine the global focus information by + * starting at the focus target of the root layer tree ID and following remote + * browsers until we reach a scrollable or non-scrollable focus target. + * + * # Determinism and sequence numbers + * + * The focused element in content can be changed within any javascript code. And + * javascript can run in response to an event or at any moment from `setTimeout` + * and others. This makes it impossible to always have the current focus + * information in APZ as it can be changed asynchronously at any moment. If we + * don't have the latest focus information, we may incorrectly scroll a target + * when we shouldn't. + * + * A tradeoff is designed here whereby we will maintain deterministic focus + * changes for user input, but not for other javascript code. The reasoning + * here is that `setTimeout` and others are already non-deterministic and so it + * might not be as breaking to web content. + * + * To maintain deterministic focus changes for a given stream of user inputs, + * we invalidate our focus state whenever we receive a user input that may + * trigger event listeners. We then attach a new sequence number to these + * events and dispatch them to content. Content will then include the latest + * sequence number it has processed to every focus update. Using this we can + * determine whether any potentially focus changing events have yet to be + * handled by content. + * + * Once we have received the latest focus sequence number from content, we know + * that all event listeners triggered by user inputs, and their resulting focus + * changes, have been processed and so we have a current target that we can use + * again. + */ +class FocusState final { + public: + FocusState(); + + /** + * The sequence number of the last potentially focus changing event processed + * by APZ. This number starts at one and increases monotonically. This number + * will never be zero as that is used to catch uninitialized focus sequence + * numbers on input events. + */ + uint64_t LastAPZProcessedEvent() const; + + /** + * Notify focus state of a potentially focus changing event. This will + * increment the current focus sequence number. The new value can be gotten + * from LastAPZProcessedEvent(). + */ + void ReceiveFocusChangingEvent(); + + /** + * Update the internal focus tree and recalculate the global focus target for + * a focus target update received from chrome or content. + * + * @param aRootLayerTreeId the layer tree ID of the root layer for the + parent APZCTreeManager + * @param aOriginatingLayersId the layer tree ID that this focus target + belongs to + */ + void Update(LayersId aRootLayerTreeId, LayersId aOriginatingLayersId, + const FocusTarget& aTarget); + + /** + * Removes a focus target by its layer tree ID. + */ + void RemoveFocusTarget(LayersId aLayersId); + + /** + * Gets the scrollable layer that should be horizontally scrolled for a key + * event, if any. The returned ScrollableLayerGuid doesn't contain a + * presShellId, and so it should not be used in comparisons. + * + * No scrollable layer is returned if any of the following are true: + * 1. We don't have a current focus target + * 2. There are event listeners that could change the focus + * 3. The target has not been layerized + */ + Maybe<ScrollableLayerGuid> GetHorizontalTarget() const; + /** + * The same as GetHorizontalTarget() but for vertical scrolling. + */ + Maybe<ScrollableLayerGuid> GetVerticalTarget() const; + + /** + * Gets whether it is safe to not increment the focus sequence number for an + * unmatched keyboard event. + */ + bool CanIgnoreKeyboardShortcutMisses() const; + + /** + * Reset to initial state. + */ + void Reset(); + + private: + /** + * Whether the current focus state is known to be current or else if an event + * has been processed that could change the focus but we have not received an + * update with a new confirmed target. + * This can only be called by methods that have already acquired mMutex; they + * have to pass their lock as compile-time proof. + */ + bool IsCurrent(const MutexAutoLock& aLock) const; + + private: + // All methods should hold this lock, since this class is accessed via both + // the updater and controller threads. + mutable Mutex mMutex MOZ_UNANNOTATED; + + // The set of focus targets received indexed by their layer tree ID + std::unordered_map<LayersId, FocusTarget, LayersId::HashFn> mFocusTree; + + // The focus sequence number of the last potentially focus changing event + // processed by APZ. This number starts at one and increases monotonically. + // We don't worry about wrap around here because at a pace of 100 + // increments/sec, it would take 5.85*10^9 years before we would wrap around. + // This number will never be zero as that is used to catch uninitialized focus + // sequence numbers on input events. + uint64_t mLastAPZProcessedEvent; + // The focus sequence number last received in a focus update. + uint64_t mLastContentProcessedEvent; + + // A flag whether there is a key listener on the event target chain for the + // focused element + bool mFocusHasKeyEventListeners; + // A flag that is false until the first call to Update(). + bool mReceivedUpdate; + + // The layer tree ID which contains the scrollable frame of the focused + // element + LayersId mFocusLayersId; + // The scrollable layer corresponding to the scrollable frame that is used to + // scroll the focused element. This depends on the direction the user is + // scrolling. + ScrollableLayerGuid::ViewID mFocusHorizontalTarget; + ScrollableLayerGuid::ViewID mFocusVerticalTarget; +}; + +} // namespace layers +} // namespace mozilla + +#endif // mozilla_layers_FocusState_h |