summaryrefslogtreecommitdiffstats
path: root/editor/libeditor/EditorUtils.h
blob: 9664adaaaa6c2da8fc70de32e097c8dd8d3a9673 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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_EditorUtils_h
#define mozilla_EditorUtils_h

#include "mozilla/EditorBase.h"      // for EditorBase
#include "mozilla/EditorDOMPoint.h"  // for EditorDOMPoint, EditorDOMRange, etc
#include "mozilla/EditorForwards.h"
#include "mozilla/IntegerRange.h"       // for IntegerRange
#include "mozilla/Maybe.h"              // for Maybe
#include "mozilla/Result.h"             // for Result<>
#include "mozilla/dom/Element.h"        // for dom::Element
#include "mozilla/dom/HTMLBRElement.h"  // for dom::HTMLBRElement
#include "mozilla/dom/Selection.h"      // for dom::Selection
#include "mozilla/dom/Text.h"           // for dom::Text

#include "nsAtom.h"          // for nsStaticAtom
#include "nsCOMPtr.h"        // for nsCOMPtr
#include "nsContentUtils.h"  // for nsContentUtils
#include "nsDebug.h"         // for NS_WARNING, etc
#include "nsError.h"         // for NS_SUCCESS_* and NS_ERROR_*
#include "nsRange.h"         // for nsRange
#include "nsString.h"        // for nsAString, nsString, etc

class nsITransferable;

namespace mozilla {

enum class StyleWhiteSpace : uint8_t;

enum class SuggestCaret {
  // If specified, the method returns NS_OK when there is no recommended caret
  // position.
  OnlyIfHasSuggestion,
  // If specified and if EditorBase::AllowsTransactionsToChangeSelection
  // returns false, the method does nothing and returns NS_OK.
  OnlyIfTransactionsAllowedToDoIt,
  // If specified, the method returns
  // NS_SUCCESS_EDITOR_BUT_IGNORED_TRIVIAL_ERROR even if
  // EditorBase::CollapseSelectionTo returns an error except when
  // NS_ERROR_EDITOR_DESTROYED.
  AndIgnoreTrivialError,
};

/******************************************************************************
 * CaretPoint is a wrapper of EditorDOMPoint and provides a helper method to
 * collapse Selection there, or move it to a local variable.  This is typically
 * used as the ok type of Result or a base class of DoSomethingResult classes.
 ******************************************************************************/
class MOZ_STACK_CLASS CaretPoint {
 public:
  explicit CaretPoint(const EditorDOMPoint& aPointToPutCaret)
      : mCaretPoint(aPointToPutCaret) {}
  explicit CaretPoint(EditorDOMPoint&& aPointToPutCaret)
      : mCaretPoint(std::move(aPointToPutCaret)) {}

  CaretPoint(const CaretPoint&) = delete;
  CaretPoint& operator=(const CaretPoint&) = delete;
  CaretPoint(CaretPoint&&) = default;
  CaretPoint& operator=(CaretPoint&&) = default;

  /**
   * Suggest caret position to aEditorBase.
   */
  [[nodiscard]] MOZ_CAN_RUN_SCRIPT nsresult SuggestCaretPointTo(
      EditorBase& aEditorBase, const SuggestCaretOptions& aOptions) const;

  /**
   * IgnoreCaretPointSuggestion() should be called if the method does not want
   * to use caret position recommended by this instance.
   */
  void IgnoreCaretPointSuggestion() const { mHandledCaretPoint = true; }

  /**
   * When propagating the result, it may not want to the caller modify
   * selection.  In such case, this can clear the caret point.  Use
   * IgnoreCaretPointSuggestion() in the caller side instead.
   */
  void ForgetCaretPointSuggestion() { mCaretPoint.Clear(); }

