EditorModuleStructure.rst (9597B)
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``.