Bug 1860328 - Track nsCaret position at the DOM level. r=sefeng,masayuki
[gecko.git] / layout / base / nsCaret.h
blob2d938c35a5c6bc19efe9b775475a89bca98c7ce9
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 /* the caret is the text cursor used, e.g., when editing */
9 #ifndef nsCaret_h__
10 #define nsCaret_h__
12 #include "mozilla/MemoryReporting.h"
13 #include "mozilla/SelectionMovementUtils.h"
14 #include "nsCoord.h"
15 #include "nsIFrame.h"
16 #include "nsISelectionListener.h"
17 #include "nsIWeakReferenceUtils.h"
18 #include "nsPoint.h"
19 #include "nsRect.h"
21 class nsFrameSelection;
22 class nsIContent;
23 class nsIFrame;
24 class nsINode;
25 class nsITimer;
27 namespace mozilla {
28 class PresShell;
29 enum class CaretAssociationHint;
30 namespace gfx {
31 class DrawTarget;
32 } // namespace gfx
33 } // namespace mozilla
35 //-----------------------------------------------------------------------------
36 class nsCaret final : public nsISelectionListener {
37 typedef mozilla::gfx::DrawTarget DrawTarget;
39 public:
40 nsCaret();
42 protected:
43 virtual ~nsCaret();
45 public:
46 NS_DECL_ISUPPORTS
48 using CaretAssociationHint = mozilla::CaretAssociationHint;
50 nsresult Init(mozilla::PresShell*);
51 void Terminate();
53 void SetSelection(mozilla::dom::Selection*);
54 mozilla::dom::Selection* GetSelection();
56 /**
57 * Sets whether the caret should only be visible in nodes that are not
58 * user-modify: read-only, or whether it should be visible in all nodes.
60 * @param aIgnoreUserModify true to have the cursor visible in all nodes,
61 * false to have it visible in all nodes except
62 * those with user-modify: read-only
64 void SetIgnoreUserModify(bool aIgnoreUserModify);
65 /** SetVisible will set the visibility of the caret
66 * @param inMakeVisible true to show the caret, false to hide it
68 void SetVisible(bool aVisible);
69 /** IsVisible will get the visibility of the caret.
70 * This returns false if the caret is hidden because it was set
71 * to not be visible, or because the selection is not collapsed, or
72 * because an open popup is hiding the caret.
73 * It does not take account of blinking or the caret being hidden
74 * because we're in non-editable/disabled content.
76 bool IsVisible();
78 /**
79 * AddForceHide() increases mHideCount and hide the caret even if
80 * SetVisible(true) has been or will be called. This is useful when the
81 * caller wants to hide caret temporarily and it needs to cancel later.
82 * Especially, in the latter case, it's too difficult to decide if the
83 * caret should be actually visible or not because caret visible state
84 * is set from a lot of event handlers. So, it's very stateful.
86 void AddForceHide();
87 /**
88 * RemoveForceHide() decreases mHideCount if it's over 0.
89 * If the value becomes 0, this may show the caret if SetVisible(true)
90 * has been called.
92 void RemoveForceHide();
93 /** SetCaretReadOnly set the appearance of the caret
94 * @param inMakeReadonly true to show the caret in a 'read only' state,
95 * false to show the caret in normal, editing state
97 void SetCaretReadOnly(bool aReadOnly);
98 /**
99 * @param aVisibility true if the caret should be visible even when the
100 * selection is not collapsed.
102 void SetVisibilityDuringSelection(bool aVisibility);
105 * Set the caret's position explicitly to the specified node and offset
106 * instead of tracking its selection.
107 * Passing null for aNode would set the caret to track its selection again.
109 void SetCaretPosition(nsINode* aNode, int32_t aOffset);
112 * Schedule a repaint for the frame where the caret would appear.
113 * Does not check visibility etc.
115 void SchedulePaint();
118 * Returns a frame to paint in, and the bounds of the painted caret
119 * relative to that frame.
120 * The rectangle includes bidi decorations.
121 * Returns null if the caret should not be drawn (including if it's blinked
122 * off).
124 nsIFrame* GetPaintGeometry(nsRect* aRect);
126 * Same as the overload above, but returns the caret and hook rects
127 * separately, and also computes the color if requested.
129 nsIFrame* GetPaintGeometry(nsRect* aCaretRect, nsRect* aHookRect,
130 nscolor* aCaretColor = nullptr);
132 * A simple wrapper around GetGeometry. Does not take any caret state into
133 * account other than the current selection.
135 nsIFrame* GetGeometry(nsRect* aRect) {
136 return GetGeometry(GetSelection(), aRect);
139 /** PaintCaret
140 * Actually paint the caret onto the given rendering context.
142 void PaintCaret(DrawTarget& aDrawTarget, nsIFrame* aForFrame,
143 const nsPoint& aOffset);
145 // nsISelectionListener interface
146 NS_DECL_NSISELECTIONLISTENER
148 /** The current caret position. */
149 struct CaretPosition {
150 nsCOMPtr<nsINode> mContent;
151 int32_t mOffset = 0;
152 CaretAssociationHint mHint{0};
153 mozilla::intl::BidiEmbeddingLevel mBidiLevel;
155 bool operator==(const CaretPosition& aOther) const {
156 return mContent == aOther.mContent && mOffset == aOther.mOffset &&
157 mHint == aOther.mHint && mBidiLevel == aOther.mBidiLevel;
159 explicit operator bool() const { return !!mContent; }
162 static CaretPosition CaretPositionFor(const mozilla::dom::Selection*);
165 * Gets the position and size of the caret that would be drawn for
166 * the focus node/offset of aSelection (assuming it would be drawn,
167 * i.e., disregarding blink status). The geometry is stored in aRect,
168 * and we return the frame aRect is relative to.
169 * Only looks at the focus node of aSelection, so you can call it even if
170 * aSelection is not collapsed.
171 * This rect does not include any extra decorations for bidi.
172 * @param aRect must be non-null
174 static nsIFrame* GetGeometry(const mozilla::dom::Selection* aSelection,
175 nsRect* aRect);
177 static nsRect GetGeometryForFrame(nsIFrame* aFrame, int32_t aFrameOffset,
178 nscoord* aBidiIndicatorSize);
180 // Get the frame and frame offset based on aPosition.
181 static mozilla::CaretFrameData GetFrameAndOffset(
182 const CaretPosition& aPosition);
184 size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf) const;
186 protected:
187 static void CaretBlinkCallback(nsITimer* aTimer, void* aClosure);
189 void CheckSelectionLanguageChange();
191 void ResetBlinking();
192 void StopBlinking();
194 struct Metrics {
195 nscoord mBidiIndicatorSize; // width and height of bidi indicator
196 nscoord mCaretWidth; // full caret width including bidi indicator
198 static Metrics ComputeMetrics(nsIFrame* aFrame, int32_t aOffset,
199 nscoord aCaretHeight);
200 void ComputeCaretRects(nsIFrame* aFrame, int32_t aFrameOffset,
201 nsRect* aCaretRect, nsRect* aHookRect);
203 // Returns true if we should not draw the caret because of XUL menu popups.
204 // The caret should be hidden if:
205 // 1. An open popup contains the caret, but a menu popup exists before the
206 // caret-owning popup in the popup list (i.e. a menu is in front of the
207 // popup with the caret). If the menu itself contains the caret we don't
208 // hide it.
209 // 2. A menu popup is open, but there is no caret present in any popup.
210 // 3. The caret selection is empty.
211 bool IsMenuPopupHidingCaret();
213 // If we're tracking the selection, this updates the caret position and
214 // invalidates paint as needed.
215 void UpdateCaretPositionFromSelectionIfNeeded();
217 nsWeakPtr mPresShell;
218 mozilla::WeakPtr<mozilla::dom::Selection> mDomSelectionWeak;
220 nsCOMPtr<nsITimer> mBlinkTimer;
222 CaretPosition mCaretPosition;
225 * mBlinkCount is used to control the number of times to blink the caret
226 * before stopping the blink. This is reset each time we reset the
227 * blinking.
229 int32_t mBlinkCount = -1;
231 * mBlinkRate is the rate of the caret blinking the last time we read it.
232 * It is used as a way to optimize whether we need to reset the blinking
233 * timer. 0 or a negative value means no blinking.
235 int32_t mBlinkRate = 0;
237 * mHideCount is not 0, it means that somebody doesn't want the caret
238 * to be visible. See AddForceHide() and RemoveForceHide().
240 uint32_t mHideCount = 0;
243 * mIsBlinkOn is true when we're in a blink cycle where the caret is on.
245 bool mIsBlinkOn = false;
247 * mIsVisible is true when SetVisible was last called with 'true'.
249 bool mVisible = false;
251 * mReadOnly is true when the caret is set to "read only" mode (i.e.,
252 * it doesn't blink).
254 bool mReadOnly = false;
256 * mShowDuringSelection is true when the caret should be shown even when
257 * the selection is not collapsed.
259 bool mShowDuringSelection = false;
261 * mIgnoreUserModify is true when the caret should be shown even when
262 * it's in non-user-modifiable content.
264 bool mIgnoreUserModify = true;
267 * If the caret position is fixed, it's been overridden externally and it
268 * will not track the selection.
270 bool mFixedCaretPosition = false;
273 #endif // nsCaret_h__