  bool HasCaretPointSuggestion() const { return mCaretPoint.IsSet(); }
  constexpr const EditorDOMPoint& CaretPointRef() const { return mCaretPoint; }
  constexpr EditorDOMPoint&& UnwrapCaretPoint() {
    mHandledCaretPoint = true;
    return std::move(mCaretPoint);
  }
  bool CopyCaretPointTo(EditorDOMPoint& aPointToPutCaret,
                        const SuggestCaretOptions& aOptions) const {
    MOZ_ASSERT(!aOptions.contains(SuggestCaret::AndIgnoreTrivialError));
    MOZ_ASSERT(
        !aOptions.contains(SuggestCaret::OnlyIfTransactionsAllowedToDoIt));
    mHandledCaretPoint = true;
    if (aOptions.contains(SuggestCaret::OnlyIfHasSuggestion) &&
        !mCaretPoint.IsSet()) {
      return false;
    }
    aPointToPutCaret = mCaretPoint;
    return true;
  }
  bool MoveCaretPointTo(EditorDOMPoint& aPointToPutCaret,
                        const SuggestCaretOptions& aOptions) {
    MOZ_ASSERT(!aOptions.contains(SuggestCaret::AndIgnoreTrivialError));
    MOZ_ASSERT(
        !aOptions.contains(SuggestCaret::OnlyIfTransactionsAllowedToDoIt));
    if (aOptions.contains(SuggestCaret::OnlyIfHasSuggestion) &&
        !mCaretPoint.IsSet()) {
      return false;
    }
    aPointToPutCaret = UnwrapCaretPoint();
    return true;
  }
  bool CopyCaretPointTo(EditorDOMPoint& aPointToPutCaret,
                        const EditorBase& aEditorBase,
                        const SuggestCaretOptions& aOptions) const;
  bool MoveCaretPointTo(EditorDOMPoint& aPointToPutCaret,
                        const EditorBase& aEditorBase,
                        const SuggestCaretOptions& aOptions);

 protected:
  constexpr bool CaretPointHandled() const { return mHandledCaretPoint; }

  void SetCaretPoint(const EditorDOMPoint& aCaretPoint) {
    mHandledCaretPoint = false;
    mCaretPoint = aCaretPoint;
  }
  void SetCaretPoint(EditorDOMPoint&& aCaretPoint) {
    mHandledCaretPoint = false;
    mCaretPoint = std::move(aCaretPoint);
  }

  void UnmarkAsHandledCaretPoint() { mHandledCaretPoint = true; }

  CaretPoint() = default;

 private:
  EditorDOMPoint mCaretPoint;
  bool mutable mHandledCaretPoint = false;
};

/***************************************************************************
 * EditActionResult is useful to return the handling state of edit sub actions
 * without out params.
 */
class MOZ_STACK_CLASS EditActionResult final {
 public:
  bool Canceled() const { return mCanceled; }
  bool Handled() const { return mHandled; }
  bool Ignored() const { return !mCanceled && !mHandled; }

  void MarkAsCanceled() { mCanceled = true; }
  void MarkAsHandled() { mHandled = true; }

  EditActionResult& operator|=(const EditActionResult& aOther) {
    mCanceled |= aOther.mCanceled;
    mHandled |= aOther.mHandled;
    return *this;
  }

  EditActionResult& operator|=(const MoveNodeResult& aMoveNodeResult);

  static EditActionResult IgnoredResult() {
    return EditActionResult(false, false);
  }
  static EditActionResult HandledResult() {
    return EditActionResult(false, true);
  }
  static EditActionResult CanceledResult() {
    return EditActionResult(true, true);
  }

  EditActionResult(const EditActionResult&) = delete;
  EditActionResult& operator=(const EditActionResult&) = delete;
  EditActionResult(EditActionResult&&) = default;
  EditActionResult& operator=(EditActionResult&&) = default;

 private:
  bool mCanceled = false;
  bool mHandled = false;

  EditActionResult(bool aCanceled, bool aHandled)
      : mCanceled(aCanceled), mHandled(aHandled) {}

  EditActionResult() : mCanceled(false), mHandled(false) {}
};

/***************************************************************************
 * CreateNodeResultBase is a simple class for CreateSomething() methods
 * which want to return new node.
 */
template <typename NodeType>
class MOZ_STACK_CLASS CreateNodeResultBase final : public CaretPoint {
  using SelfType = CreateNodeResultBase<NodeType>;

