Line data Source code
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/. */
6 :
7 : #ifndef AccessibleCaretManager_h
8 : #define AccessibleCaretManager_h
9 :
10 : #include "AccessibleCaret.h"
11 :
12 : #include "mozilla/dom/CaretStateChangedEvent.h"
13 : #include "mozilla/EnumSet.h"
14 : #include "mozilla/EventForwards.h"
15 : #include "mozilla/RefPtr.h"
16 : #include "mozilla/UniquePtr.h"
17 : #include "nsCOMPtr.h"
18 : #include "nsCoord.h"
19 : #include "nsIDOMMouseEvent.h"
20 : #include "nsIFrame.h"
21 : #include "nsISelectionListener.h"
22 :
23 : class nsFrameSelection;
24 : class nsIContent;
25 : class nsIPresShell;
26 : struct nsPoint;
27 :
28 : namespace mozilla {
29 :
30 : namespace dom {
31 : class Element;
32 : class Selection;
33 : } // namespace dom
34 :
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.
40 : //
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
43 : // date.
44 : //
45 : // Please see the wiki page for more information.
46 : // https://wiki.mozilla.org/AccessibleCaret
47 : //
48 : class AccessibleCaretManager
49 : {
50 : public:
51 : explicit AccessibleCaretManager(nsIPresShell* aPresShell);
52 : virtual ~AccessibleCaretManager();
53 :
54 : // Called by AccessibleCaretEventHub to inform us that PresShell is destroyed.
55 : void Terminate();
56 :
57 : // The aPoint in the following public methods should be relative to root
58 : // frame.
59 :
60 : // Press caret on the given point. Return NS_OK if the point is actually on
61 : // one of the carets.
62 : virtual nsresult PressCaret(const nsPoint& aPoint, EventClassID aEventClass);
63 :
64 : // Drag caret to the given point. It's required to call PressCaret()
65 : // beforehand.
66 : virtual nsresult DragCaret(const nsPoint& aPoint);
67 :
68 : // Release caret from he previous press action. It's required to call
69 : // PressCaret() beforehand.
70 : virtual nsresult ReleaseCaret();
71 :
72 : // A quick single tap on caret on given point without dragging.
73 : virtual nsresult TapCaret(const nsPoint& aPoint);
74 :
75 : // Select a word or bring up paste shortcut (if Gaia is listening) under the
76 : // given point.
77 : virtual nsresult SelectWordOrShortcut(const nsPoint& aPoint);
78 :
79 : // Handle scroll-start event.
80 : virtual void OnScrollStart();
81 :
82 : // Handle scroll-end event.
83 : virtual void OnScrollEnd();
84 :
85 : // Handle ScrollPositionChanged from nsIScrollObserver. This might be called
86 : // at anytime, not necessary between OnScrollStart and OnScrollEnd.
87 : virtual void OnScrollPositionChanged();
88 :
89 : // Handle reflow event from nsIReflowObserver.
90 : virtual void OnReflow();
91 :
92 : // Handle blur event from nsFocusManager.
93 : virtual void OnBlur();
94 :
95 : // Handle NotifySelectionChanged event from nsISelectionListener.
96 : virtual nsresult OnSelectionChanged(nsIDOMDocument* aDoc,
97 : nsISelection* aSel,
98 : int16_t aReason);
99 : // Handle key event.
100 : virtual void OnKeyboardEvent();
101 :
102 : // The canvas frame holding the accessible caret anonymous content elements
103 : // was reconstructed, resulting in the content elements getting cloned.
104 : virtual void OnFrameReconstruction();
105 :
106 : // Update the manager with the last input source that was observed. This
107 : // is used in part to determine if the carets should be shown or hidden.
108 : void SetLastInputSource(uint16_t aInputSource);
109 :
110 : protected:
111 : // This enum representing the number of AccessibleCarets on the screen.
112 : enum class CaretMode : uint8_t {
113 : // No caret on the screen.
114 : None,
115 :
116 : // One caret, i.e. the selection is collapsed.
117 : Cursor,
118 :
119 : // Two carets, i.e. the selection is not collapsed.
120 : Selection
121 : };
122 :
123 : friend std::ostream& operator<<(std::ostream& aStream,
124 : const CaretMode& aCaretMode);
125 :
126 : enum class UpdateCaretsHint : uint8_t {
127 : // Update everything including appearance and position.
128 : Default,
129 :
130 : // Update everything while respecting the old appearance. For example, if
131 : // the caret in cursor mode is hidden due to blur, do not change its
132 : // appearance to Normal.
133 : RespectOldAppearance,
134 :
135 : // No CaretStateChangedEvent will be dispatched in the end of
136 : // UpdateCarets().
137 : DispatchNoEvent,
138 : };
139 :
140 : using UpdateCaretsHintSet = mozilla::EnumSet<UpdateCaretsHint>;
141 :
142 : friend std::ostream& operator<<(std::ostream& aStream,
143 : const UpdateCaretsHint& aResult);
144 :
145 : // Update carets based on current selection status. This function will flush
146 : // layout, so caller must ensure the PresShell is still valid after calling
147 : // this method.
148 : void UpdateCarets(UpdateCaretsHintSet aHints = UpdateCaretsHint::Default);
149 :
150 : // Force hiding all carets regardless of the current selection status.
151 : void HideCarets();
152 :
153 : void UpdateCaretsForCursorMode(UpdateCaretsHintSet aHints);
154 : void UpdateCaretsForSelectionMode(UpdateCaretsHintSet aHints);
155 :
156 : // Provide haptic / touch feedback, primarily for select on longpress.
157 : void ProvideHapticFeedback();
158 :
159 : // Get the nearest enclosing focusable frame of aFrame.
160 : // @return focusable frame if there is any; nullptr otherwise.
161 : nsIFrame* GetFocusableFrame(nsIFrame* aFrame) const;
162 :
163 : // Change focus to aFrame if it isn't nullptr. Otherwise, clear the old focus
164 : // then re-focus the window.
165 : void ChangeFocusToOrClearOldFocus(nsIFrame* aFrame) const;
166 :
167 : nsresult SelectWord(nsIFrame* aFrame, const nsPoint& aPoint) const;
168 : void SetSelectionDragState(bool aState) const;
169 :
170 : // Return true if the candidate string is a phone number.
171 : bool IsPhoneNumber(nsAString& aCandidate) const;
172 :
173 : // Extend the current selection forwards and backwards if it's already a
174 : // phone number.
175 : void SelectMoreIfPhoneNumber() const;
176 :
177 : // Extend the current phone number selection in the requested direction.
178 : void ExtendPhoneNumberSelection(const nsAString& aDirection) const;
179 :
180 : void SetSelectionDirection(nsDirection aDir) const;
181 :
182 : // If aDirection is eDirNext, get the frame for the range start in the first
183 : // range from the current selection, and return the offset into that frame as
184 : // well as the range start content and the content offset. Otherwise, get the
185 : // frame and the offset for the range end in the last range instead.
186 : nsIFrame* GetFrameForFirstRangeStartOrLastRangeEnd(
187 : nsDirection aDirection,
188 : int32_t* aOutOffset,
189 : nsIContent** aOutContent = nullptr,
190 : int32_t* aOutContentOffset = nullptr) const;
191 :
192 : nsresult DragCaretInternal(const nsPoint& aPoint);
193 : nsPoint AdjustDragBoundary(const nsPoint& aPoint) const;
194 : void ClearMaintainedSelection() const;
195 :
196 : // Caller is responsible to use IsTerminated() to check whether PresShell is
197 : // still valid.
198 : void FlushLayout() const;
199 :
200 : dom::Element* GetEditingHostForFrame(nsIFrame* aFrame) const;
201 : dom::Selection* GetSelection() const;
202 : already_AddRefed<nsFrameSelection> GetFrameSelection() const;
203 : nsAutoString StringifiedSelection() const;
204 :
205 : // Get the union of all the child frame scrollable overflow rects for aFrame,
206 : // which is used as a helper function to restrict the area where the caret can
207 : // be dragged. Returns the rect relative to aFrame.
208 : nsRect GetAllChildFrameRectsUnion(nsIFrame* aFrame) const;
209 :
210 : // Restrict the active caret's dragging position based on
211 : // sCaretsAllowDraggingAcrossOtherCaret. If the active caret is the first
212 : // caret, the `limit` will be the previous character of the second caret.
213 : // Otherwise, the `limit` will be the next character of the first caret.
214 : //
215 : // @param aOffsets is the new position of the active caret, and it will be set
216 : // to the `limit` when 1) sCaretsAllowDraggingAcrossOtherCaret is false and
217 : // it's being dragged past the limit. 2) sCaretsAllowDraggingAcrossOtherCaret
218 : // is true and the active caret's position is the same as the inactive's
219 : // position.
220 : // @return true if the aOffsets is suitable for changing the selection.
221 : bool RestrictCaretDraggingOffsets(nsIFrame::ContentOffsets& aOffsets);
222 :
223 : // ---------------------------------------------------------------------------
224 : // The following functions are made virtual for stubbing or mocking in gtest.
225 : //
226 : // @return true if Terminate() had been called.
227 0 : virtual bool IsTerminated() const { return !mPresShell; }
228 :
229 : // Get caret mode based on current selection.
230 : virtual CaretMode GetCaretMode() const;
231 :
232 : // @return true if aStartFrame comes before aEndFrame.
233 : virtual bool CompareTreePosition(nsIFrame* aStartFrame,
234 : nsIFrame* aEndFrame) const;
235 :
236 : // Check if the two carets is overlapping to become tilt.
237 : // @return true if the two carets become tilt; false, otherwise.
238 : virtual bool UpdateCaretsForOverlappingTilt();
239 :
240 : // Make the two carets always tilt.
241 : virtual void UpdateCaretsForAlwaysTilt(nsIFrame* aStartFrame,
242 : nsIFrame* aEndFrame);
243 :
244 : // Check whether AccessibleCaret is displayable in cursor mode or not.
245 : // @param aOutFrame returns frame of the cursor if it's displayable.
246 : // @param aOutOffset returns frame offset as well.
247 : virtual bool IsCaretDisplayableInCursorMode(nsIFrame** aOutFrame = nullptr,
248 : int32_t* aOutOffset = nullptr) const;
249 :
250 : virtual bool HasNonEmptyTextContent(nsINode* aNode) const;
251 :
252 : // This function will flush layout, so caller must ensure the PresShell is
253 : // still valid after calling this method.
254 : virtual void DispatchCaretStateChangedEvent(dom::CaretChangedReason aReason) const;
255 :
256 : // ---------------------------------------------------------------------------
257 : // Member variables
258 : //
259 : nscoord mOffsetYToCaretLogicalPosition = NS_UNCONSTRAINEDSIZE;
260 :
261 : // AccessibleCaretEventHub owns us by a UniquePtr. When it's destroyed, we'll
262 : // also be destroyed. No need to worry if we outlive mPresShell.
263 : //
264 : // mPresShell will be set to nullptr in Terminate(). Therefore mPresShell is
265 : // nullptr either we are in gtest or PresShell::IsDestroying() is true.
266 : nsIPresShell* MOZ_NON_OWNING_REF mPresShell = nullptr;
267 :
268 : // First caret is attached to nsCaret in cursor mode, and is attached to
269 : // selection highlight as the left caret in selection mode.
270 : UniquePtr<AccessibleCaret> mFirstCaret;
271 :
272 : // Second caret is used solely in selection mode, and is attached to selection
273 : // highlight as the right caret.
274 : UniquePtr<AccessibleCaret> mSecondCaret;
275 :
276 : // The caret being pressed or dragged.
277 : AccessibleCaret* mActiveCaret = nullptr;
278 :
279 : // The caret mode since last update carets.
280 : CaretMode mLastUpdateCaretMode = CaretMode::None;
281 :
282 : // Store the appearance of the carets when calling OnScrollStart() so that it
283 : // can be restored in OnScrollEnd().
284 : AccessibleCaret::Appearance mFirstCaretAppearanceOnScrollStart =
285 : AccessibleCaret::Appearance::None;
286 : AccessibleCaret::Appearance mSecondCaretAppearanceOnScrollStart =
287 : AccessibleCaret::Appearance::None;
288 :
289 : // The last input source that the event hub saw. We use this to decide whether
290 : // or not show the carets when the selection is updated, as we want to hide
291 : // the carets for mouse-triggered selection changes but show them for other
292 : // input types such as touch.
293 : uint16_t mLastInputSource = nsIDOMMouseEvent::MOZ_SOURCE_UNKNOWN;
294 :
295 : // Set to true in OnScrollStart() and set to false in OnScrollEnd().
296 : bool mIsScrollStarted = false;
297 :
298 : static const int32_t kAutoScrollTimerDelay = 30;
299 :
300 : // Clicking on the boundary of input or textarea will move the caret to the
301 : // front or end of the content. To avoid this, we need to deflate the content
302 : // boundary by 61 app units, which is 1 pixel + 1 app unit as defined in
303 : // AppUnit.h.
304 : static const int32_t kBoundaryAppUnits = 61;
305 :
306 : // Preference to show selection bars at the two ends in selection mode. The
307 : // selection bar is always disabled in cursor mode.
308 : static bool sSelectionBarEnabled;
309 :
310 : // Preference to allow smarter selection of phone numbers,
311 : // when user long presses text to start.
312 : static bool sExtendSelectionForPhoneNumber;
313 :
314 : // Preference to show caret in cursor mode when long tapping on an empty
315 : // content. This also changes the default update behavior in cursor mode,
316 : // which is based on the emptiness of the content, into something more
317 : // heuristic. See UpdateCaretsForCursorMode() for the details.
318 : static bool sCaretShownWhenLongTappingOnEmptyContent;
319 :
320 : // Preference to make carets always tilt in selection mode. By default, the
321 : // carets become tilt only when they are overlapping.
322 : static bool sCaretsAlwaysTilt;
323 :
324 : // Preference to allow carets always show when scrolling (either panning or
325 : // zooming) the page. When set to false, carets will hide during scrolling,
326 : // and show again after the user lifts the finger off the screen.
327 : static bool sCaretsAlwaysShowWhenScrolling;
328 :
329 : // By default, javascript content selection changes closes AccessibleCarets and
330 : // UI interactions. Optionally, we can try to maintain the active UI, keeping
331 : // carets and ActionBar available.
332 : static bool sCaretsScriptUpdates;
333 :
334 : // Preference to allow one caret to be dragged across the other caret without
335 : // any limitation. When set to false, one caret cannot be dragged across the
336 : // other one.
337 : static bool sCaretsAllowDraggingAcrossOtherCaret;
338 :
339 : // AccessibleCaret pref for haptic feedback behaviour on longPress.
340 : static bool sHapticFeedback;
341 :
342 : // Preference to keep carets hidden when the selection is being manipulated
343 : // by mouse input (as opposed to touch/pen/etc.).
344 : static bool sHideCaretsForMouseInput;
345 : };
346 :
347 : std::ostream& operator<<(std::ostream& aStream,
348 : const AccessibleCaretManager::CaretMode& aCaretMode);
349 :
350 : std::ostream& operator<<(std::ostream& aStream,
351 : const AccessibleCaretManager::UpdateCaretsHint& aResult);
352 :
353 : } // namespace mozilla
354 :
355 : #endif // AccessibleCaretManager_h
|
