Bug 1856663 - Add more chunks for Android mochitest-plain. r=jmaher,taskgraph-reviewe...
[gecko.git] / layout / base / AccessibleCaret.h
blob120cfc47fa0062772a16826b64a5120814c58cf9
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/. */
7 #ifndef AccessibleCaret_h__
8 #define AccessibleCaret_h__
10 #include "mozilla/Attributes.h"
11 #include "mozilla/dom/AnonymousContent.h"
12 #include "nsCOMPtr.h"
13 #include "nsIDOMEventListener.h"
14 #include "nsIFrame.h" // for WeakFrame only
15 #include "nsISupports.h"
16 #include "nsISupportsImpl.h"
17 #include "nsLiteralString.h"
18 #include "nsRect.h"
19 #include "mozilla/RefPtr.h"
20 #include "nsString.h"
22 class nsIFrame;
23 struct nsPoint;
25 namespace mozilla {
26 class PresShell;
27 namespace dom {
28 class Element;
29 class Event;
30 } // namespace dom
32 // -----------------------------------------------------------------------------
33 // Upon the creation of AccessibleCaret, it will insert DOM Element as an
34 // anonymous content containing the caret image. The caret appearance and
35 // position can be controlled by SetAppearance() and SetPosition().
37 // All the rect or point are relative to root frame except being specified
38 // explicitly.
40 // None of the methods in AccessibleCaret will flush layout or style. To ensure
41 // that SetPosition() works correctly, the caller must make sure the layout is
42 // up to date.
44 // Please see the wiki page for more information.
45 // https://wiki.mozilla.org/AccessibleCaret
47 class AccessibleCaret {
48 public:
49 explicit AccessibleCaret(PresShell* aPresShell);
50 virtual ~AccessibleCaret();
52 // This enumeration representing the visibility and visual style of an
53 // AccessibleCaret.
55 // Use SetAppearance() to change the appearance, and use GetAppearance() to
56 // get the current appearance.
57 enum class Appearance : uint8_t {
58 // Do not display the caret at all.
59 None,
61 // Display the caret in default style.
62 Normal,
64 // The caret should be displayed logically but it is kept invisible to the
65 // user. This enum is the only difference between "logically visible" and
66 // "visually visible". It can be used for reasons such as:
67 // 1. Out of scroll port.
68 // 2. For UX requirement such as hide a caret in an empty text area.
69 NormalNotShown,
71 // Display the caret which is tilted to the left.
72 Left,
74 // Display the caret which is tilted to the right.
75 Right
78 friend std::ostream& operator<<(std::ostream& aStream,
79 const Appearance& aAppearance);
81 Appearance GetAppearance() const { return mAppearance; }
83 virtual void SetAppearance(Appearance aAppearance);
85 // Return true if current appearance is either Normal, NormalNotShown, Left,
86 // or Right.
87 bool IsLogicallyVisible() const { return mAppearance != Appearance::None; }
89 // Return true if current appearance is either Normal, Left, or Right.
90 bool IsVisuallyVisible() const {
91 return (mAppearance != Appearance::None) &&
92 (mAppearance != Appearance::NormalNotShown);
95 // This enum represents the result returned by SetPosition().
96 enum class PositionChangedResult : uint8_t {
97 // Both position and the zoom level are not changed.
98 NotChanged,
100 // The position is changed. (The zoom level may or may not be changed.)
101 Position,
103 // Only the zoom level is changed. The position is *not* changed.
104 Zoom,
106 // The position is out of scroll port.
107 Invisible
110 friend std::ostream& operator<<(std::ostream& aStream,
111 const PositionChangedResult& aResult);
113 virtual PositionChangedResult SetPosition(nsIFrame* aFrame, int32_t aOffset);
115 // Does two AccessibleCarets overlap?
116 bool Intersects(const AccessibleCaret& aCaret) const;
118 // Is the point within the caret's rect? The point should be relative to root
119 // frame.
120 enum class TouchArea {
121 Full, // Contains both text overlay and caret image.
122 CaretImage
124 bool Contains(const nsPoint& aPoint, TouchArea aTouchArea) const;
126 // The geometry center of the imaginary caret (nsCaret) to which this
127 // AccessibleCaret is attached. It is needed when dragging the caret.
128 nsPoint LogicalPosition() const { return mImaginaryCaretRect.Center(); }
130 // Element for 'Intersects' test. This is the container of the caret image
131 // and text-overlay elements. See CreateCaretElement() for the content
132 // structure.
133 dom::Element& CaretElement() const { return *mCaretElementHolder->Host(); }
135 // Ensures that the caret element is made "APZ aware" so that the APZ code
136 // doesn't scroll the page when the user is trying to drag the caret.
137 void EnsureApzAware();
139 bool IsInPositionFixedSubtree() const;
141 protected:
142 // Argument aRect should be relative to CustomContentContainerFrame().
143 void SetCaretElementStyle(const nsRect& aRect, float aZoomLevel);
144 void SetTextOverlayElementStyle(const nsRect& aRect, float aZoomLevel);
145 void SetCaretImageElementStyle(const nsRect& aRect, float aZoomLevel);
147 // Get current zoom level.
148 float GetZoomLevel();
150 // Element which contains the text overly for the 'Contains' test.
151 dom::Element* TextOverlayElement() const;
153 // Element which contains the caret image for 'Contains' test.
154 dom::Element* CaretImageElement() const;
156 nsIFrame* RootFrame() const;
158 nsIFrame* CustomContentContainerFrame() const;
160 // Transform Appearance to CSS id used in ua.css.
161 static nsAutoString AppearanceString(Appearance aAppearance);
163 void CreateCaretElement() const;
165 // Inject caret element into custom content container.
166 void InjectCaretElement(dom::Document*);
168 // Remove caret element from custom content container.
169 void RemoveCaretElement(dom::Document*);
171 // Clear the cached rects and zoom level.
172 void ClearCachedData();
174 // The top-center of the imaginary caret to which this AccessibleCaret is
175 // attached.
176 static nsPoint CaretElementPosition(const nsRect& aRect) {
177 return aRect.TopLeft() + nsPoint(aRect.width / 2, 0);
180 class DummyTouchListener final : public nsIDOMEventListener {
181 public:
182 NS_DECL_ISUPPORTS
183 NS_IMETHOD HandleEvent(mozilla::dom::Event* aEvent) override {
184 return NS_OK;
187 private:
188 virtual ~DummyTouchListener() = default;
191 // Member variables
192 Appearance mAppearance = Appearance::None;
194 // AccessibleCaretManager owns us by a UniquePtr. When it's terminated by
195 // AccessibleCaretEventHub::Terminate() which is called in
196 // PresShell::Destroy(), it frees us automatically. No need to worry if we
197 // outlive mPresShell.
198 PresShell* const MOZ_NON_OWNING_REF mPresShell = nullptr;
200 RefPtr<dom::AnonymousContent> mCaretElementHolder;
202 // This cached rect is relative to the root frame, and is used in
203 // LogicalPosition() when dragging a caret.
204 nsRect mImaginaryCaretRect;
206 // This cached rect is relative to the custom content container, and is used
207 // in SetPosition() to check whether the caret position has changed.
208 nsRect mImaginaryCaretRectInContainerFrame;
210 // The reference frame we used to calculate mImaginaryCaretRect and
211 // mImaginaryCaretRectInContainerFrame.
212 WeakFrame mImaginaryCaretReferenceFrame;
214 // Cache current zoom level to determine whether position is changed.
215 float mZoomLevel = 0.0f;
217 // A no-op touch-start listener which prevents APZ from panning when dragging
218 // the caret.
219 RefPtr<DummyTouchListener> mDummyTouchListener{new DummyTouchListener()};
220 }; // class AccessibleCaret
222 std::ostream& operator<<(std::ostream& aStream,
223 const AccessibleCaret::Appearance& aAppearance);
225 std::ostream& operator<<(std::ostream& aStream,
226 const AccessibleCaret::PositionChangedResult& aResult);
228 } // namespace mozilla
230 #endif // AccessibleCaret_h__