 public:
  bool Handled() const { return mNode; }
  NodeType* GetNewNode() const { return mNode; }
  RefPtr<NodeType> UnwrapNewNode() { return std::move(mNode); }

  CreateNodeResultBase() = delete;
  explicit CreateNodeResultBase(NodeType& aNode) : mNode(&aNode) {}
  explicit CreateNodeResultBase(NodeType& aNode,
                                const EditorDOMPoint& aCandidateCaretPoint)
      : CaretPoint(aCandidateCaretPoint), mNode(&aNode) {}
  explicit CreateNodeResultBase(NodeType& aNode,
                                EditorDOMPoint&& aCandidateCaretPoint)
      : CaretPoint(std::move(aCandidateCaretPoint)), mNode(&aNode) {}

  explicit CreateNodeResultBase(RefPtr<NodeType>&& aNode)
      : mNode(std::move(aNode)) {}
  explicit CreateNodeResultBase(RefPtr<NodeType>&& aNode,
                                const EditorDOMPoint& aCandidateCaretPoint)
      : CaretPoint(aCandidateCaretPoint), mNode(std::move(aNode)) {
    MOZ_ASSERT(mNode);
  }
  explicit CreateNodeResultBase(RefPtr<NodeType>&& aNode,
                                EditorDOMPoint&& aCandidateCaretPoint)
      : CaretPoint(std::move(aCandidateCaretPoint)), mNode(std::move(aNode)) {
    MOZ_ASSERT(mNode);
  }

  [[nodiscard]] static SelfType NotHandled() {
    return SelfType(EditorDOMPoint());
  }
  [[nodiscard]] static SelfType NotHandled(
      const EditorDOMPoint& aPointToPutCaret) {
    SelfType result(aPointToPutCaret);
    return result;
  }
  [[nodiscard]] static SelfType NotHandled(EditorDOMPoint&& aPointToPutCaret) {
    SelfType result(std::move(aPointToPutCaret));
    return result;
  }

#ifdef DEBUG
  ~CreateNodeResultBase() {
    MOZ_ASSERT(!HasCaretPointSuggestion() || CaretPointHandled());
  }
#endif

  CreateNodeResultBase(const SelfType& aOther) = delete;
  SelfType& operator=(const SelfType& aOther) = delete;
  CreateNodeResultBase(SelfType&& aOther) = default;
  SelfType& operator=(SelfType&& aOther) = default;

 private:
  explicit CreateNodeResultBase(const EditorDOMPoint& aCandidateCaretPoint)
      : CaretPoint(aCandidateCaretPoint) {}
  explicit CreateNodeResultBase(EditorDOMPoint&& aCandidateCaretPoint)
      : CaretPoint(std::move(aCandidateCaretPoint)) {}

  RefPtr<NodeType> mNode;
};

/**
 * This is a result of inserting text.  If the text inserted as a part of
 * composition, this does not return CaretPoint.  Otherwise, must return
 * CaretPoint which is typically same as end of inserted text.
 */
class MOZ_STACK_CLASS InsertTextResult final : public CaretPoint {
 public:
  InsertTextResult() : CaretPoint(EditorDOMPoint()) {}
  template <typename EditorDOMPointType>
  explicit InsertTextResult(const EditorDOMPointType& aEndOfInsertedText)
      : CaretPoint(EditorDOMPoint()),
        mEndOfInsertedText(aEndOfInsertedText.template To<EditorDOMPoint>()) {}
  explicit InsertTextResult(EditorDOMPointInText&& aEndOfInsertedText)
      : CaretPoint(EditorDOMPoint()),
        mEndOfInsertedText(std::move(aEndOfInsertedText)) {}
  template <typename PT, typename CT>
  InsertTextResult(EditorDOMPointInText&& aEndOfInsertedText,
                   const EditorDOMPointBase<PT, CT>& aCaretPoint)
      : CaretPoint(aCaretPoint.template To<EditorDOMPoint>()),
        mEndOfInsertedText(std::move(aEndOfInsertedText)) {}
  InsertTextResult(EditorDOMPointInText&& aEndOfInsertedText,
                   CaretPoint&& aCaretPoint)
      : CaretPoint(std::move(aCaretPoint)),
        mEndOfInsertedText(std::move(aEndOfInsertedText)) {
    UnmarkAsHandledCaretPoint();
  }
  InsertTextResult(InsertTextResult&& aOther, EditorDOMPoint&& aCaretPoint)
      : CaretPoint(std::move(aCaretPoint)),
        mEndOfInsertedText(std::move(aOther.mEndOfInsertedText)) {}

