editor/docs/EditorModuleStructure.rst

   1 #######################
   2 Editor module structure
   3 #######################
   4
   5 This document explains the structure of the editor module and overview of classes.
   6
   7 Introduction
   8 ============
   9
  10 This module implements the builtin editors of editable elements or documents, and this does **not**
  11 implement the interface with DOM API and visual feedback of the editing UI. In other words, this
  12 module implements DOM tree editors.
  13
  14 Directories
  15 ===========
  16
  17 composer
  18 --------
  19
  20 Previously, this directory contained "Composer" UI related code.  However, currently, this
  21 directory contains ``nsEditingSession`` and ``ComposerCommandsUpdater``.
  22
  23 libeditor
  24 ---------
  25
  26 This is the main directory which contains "core" implementation of editors.
  27
  28 spellchecker
  29 ------------
  30
  31 Despite of the directory name, implementation of the spellchecker is **not** here. This directory
  32 contains only a bridge between editor classes and the spellchecker and serialized text of editable
  33 content for spellchecking.
  34
  35 txmgr
  36 -----
  37
  38 This directory contains transaction items and transaction classes. They were designed for generic
  39 use cases, e.g., managing undo/redo of bookmarks/history of browser, etc, but they are used only by
  40 the editor.
  41
  42 Main classes
  43 ============
  44
  45 EditorBase
  46 ----------
  47
  48 ``EditorBase`` class is an abstract class of editors.  This inherits ``nsIEditor`` XPCOM interface,
  49 implement common features which work with instance of classes, and exposed by
  50 ``mozilla/EditorBase.h``.
  51
  52 TextEditor
  53 ----------
  54
  55 ``TextEditor`` class is the implementation of plaintext editor which works with ``<input>`` and
  56 ``<textarea>``.  Its exposed root is the host HTML elements, however, the editable root is an
  57 anonymous ``<div>`` created in a native anonymous subtree under the exposed root elements. This
  58 creates a ``Text`` node as the first child of the anonymous ``<div>`` and modify its data. If the text
  59 data ends with a line-break, i.e., the last line is empty, append a ``<br>`` element for making the
  60 empty last line visible.
  61
  62 This also implements password editor. It works almost same as normal text editor, but each character
  63 may be masked by masked character such as "●" or "*" by the layout module for the privacy.
  64 Therefore, this manages masked/unmasked range of password and maybe making typed character
  65 automatically after a while for mobile devices.
  66
  67 This is exposed with ``mozilla/TextEditor.h``.
  68
  69 Selection in TextEditor
  70 ^^^^^^^^^^^^^^^^^^^^^^^
  71
  72 Independent ``Selection`` and ``nsFrameSelection`` per ``<input>`` or ``<textarea>``.
  73
  74 Lifetime of TextEditor
  75 ^^^^^^^^^^^^^^^^^^^^^^
  76
  77 Created when an editable ``<textarea>`` is created or a text-editable ``<input>`` element gets focus.
  78 Note that the initialization may run asynchronously if it's requested when it's not safe to run
  79 script. Destroyed when the element becomes invisible. Note that ``TextEditor`` is recreated when
  80 every reframe of the host element.  This means that when the size of ``<input>`` or ``<textarea>``
  81 is changed for example, ``TextEditor`` is recreated and forget undo/redo transactions, but takes
  82 over the value, selection ranges and composition of IME from the previous instance.
  83
  84 HTMLEditor
  85 ----------
  86
  87 ``HTMLEditor`` class is the implementation of rich text editor which works with ``contenteditable``,
  88 ``Document.designMode`` and XUL ``<editor>``. Its instance is created per document even if the
  89 document has multiple elements having ``contenteditable`` attribute. Therefore, undo/redo
  90 transactions are shared in all editable regions.
  91
  92 This is exposed with ``mozilla/HTMLEditor.h``.
  93
  94 Selection in HTMLEditor
  95 ^^^^^^^^^^^^^^^^^^^^^^^
  96
  97 The instance for the ``Document`` and ``Window``. When an editable element gets focus, ``HTMLEditor``
  98 sets the ancestor limit of ``Selection`` to the focused element or the ``<body>`` of the ``Document``.
  99 Then, ``Selection`` cannot cross boundary of the limiter element.
 100
 101 Lifetime of HTMLEditor
 102 ^^^^^^^^^^^^^^^^^^^^^^
 103
 104 Created when first editable region is created in the ``Document``.  Destroyed when last editable
 105 region becomes non-editable.
 106
 107 Currently, even while ``HTMLEditor`` is handling an edit command/operation (called edit action in
 108 editor classes), each DOM mutation can be tracked with legacy DOM mutation events synchronously.
 109 Thus, after changing the DOM tree from ``HTMLEditor``, any state could occur, e.g., the editor
 110 itself may have been destroyed, the DOM tree have been modified, the ``Selection`` have been
 111 modified, etc. This issue is tracked in
 112 `bug 1710784 <https://bugzilla.mozilla.org/show_bug.cgi?id=1710784>`__.
 113
 114
 115 EditorUtils
 116 -----------
 117
 118 This class has only static utility methods which are used by ``EditorBase`` or ``TextEditor`` and
 119 may be used by ``HTMLEditor`` too.  I.e., the utility methods which are used **not** only by
 120 ``HTMLEditor`` should be implemented in this class.
 121
 122 Typically, sateless methods should be implemented as ``static`` methods of utility classes because
 123 editor classes have too many methods and fields.
 124
 125 This class is not exposed.
 126
 127 HTMLEditUtils
 128 -------------
 129
 130 This class has only static utility methods which are used only by ``HTMLEditor``.
 131
 132 This class is not exposed.
 133
 134 AutoRangeArray
 135 --------------
 136
 137 This class is a stack only class and intended to copy of normal selection ranges.  In the new code,
 138 `Selection` shouldn't be referred directly, instead, methods should take reference to this instance
 139 and modify it.  Finally, root caller should apply the ranges to `Selection`.  Then, `HTMLEditor`
 140 does not need to take care of unexpected `Selection` updates by legacy DOM mutation event listeners.
 141
 142 This class is not exposed.
 143
 144 EditorDOMPoint, EditorRawDOMPoint, EditorDOMPointInText, EditorRawDOMPointInText
 145 --------------------------------------------------------------------------------
 146
 147 It represents a point in a DOM tree with one of the following:
 148
 149 * Container node and offset in it
 150 * Container node and child node in it
 151 * Container node and both offset and child node in it
 152
 153 In most cases, instances are initialized with a container and only offset or child node.  Then,
 154 when ``Offset()`` or ``GetChild()`` is called, the last one is "fixed".  After inserting new child
 155 node before the offset and/or the child node, ``IsSetAndValid()`` will return ``false`` since the
 156 child node is not the child at the offset.
 157
 158 If you want to keep using after modifying the DOM tree, you can make the instance forget offset or
 159 child node with ``AutoEditorDOMPointChildInvalidator`` and ``AutoEditorDOMRangeChildrenInvalidator``.
 160 The reason why the forgetting methods are not simply exposed is, ``Offset()`` and ``GetChild()``
 161 are available even after the DOM tree is modified to get the cached offset and child node,
 162 additionally, which method may modify the DOM tree may be not clear for developers.  Therefore,
 163 creating a block only for these helper classes makes the updating point clearer.
 164
 165 These classes are exposed with ``mozilla/EditorDOMPoint.h``.
 166
 167 EditorDOMRange, EditorRawDOMRange, EditorDOMRangeInTexts, EditorRawDOMRangeInTexts
 168 ----------------------------------------------------------------------------------
 169
 170 It represents 2 points in a DOM tree with 2 ``Editor*DOMPoint(InText)``.  Different from ``nsRange``,
 171 the instances do not track the DOM tree changes. Therefore, the initialization is much faster than
 172 ``nsRange`` and can be in the stack.
 173
 174 These classes are exposed with ``mozilla/EditorDOMPoint.h``.
 175
 176 AutoTrackDOMPoint, AutoTrackDOMRange
 177 ------------------------------------
 178
 179 These methods updates ``Editor*DOMPoint(InText)`` or ``Editor*DOMRange(InTexts)`` at destruction
 180 with applying the changes caused by the editor instance.  In other words, they don't track the DOM
 181 tree changes by the web apps like changes from legacy DOM mutation event listeners.
 182
 183 These classes are currently exposed with ``mozilla/SelectionState.h``, but we should stop exposing
 184 them.
 185
 186 WSRunScanner
 187 ------------
 188
 189 A helper class of ``HTMLEditor``. This class scans previous or (inclusive) next visible thing from
 190 a DOM point or a DOM node. This is typically useful for considering whether a `<br>` is visible or
 191 invisible due to near a block element boundary, finding nearest editable character from caret
 192 position, etc.  However, the running cost is **not** cheap, thus if you find another way to consider
 193 it simpler, use it instead, and also this does not check the actual style of the nodes (visible vs.
 194 invisible, block vs. inline), thus you'd get unexpected result in tricky cases.
 195
 196 This class is not exposed.
 197
 198 WhiteSpaceVisibilityKeeper
 199 --------------------------
 200
 201 A helper class of ``HTMLEditor`` to handle collapsible white-spaces as what user expected. This
 202 class currently handles white-space normalization (e.g., when user inputs multiple collapsible
 203 white-spaces, this replaces some of them to NBSPs), but the behavior is different from the other
 204 browsers. We should re-implement this with emulating the other browsers' behavior as far as possible,
 205 but currently it's put off due to not affecting UX (tracked in
 206 `bug 1658699 <https://bugzilla.mozilla.org/show_bug.cgi?id=1658699>`__.
 207
 208 This class is not exposed.
 209
 210 \*Transaction
 211 -------------
 212
 213 ``*Transaction`` classes represents a small transaction of updating the DOM tree and implements
 214 "do", "undo" and "redo" of the update.
 215
 216 Note that each class instance is created too many (one edit action may cause multiple transactions).
 217 Therefore, each instance must be smaller as far as possible, and if you have an idea to collapse
 218 multiple instances to one instance, you should fix it. Then, users can run Firefox with smaller
 219 memory devices especially if the transaction is used in ``TextEditor``.