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 AccessibleCaretManager_h
8 #define AccessibleCaretManager_h
10 #include "AccessibleCaret.h"
12 #include "mozilla/dom/CaretStateChangedEvent.h"
13 #include "mozilla/dom/MouseEventBinding.h"
14 #include "mozilla/EnumSet.h"
15 #include "mozilla/EventForwards.h"
16 #include "mozilla/RefPtr.h"
17 #include "mozilla/UniquePtr.h"
21 #include "nsISelectionListener.h"
23 class nsFrameSelection
;
35 // -----------------------------------------------------------------------------
36 // AccessibleCaretManager does not deal with events or callbacks directly. It
37 // relies on AccessibleCaretEventHub to call its public methods to do the work.
38 // All codes needed to interact with PresShell, Selection, and AccessibleCaret
39 // should be written in AccessibleCaretManager.
41 // None the public methods in AccessibleCaretManager will flush layout or style
42 // prior to performing its task. The caller must ensure the layout is up to
45 // Please see the wiki page for more information.
46 // https://wiki.mozilla.org/AccessibleCaret
48 class AccessibleCaretManager
{
50 explicit AccessibleCaretManager(PresShell
* aPresShell
);
51 virtual ~AccessibleCaretManager();
53 // Called by AccessibleCaretEventHub to inform us that PresShell is destroyed.
56 // The aPoint in the following public methods should be relative to root
59 // Press caret on the given point. Return NS_OK if the point is actually on
62 virtual nsresult
PressCaret(const nsPoint
& aPoint
, EventClassID aEventClass
);
64 // Drag caret to the given point. It's required to call PressCaret()
67 virtual nsresult
DragCaret(const nsPoint
& aPoint
);
69 // Release caret from he previous press action. It's required to call
70 // PressCaret() beforehand.
72 virtual nsresult
ReleaseCaret();
74 // A quick single tap on caret on given point without dragging.
76 virtual nsresult
TapCaret(const nsPoint
& aPoint
);
78 // Select a word or bring up paste shortcut (if Gaia is listening) under the
81 virtual nsresult
SelectWordOrShortcut(const nsPoint
& aPoint
);
83 // Handle scroll-start event.
85 virtual void OnScrollStart();
87 // Handle scroll-end event.
89 virtual void OnScrollEnd();
91 // Handle ScrollPositionChanged from nsIScrollObserver. This might be called
92 // at anytime, not necessary between OnScrollStart and OnScrollEnd.
94 virtual void OnScrollPositionChanged();
96 // Handle reflow event from nsIReflowObserver.
98 virtual void OnReflow();
100 // Handle blur event from nsFocusManager.
102 virtual void OnBlur();
104 // Handle NotifySelectionChanged event from nsISelectionListener.
105 // @param aReason potentially multiple of the reasons defined in
106 // nsISelectionListener.idl.
108 virtual nsresult
OnSelectionChanged(dom::Document
* aDoc
, dom::Selection
* aSel
,
112 virtual void OnKeyboardEvent();
114 // The canvas frame holding the accessible caret anonymous content elements
115 // was reconstructed, resulting in the content elements getting cloned.
116 virtual void OnFrameReconstruction();
118 // Update the manager with the last input source that was observed. This
119 // is used in part to determine if the carets should be shown or hidden.
120 void SetLastInputSource(uint16_t aInputSource
);
122 // Returns True indicating that we should disable APZ to avoid jumpy carets.
123 bool ShouldDisableApz() const { return mShouldDisableApz
; }
126 // This enum representing the number of AccessibleCarets on the screen.
127 enum class CaretMode
: uint8_t {
128 // No caret on the screen.
131 // One caret, i.e. the selection is collapsed.
134 // Two carets, i.e. the selection is not collapsed.
138 friend std::ostream
& operator<<(std::ostream
& aStream
,
139 const CaretMode
& aCaretMode
);
141 enum class UpdateCaretsHint
: uint8_t {
142 // Update everything including appearance and position.
145 // Update everything while respecting the old appearance. For example, if
146 // the caret in cursor mode is hidden due to blur, do not change its
147 // appearance to Normal.
148 RespectOldAppearance
,
150 // No CaretStateChangedEvent will be dispatched in the end of
155 using UpdateCaretsHintSet
= mozilla::EnumSet
<UpdateCaretsHint
>;
157 friend std::ostream
& operator<<(std::ostream
& aStream
,
158 const UpdateCaretsHint
& aResult
);
160 // Update carets based on current selection status. This function will flush
161 // layout, so caller must ensure the PresShell is still valid after calling
165 const UpdateCaretsHintSet
& aHints
= UpdateCaretsHint::Default
);
167 // Force hiding all carets regardless of the current selection status.
172 void UpdateCaretsForCursorMode(const UpdateCaretsHintSet
& aHints
);
175 void UpdateCaretsForSelectionMode(const UpdateCaretsHintSet
& aHints
);
177 // A helper function to update mShouldDisableApz.
178 void UpdateShouldDisableApz();
180 // Provide haptic / touch feedback, primarily for select on longpress.
181 void ProvideHapticFeedback();
183 // Get the nearest enclosing focusable frame of aFrame.
184 // @return focusable frame if there is any; nullptr otherwise.
185 nsIFrame
* GetFocusableFrame(nsIFrame
* aFrame
) const;
187 // Change focus to aFrame if it isn't nullptr. Otherwise, clear the old focus
188 // then re-focus the window.
189 MOZ_CAN_RUN_SCRIPT_BOUNDARY
void ChangeFocusToOrClearOldFocus(
190 nsIFrame
* aFrame
) const;
193 nsresult
SelectWord(nsIFrame
* aFrame
, const nsPoint
& aPoint
) const;
194 void SetSelectionDragState(bool aState
) const;
196 // Return true if the candidate string is a phone number.
197 bool IsPhoneNumber(nsAString
& aCandidate
) const;
199 // Extend the current selection forwards and backwards if it's already a
202 void SelectMoreIfPhoneNumber() const;
204 // Extend the current phone number selection in the requested direction.
206 void ExtendPhoneNumberSelection(const nsAString
& aDirection
) const;
208 void SetSelectionDirection(nsDirection aDir
) const;
210 // If aDirection is eDirNext, get the frame for the range start in the first
211 // range from the current selection, and return the offset into that frame as
212 // well as the range start content and the content offset. Otherwise, get the
213 // frame and the offset for the range end in the last range instead.
214 nsIFrame
* GetFrameForFirstRangeStartOrLastRangeEnd(
215 nsDirection aDirection
, int32_t* aOutOffset
,
216 nsIContent
** aOutContent
= nullptr,
217 int32_t* aOutContentOffset
= nullptr) const;
219 MOZ_CAN_RUN_SCRIPT nsresult
DragCaretInternal(const nsPoint
& aPoint
);
220 nsPoint
AdjustDragBoundary(const nsPoint
& aPoint
) const;
222 // Start the selection scroll timer if the caret is being dragged out of
225 void StartSelectionAutoScrollTimer(const nsPoint
& aPoint
) const;
226 void StopSelectionAutoScrollTimer() const;
228 void ClearMaintainedSelection() const;
230 // This method could kill the shell, so callers to methods that call
231 // FlushLayout should ensure the event hub that owns us is still alive.
233 // See the mRefCnt assertions in AccessibleCaretEventHub.
235 // Returns whether mPresShell we're holding is still valid.
236 [[nodiscard
]] MOZ_CAN_RUN_SCRIPT
bool FlushLayout();
238 dom::Element
* GetEditingHostForFrame(nsIFrame
* aFrame
) const;
239 dom::Selection
* GetSelection() const;
240 already_AddRefed
<nsFrameSelection
> GetFrameSelection() const;
243 nsAutoString
StringifiedSelection() const;
245 // Get the union of all the child frame scrollable overflow rects for aFrame,
246 // which is used as a helper function to restrict the area where the caret can
247 // be dragged. Returns the rect relative to aFrame.
248 nsRect
GetAllChildFrameRectsUnion(nsIFrame
* aFrame
) const;
250 // Restrict the active caret's dragging position based on
251 // sCaretsAllowDraggingAcrossOtherCaret. If the active caret is the first
252 // caret, the `limit` will be the previous character of the second caret.
253 // Otherwise, the `limit` will be the next character of the first caret.
255 // @param aOffsets is the new position of the active caret, and it will be set
256 // to the `limit` when 1) sCaretsAllowDraggingAcrossOtherCaret is false and
257 // it's being dragged past the limit. 2) sCaretsAllowDraggingAcrossOtherCaret
258 // is true and the active caret's position is the same as the inactive's
260 // @return true if the aOffsets is suitable for changing the selection.
261 bool RestrictCaretDraggingOffsets(nsIFrame::ContentOffsets
& aOffsets
);
263 // ---------------------------------------------------------------------------
264 // The following functions are made virtual for stubbing or mocking in gtest.
266 // @return true if Terminate() had been called.
267 virtual bool IsTerminated() const { return !mPresShell
; }
269 // Get caret mode based on current selection.
270 virtual CaretMode
GetCaretMode() const;
272 // @return true if aStartFrame comes before aEndFrame.
273 virtual bool CompareTreePosition(nsIFrame
* aStartFrame
,
274 nsIFrame
* aEndFrame
) const;
276 // Check if the two carets is overlapping to become tilt.
277 // @return true if the two carets become tilt; false, otherwise.
278 virtual bool UpdateCaretsForOverlappingTilt();
280 // Make the two carets always tilt.
281 virtual void UpdateCaretsForAlwaysTilt(nsIFrame
* aStartFrame
,
282 nsIFrame
* aEndFrame
);
284 // Check whether AccessibleCaret is displayable in cursor mode or not.
285 // @param aOutFrame returns frame of the cursor if it's displayable.
286 // @param aOutOffset returns frame offset as well.
287 virtual bool IsCaretDisplayableInCursorMode(
288 nsIFrame
** aOutFrame
= nullptr, int32_t* aOutOffset
= nullptr) const;
290 virtual bool HasNonEmptyTextContent(nsINode
* aNode
) const;
292 // This function will flush layout, so caller must ensure the PresShell is
293 // still valid after calling this method.
295 virtual void DispatchCaretStateChangedEvent(dom::CaretChangedReason aReason
);
297 // ---------------------------------------------------------------------------
300 nscoord mOffsetYToCaretLogicalPosition
= NS_UNCONSTRAINEDSIZE
;
302 // AccessibleCaretEventHub owns us by a UniquePtr. When it's destroyed, we'll
303 // also be destroyed. No need to worry if we outlive mPresShell.
305 // mPresShell will be set to nullptr in Terminate(). Therefore mPresShell is
306 // nullptr either we are in gtest or PresShell::IsDestroying() is true.
307 PresShell
* MOZ_NON_OWNING_REF mPresShell
= nullptr;
309 // First caret is attached to nsCaret in cursor mode, and is attached to
310 // selection highlight as the left caret in selection mode.
311 UniquePtr
<AccessibleCaret
> mFirstCaret
;
313 // Second caret is used solely in selection mode, and is attached to selection
314 // highlight as the right caret.
315 UniquePtr
<AccessibleCaret
> mSecondCaret
;
317 // The caret being pressed or dragged.
318 AccessibleCaret
* mActiveCaret
= nullptr;
320 // The caret mode since last update carets.
321 CaretMode mLastUpdateCaretMode
= CaretMode::None
;
323 // The last input source that the event hub saw. We use this to decide whether
324 // or not show the carets when the selection is updated, as we want to hide
325 // the carets for mouse-triggered selection changes but show them for other
326 // input types such as touch.
327 uint16_t mLastInputSource
= dom::MouseEvent_Binding::MOZ_SOURCE_UNKNOWN
;
329 // Set to true in OnScrollStart() and set to false in OnScrollEnd().
330 bool mIsScrollStarted
= false;
332 // Whether we're flushing layout, used for sanity-checking.
333 bool mFlushingLayout
= false;
335 // Set to false to disallow flushing layout in some callbacks such as
336 // OnReflow(), OnScrollStart(), OnScrollStart(), or OnScrollPositionChanged().
337 bool mAllowFlushingLayout
= true;
339 // Set to True if one of the caret's position is changed in last update.
340 bool mIsCaretPositionChanged
= false;
342 // Set to true if we should disable APZ.
343 bool mShouldDisableApz
= false;
345 static const int32_t kAutoScrollTimerDelay
= 30;
347 // Clicking on the boundary of input or textarea will move the caret to the
348 // front or end of the content. To avoid this, we need to deflate the content
349 // boundary by 61 app units, which is 1 pixel + 1 app unit as defined in
351 static const int32_t kBoundaryAppUnits
= 61;
353 enum ScriptUpdateMode
: int32_t {
354 // By default, always hide carets for selection changes due to JS calls.
356 // Update any visible carets for selection changes due to JS calls,
357 // but don't show carets if carets are hidden.
358 kScriptUpdateVisible
,
359 // Always show carets for selection changes due to JS calls.
364 std::ostream
& operator<<(std::ostream
& aStream
,
365 const AccessibleCaretManager::CaretMode
& aCaretMode
);
367 std::ostream
& operator<<(
368 std::ostream
& aStream
,
369 const AccessibleCaretManager::UpdateCaretsHint
& aResult
);
371 } // namespace mozilla
373 #endif // AccessibleCaretManager_h