  [[nodiscard]] bool Handled() const { return mEndOfInsertedText.IsSet(); }
  const EditorDOMPointInText& EndOfInsertedTextRef() const {
    return mEndOfInsertedText;
  }

 private:
  EditorDOMPointInText mEndOfInsertedText;
};

/***************************************************************************
 * stack based helper class for calling EditorBase::EndTransaction() after
 * EditorBase::BeginTransaction().  This shouldn't be used in editor classes
 * or helper classes while an edit action is being handled.  Use
 * AutoTransactionBatch in such cases since it uses non-virtual internal
 * methods.
 ***************************************************************************/
class MOZ_RAII AutoTransactionBatchExternal final {
 public:
  MOZ_CAN_RUN_SCRIPT explicit AutoTransactionBatchExternal(
      EditorBase& aEditorBase)
      : mEditorBase(aEditorBase) {
    MOZ_KnownLive(mEditorBase).BeginTransaction();
  }

  MOZ_CAN_RUN_SCRIPT ~AutoTransactionBatchExternal() {
    MOZ_KnownLive(mEditorBase).EndTransaction();
  }

 private:
  EditorBase& mEditorBase;
};

/******************************************************************************
 * AutoSelectionRangeArray stores all ranges in `aSelection`.
 * Note that modifying the ranges means modifing the selection ranges.
 *****************************************************************************/
class MOZ_STACK_CLASS AutoSelectionRangeArray final {
 public:
  explicit AutoSelectionRangeArray(dom::Selection& aSelection) {
    for (const uint32_t i : IntegerRange(aSelection.RangeCount())) {
      MOZ_ASSERT(aSelection.GetRangeAt(i));
      mRanges.AppendElement(*aSelection.GetRangeAt(i));
    }
  }

  AutoTArray<mozilla::OwningNonNull<nsRange>, 8> mRanges;
};

class EditorUtils final {
 public:
  using EditorType = EditorBase::EditorType;
  using Selection = dom::Selection;

  /**
   * IsDescendantOf() checks if aNode is a child or a descendant of aParent.
   * aOutPoint is set to the child of aParent.
   *
   * @return            true if aNode is a child or a descendant of aParent.
   */
  static bool IsDescendantOf(const nsINode& aNode, const nsINode& aParent,
                             EditorRawDOMPoint* aOutPoint = nullptr);
  static bool IsDescendantOf(const nsINode& aNode, const nsINode& aParent,
                             EditorDOMPoint* aOutPoint);

  /**
   * Returns true if aContent is a <br> element and it's marked as padding for
   * empty editor.
   */
  static bool IsPaddingBRElementForEmptyEditor(const nsIContent& aContent) {
    const dom::HTMLBRElement* brElement =
        dom::HTMLBRElement::FromNode(&aContent);
    return brElement && brElement->IsPaddingForEmptyEditor();
  }

  /**
   * Returns true if aContent is a <br> element and it's marked as padding for
   * empty last line.
   */
  static bool IsPaddingBRElementForEmptyLastLine(const nsIContent& aContent) {
    const dom::HTMLBRElement* brElement =
        dom::HTMLBRElement::FromNode(&aContent);
    return brElement && brElement->IsPaddingForEmptyLastLine();
  }

