/
document.js
233 lines (212 loc) · 8.24 KB
/
document.js
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
/**
* @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module engine/view/document
*/
import DocumentSelection from './documentselection';
import Collection from '@ckeditor/ckeditor5-utils/src/collection';
import mix from '@ckeditor/ckeditor5-utils/src/mix';
import BubblingEmitterMixin from './observer/bubblingemittermixin';
import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
// @if CK_DEBUG_ENGINE // const { logDocument } = require( '../dev-utils/utils' );
/**
* Document class creates an abstract layer over the content editable area, contains a tree of view elements and
* {@link module:engine/view/documentselection~DocumentSelection view selection} associated with this document.
*
* @mixes module:engine/view/observer/bubblingemittermixin~BubblingEmitterMixin
* @mixes module:utils/observablemixin~ObservableMixin
*/
export default class Document {
/**
* Creates a Document instance.
*
* @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor The styles processor instance.
*/
constructor( stylesProcessor ) {
/**
* Selection done on this document.
*
* @readonly
* @member {module:engine/view/documentselection~DocumentSelection} module:engine/view/document~Document#selection
*/
this.selection = new DocumentSelection();
/**
* Roots of the view tree. Collection of the {@link module:engine/view/element~Element view elements}.
*
* View roots are created as a result of binding between {@link module:engine/view/document~Document#roots} and
* {@link module:engine/model/document~Document#roots} and this is handled by
* {@link module:engine/controller/editingcontroller~EditingController}, so to create view root we need to create
* model root using {@link module:engine/model/document~Document#createRoot}.
*
* @readonly
* @member {module:utils/collection~Collection} module:engine/view/document~Document#roots
*/
this.roots = new Collection( { idProperty: 'rootName' } );
/**
* The styles processor instance used by this document when normalizing styles.
*
* @readonly
* @member {module:engine/view/stylesmap~StylesProcessor}
*/
this.stylesProcessor = stylesProcessor;
/**
* Defines whether document is in read-only mode.
*
* When document is read-ony then all roots are read-only as well and caret placed inside this root is hidden.
*
* @observable
* @member {Boolean} #isReadOnly
*/
this.set( 'isReadOnly', false );
/**
* True if document is focused.
*
* This property is updated by the {@link module:engine/view/observer/focusobserver~FocusObserver}.
* If the {@link module:engine/view/observer/focusobserver~FocusObserver} is disabled this property will not change.
*
* @readonly
* @observable
* @member {Boolean} module:engine/view/document~Document#isFocused
*/
this.set( 'isFocused', false );
/**
* `true` while the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
* When they stop selecting, the property goes back to `false`.
*
* This property is updated by the {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
*
* @readonly
* @observable
* @member {Boolean} module:engine/view/document~Document#isSelecting
*/
this.set( 'isSelecting', false );
/**
* True if composition is in progress inside the document.
*
* This property is updated by the {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
* If the {@link module:engine/view/observer/compositionobserver~CompositionObserver} is disabled this property will not change.
*
* @readonly
* @observable
* @member {Boolean} module:engine/view/document~Document#isComposing
*/
this.set( 'isComposing', false );
/**
* Post-fixer callbacks registered to the view document.
*
* @private
* @member {Set}
*/
this._postFixers = new Set();
}
/**
* Gets a {@link module:engine/view/document~Document#roots view root element} with the specified name. If the name is not
* specific "main" root is returned.
*
* @param {String} [name='main'] Name of the root.
* @returns {module:engine/view/rooteditableelement~RootEditableElement|null} The view root element with the specified name
* or null when there is no root of given name.
*/
getRoot( name = 'main' ) {
return this.roots.get( name );
}
/**
* Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
* to the DOM.
*
* Post-fixers are executed right after all changes from the outermost change block were applied but
* before the {@link module:engine/view/view~View#event:render render event} is fired. If a post-fixer callback made
* a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
* not be fixed in the new document tree state.
*
* View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
* changes executed in a view post-fixer should not break model-view mapping.
*
* The types of changes which should be safe:
*
* * adding or removing attribute from elements,
* * changes inside of {@link module:engine/view/uielement~UIElement UI elements},
* * {@link module:engine/model/differ~Differ#refreshItem marking some of the model elements to be re-converted}.
*
* Try to avoid changes which touch view structure:
*
* * you should not add or remove nor wrap or unwrap any view elements,
* * you should not change the editor data model in a view post-fixer.
*
* As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}.
*
* Typically, a post-fixer will look like this:
*
* editor.editing.view.document.registerPostFixer( writer => {
* if ( checkSomeCondition() ) {
* writer.doSomething();
*
* // Let other post-fixers know that something changed.
* return true;
* }
* } );
*
* Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
* That is because adding a post-fixer does not execute it.
* The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
* If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
* {@link module:engine/view/view~View#forceRender `view.forceRender()`}.
*
* If you need to register a callback which is executed when DOM elements are already updated,
* use {@link module:engine/view/view~View#event:render render event}.
*
* @param {Function} postFixer
*/
registerPostFixer( postFixer ) {
this._postFixers.add( postFixer );
}
/**
* Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
*/
destroy() {
this.roots.map( root => root.destroy() );
this.stopListening();
}
/**
* Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
*
* @protected
* @param {module:engine/view/downcastwriter~DowncastWriter} writer
*/
_callPostFixers( writer ) {
let wasFixed = false;
do {
for ( const callback of this._postFixers ) {
wasFixed = callback( writer );
if ( wasFixed ) {
break;
}
}
} while ( wasFixed );
}
/**
* Event fired whenever document content layout changes. It is fired whenever content is
* {@link module:engine/view/view~View#event:render rendered}, but should be also fired by observers in case of
* other actions which may change layout, for instance when image loads.
*
* @event layoutChanged
*/
// @if CK_DEBUG_ENGINE // log( version ) {
// @if CK_DEBUG_ENGINE // logDocument( this, version );
// @if CK_DEBUG_ENGINE // }
}
mix( Document, BubblingEmitterMixin );
mix( Document, ObservableMixin );
/**
* Enum representing type of the change.
*
* Possible values:
*
* * `children` - for child list changes,
* * `attributes` - for element attributes changes,
* * `text` - for text nodes changes.
*
* @typedef {String} module:engine/view/document~ChangeType
*/