  /**
   * IsEditableContent() returns true if aContent's data or children is ediable
   * for the given editor type.  Be aware, returning true does NOT mean the
   * node can be removed from its parent node, and returning false does NOT
   * mean the node cannot be removed from the parent node.
   * XXX May be the anonymous nodes in TextEditor not editable?  If it's not
   *     so, we can get rid of aEditorType.
   */
  static bool IsEditableContent(const nsIContent& aContent,
                                EditorType aEditorType) {
    if (aEditorType == EditorType::HTML &&
        (!aContent.IsEditable() || !aContent.IsInComposedDoc())) {
      // FIXME(emilio): Why only for HTML editors? All content from the root
      // content in text editors is also editable, so afaict we can remove the
      // special-case.
      return false;
    }
    return IsElementOrText(aContent);
  }

  /**
   * Returns true if aContent is a usual element node (not padding <br> element
   * for empty editor) or a text node.  In other words, returns true if
   * aContent is a usual element node or visible data node.
   */
  static bool IsElementOrText(const nsIContent& aContent) {
    if (aContent.IsText()) {
      return true;
    }
    return aContent.IsElement() && !IsPaddingBRElementForEmptyEditor(aContent);
  }

  /**
   * Get computed white-space style of aContent.
   */
  static Maybe<StyleWhiteSpace> GetComputedWhiteSpaceStyle(
      const nsIContent& aContent);

  /**
   * IsWhiteSpacePreformatted() checks the style info for the node for the
   * preformatted text style.  This does NOT flush layout.
   */
  static bool IsWhiteSpacePreformatted(const nsIContent& aContent);

  /**
   * IsNewLinePreformatted() checks whether the linefeed characters are
   * preformatted or collapsible white-spaces.  This does NOT flush layout.
   */
  static bool IsNewLinePreformatted(const nsIContent& aContent);

  /**
   * IsOnlyNewLinePreformatted() checks whether the linefeed characters are
   * preformated but white-spaces are collapsed, or otherwise.  I.e., this
   * returns true only when `white-space:pre-line`.
   */
  static bool IsOnlyNewLinePreformatted(const nsIContent& aContent);

  static nsStaticAtom* GetTagNameAtom(const nsAString& aTagName) {
    if (aTagName.IsEmpty()) {
      return nullptr;
    }
    nsAutoString lowerTagName;
    nsContentUtils::ASCIIToLower(aTagName, lowerTagName);
    return NS_GetStaticAtom(lowerTagName);
  }

  static nsStaticAtom* GetAttributeAtom(const nsAString& aAttribute) {
    if (aAttribute.IsEmpty()) {
      return nullptr;  // Don't use nsGkAtoms::_empty for attribute.
    }
    return NS_GetStaticAtom(aAttribute);
  }

  /**
   * Helper method for deletion.  When this returns true, Selection will be
   * computed with nsFrameSelection that also requires flushed layout
   * information.
   */
  template <typename SelectionOrAutoRangeArray>
  static bool IsFrameSelectionRequiredToExtendSelection(
      nsIEditor::EDirection aDirectionAndAmount,
      SelectionOrAutoRangeArray& aSelectionOrAutoRangeArray) {
    switch (aDirectionAndAmount) {
      case nsIEditor::eNextWord:
      case nsIEditor::ePreviousWord:
      case nsIEditor::eToBeginningOfLine:
      case nsIEditor::eToEndOfLine:
        return true;
      case nsIEditor::ePrevious:
      case nsIEditor::eNext:
        return aSelectionOrAutoRangeArray.IsCollapsed();
      default:
        return false;
    }
  }

  /**
   * Returns true if aSelection includes the point in aParentContent.
   */
  static bool IsPointInSelection(const Selection& aSelection,
                                 const nsINode& aParentNode, uint32_t aOffset);

  /**
   * Create an nsITransferable instance which has kTextMime and
   * kMozTextInternal flavors.
   */
  static Result<nsCOMPtr<nsITransferable>, nsresult>
  CreateTransferableForPlainText(const dom::Document& aDocument);
};

}  // namespace mozilla

#endif  // #ifndef mozilla_EditorUtils_h