editor/idl/nsIEditor.idl@97036ab72558
editor/idl/nsIEditor.idl
Tue, 06 Jan 2015 21:39:09 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Tue, 06 Jan 2015 21:39:09 +0100
- branch
- TOR_BUG_9701
- changeset 8
- 97036ab72558
- permissions
- -rw-r--r--
Conditionally force memory storage according to privacy.thirdparty.isolate;
This solves Tor bug #9701, complying with disk avoidance documented in
https://www.torproject.org/projects/torbrowser/design/#disk-avoidance.
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
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/. */
7 #include "nsISupports.idl"
8 #include "domstubs.idl"
10 interface nsIURI;
11 interface nsIAtom;
12 interface nsIContent;
13 interface nsISelection;
14 interface nsISelectionController;
15 interface nsIDocumentStateListener;
16 interface nsIOutputStream;
17 interface nsITransactionManager;
18 interface nsITransaction;
19 interface nsIEditorObserver;
20 interface nsIEditActionListener;
21 interface nsIInlineSpellChecker;
22 interface nsITransferable;
24 [scriptable, uuid(65523eab-db1f-44aa-893e-dfe57ad306f0)]
26 interface nsIEditor : nsISupports
27 {
28 %{C++
29 typedef short EDirection;
30 typedef short EStripWrappers;
31 %}
32 const short eNone = 0;
33 const short eNext = 1;
34 const short ePrevious = 2;
35 const short eNextWord = 3;
36 const short ePreviousWord = 4;
37 const short eToBeginningOfLine = 5;
38 const short eToEndOfLine = 6;
40 const short eStrip = 0;
41 const short eNoStrip = 1;
43 readonly attribute nsISelection selection;
45 /**
46 * Init is to tell the implementation of nsIEditor to begin its services
47 * @param aDoc The dom document interface being observed
48 * @param aRoot This is the root of the editable section of this
49 * document. If it is null then we get root
50 * from document body.
51 * @param aSelCon this should be used to get the selection location
52 * (will be null for HTML editors)
53 * @param aFlags A bitmask of flags for specifying the behavior
54 * of the editor.
55 */
56 [noscript] void init(in nsIDOMDocument doc,
57 in nsIContent aRoot,
58 in nsISelectionController aSelCon,
59 in unsigned long aFlags,
60 in AString initialValue);
62 void setAttributeOrEquivalent(in nsIDOMElement element,
63 in AString sourceAttrName,
64 in AString sourceAttrValue,
65 in boolean aSuppressTransaction);
66 void removeAttributeOrEquivalent(in nsIDOMElement element,
67 in DOMString sourceAttrName,
68 in boolean aSuppressTransaction);
70 /**
71 * postCreate should be called after Init, and is the time that the editor
72 * tells its documentStateObservers that the document has been created.
73 */
74 void postCreate();
76 /**
77 * preDestroy is called before the editor goes away, and gives the editor a
78 * chance to tell its documentStateObservers that the document is going away.
79 * @param aDestroyingFrames set to true when the frames being edited
80 * are being destroyed (so there is no need to modify any nsISelections,
81 * nor is it safe to do so)
82 */
83 void preDestroy(in boolean aDestroyingFrames);
85 /** edit flags for this editor. May be set at any time. */
86 attribute unsigned long flags;
88 /**
89 * the MimeType of the document
90 */
91 attribute string contentsMIMEType;
93 /** Returns true if we have a document that is not marked read-only */
94 readonly attribute boolean isDocumentEditable;
96 /** Returns true if the current selection anchor is editable */
97 readonly attribute boolean isSelectionEditable;
99 /**
100 * the DOM Document this editor is associated with, refcounted.
101 */
102 readonly attribute nsIDOMDocument document;
104 /** the body element, i.e. the root of the editable document.
105 */
106 readonly attribute nsIDOMElement rootElement;
108 /**
109 * the selection controller for the current presentation, refcounted.
110 */
111 readonly attribute nsISelectionController selectionController;
114 /* ------------ Selected content removal -------------- */
116 /**
117 * DeleteSelection removes all nodes in the current selection.
118 * @param aDir if eNext, delete to the right (for example, the DEL key)
119 * if ePrevious, delete to the left (for example, the BACKSPACE key)
120 * @param stripWrappers If eStrip, strip any empty inline elements left
121 * behind after the deletion; if eNoStrip, don't. If in
122 * doubt, pass eStrip -- eNoStrip is only for if you're
123 * about to insert text or similar right after.
124 */
125 void deleteSelection(in short action, in short stripWrappers);
128 /* ------------ Document info and file methods -------------- */
130 /** Returns true if the document has no *meaningful* content */
131 readonly attribute boolean documentIsEmpty;
133 /** Returns true if the document is modifed and needs saving */
134 readonly attribute boolean documentModified;
136 /** Sets the current 'Save' document character set */
137 attribute ACString documentCharacterSet;
139 /** to be used ONLY when we need to override the doc's modification
140 * state (such as when it's saved).
141 */
142 void resetModificationCount();
144 /** Gets the modification count of the document we are editing.
145 * @return the modification count of the document being edited.
146 * Zero means unchanged.
147 */
148 long getModificationCount();
150 /** called each time we modify the document.
151 * Increments the modification count of the document.
152 * @param aModCount the number of modifications by which
153 * to increase or decrease the count
154 */
155 void incrementModificationCount(in long aModCount);
157 /* ------------ Transaction methods -------------- */
159 /** transactionManager Get the transaction manager the editor is using.
160 */
161 attribute nsITransactionManager transactionManager;
163 /** doTransaction() fires a transaction.
164 * It is provided here so clients can create their own transactions.
165 * If a transaction manager is present, it is used.
166 * Otherwise, the transaction is just executed directly.
167 *
168 * @param aTxn the transaction to execute
169 */
170 void doTransaction(in nsITransaction txn);
173 /** turn the undo system on or off
174 * @param aEnable if PR_TRUE, the undo system is turned on if available
175 * if PR_FALSE the undo system is turned off if it
176 * was previously on
177 * @return if aEnable is PR_TRUE, returns NS_OK if
178 * the undo system could be initialized properly
179 * if aEnable is PR_FALSE, returns NS_OK.
180 */
181 void enableUndo(in boolean enable);
183 /**
184 * The number of items on the undo stack.
185 */
186 readonly attribute long numberOfUndoItems;
188 /**
189 * The number of items on the redo stack.
190 */
191 readonly attribute long numberOfRedoItems;
193 /** undo reverses the effects of the last Do operation,
194 * if Undo is enabled in the editor.
195 * It is provided here so clients need no knowledge of whether
196 * the editor has a transaction manager or not.
197 * If a transaction manager is present, it is told to undo,
198 * and the result of that undo is returned.
199 * Otherwise, the Undo request is ignored and an
200 * error NS_ERROR_NOT_AVAILABLE is returned.
201 *
202 */
203 void undo(in unsigned long count);
205 /** returns state information about the undo system.
206 * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
207 * @param aCanUndo [OUT] PR_TRUE if at least one transaction is
208 * currently ready to be undone.
209 */
210 void canUndo(out boolean isEnabled, out boolean canUndo);
212 /** redo reverses the effects of the last Undo operation
213 * It is provided here so clients need no knowledge of whether
214 * the editor has a transaction manager or not.
215 * If a transaction manager is present, it is told to redo and the
216 * result of the previously undone transaction is reapplied to the document.
217 * If no transaction is available for Redo, or if the document
218 * has no transaction manager, the Redo request is ignored and an
219 * error NS_ERROR_NOT_AVAILABLE is returned.
220 *
221 */
222 void redo(in unsigned long count);
224 /** returns state information about the redo system.
225 * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
226 * @param aCanRedo [OUT] PR_TRUE if at least one transaction is
227 currently ready to be redone.
228 */
229 void canRedo(out boolean isEnabled, out boolean canRedo);
231 /** beginTransaction is a signal from the caller to the editor that
232 * the caller will execute multiple updates to the content tree
233 * that should be treated as a single logical operation,
234 * in the most efficient way possible.<br>
235 * All transactions executed between a call to beginTransaction and
236 * endTransaction will be undoable as an atomic action.<br>
237 * endTransaction must be called after beginTransaction.<br>
238 * Calls to beginTransaction can be nested, as long as endTransaction
239 * is called once per beginUpdate.
240 */
241 void beginTransaction();
243 /** endTransaction is a signal to the editor that the caller is
244 * finished updating the content model.<br>
245 * beginUpdate must be called before endTransaction is called.<br>
246 * Calls to beginTransaction can be nested, as long as endTransaction
247 * is called once per beginTransaction.
248 */
249 void endTransaction();
251 void beginPlaceHolderTransaction(in nsIAtom name);
252 void endPlaceHolderTransaction();
253 boolean shouldTxnSetSelection();
255 /** Set the flag that prevents insertElementTxn from changing the selection
256 * @param should Set false to suppress changing the selection;
257 * i.e., before using InsertElement() to insert
258 * under <head> element
259 * WARNING: You must be very careful to reset back to PR_TRUE after
260 * setting PR_FALSE, else selection/caret is trashed
261 * for further editing.
262 */
263 void setShouldTxnSetSelection(in boolean should);
265 /* ------------ Inline Spell Checking methods -------------- */
267 /** Returns the inline spell checker associated with this object. The spell
268 * checker is lazily created, so this function may create the object for
269 * you during this call.
270 * @param autoCreate If true, this will create a spell checker object
271 * if one does not exist yet for this editor. If false
272 * and the object has not been created, this function
273 * WILL RETURN NULL.
274 */
275 nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);
277 /** Resyncs spellchecking state (enabled/disabled). This should be called
278 * when anything that affects spellchecking state changes, such as the
279 * spellcheck attribute value.
280 */
281 void syncRealTimeSpell();
283 /** Called when the user manually overrides the spellchecking state for this
284 * editor.
285 * @param enable The new state of spellchecking in this editor, as
286 * requested by the user.
287 */
288 void setSpellcheckUserOverride(in boolean enable);
290 /* ------------ Clipboard methods -------------- */
292 /** cut the currently selected text, putting it into the OS clipboard
293 * What if no text is selected?
294 * What about mixed selections?
295 * What are the clipboard formats?
296 */
297 void cut();
299 /** Can we cut? True if the doc is modifiable, and we have a non-
300 * collapsed selection.
301 */
302 boolean canCut();
304 /** copy the currently selected text, putting it into the OS clipboard
305 * What if no text is selected?
306 * What about mixed selections?
307 * What are the clipboard formats?
308 */
309 void copy();
311 /** Can we copy? True if we have a non-collapsed selection.
312 */
313 boolean canCopy();
315 /** paste the text in the OS clipboard at the cursor position, replacing
316 * the selected text (if any)
317 */
318 void paste(in long aSelectionType);
320 /** Paste the text in |aTransferable| at the cursor position, replacing the
321 * selected text (if any).
322 */
323 void pasteTransferable(in nsITransferable aTransferable);
325 /** Can we paste? True if the doc is modifiable, and we have
326 * pasteable data in the clipboard.
327 */
328 boolean canPaste(in long aSelectionType);
330 /** Can we paste |aTransferable| or, if |aTransferable| is null, will a call
331 * to pasteTransferable later possibly succeed if given an instance of
332 * nsITransferable then? True if the doc is modifiable, and, if
333 * |aTransfeable| is non-null, we have pasteable data in |aTransfeable|.
334 */
335 boolean canPasteTransferable([optional] in nsITransferable aTransferable);
337 /* ------------ Selection methods -------------- */
339 /** sets the document selection to the entire contents of the document */
340 void selectAll();
342 /** sets the document selection to the beginning of the document */
343 void beginningOfDocument();
345 /** sets the document selection to the end of the document */
346 void endOfDocument();
348 /* ------------ Node manipulation methods -------------- */
350 /**
351 * setAttribute() sets the attribute of aElement.
352 * No checking is done to see if aAttribute is a legal attribute of the node,
353 * or if aValue is a legal value of aAttribute.
354 *
355 * @param aElement the content element to operate on
356 * @param aAttribute the string representation of the attribute to set
357 * @param aValue the value to set aAttribute to
358 */
359 void setAttribute(in nsIDOMElement aElement, in AString attributestr,
360 in AString attvalue);
362 /**
363 * getAttributeValue() retrieves the attribute's value for aElement.
364 *
365 * @param aElement the content element to operate on
366 * @param aAttribute the string representation of the attribute to get
367 * @param aResultValue [OUT] the value of aAttribute.
368 * Only valid if aResultIsSet is PR_TRUE
369 * @return PR_TRUE if aAttribute is set on the current node,
370 * PR_FALSE if it is not.
371 */
372 boolean getAttributeValue(in nsIDOMElement aElement,
373 in AString attributestr,
374 out AString resultValue);
376 /**
377 * removeAttribute() deletes aAttribute from the attribute list of aElement.
378 * If aAttribute is not an attribute of aElement, nothing is done.
379 *
380 * @param aElement the content element to operate on
381 * @param aAttribute the string representation of the attribute to get
382 */
383 void removeAttribute(in nsIDOMElement aElement,
384 in AString aAttribute);
386 /**
387 * cloneAttribute() copies the attribute from the source node to
388 * the destination node and delete those not in the source.
389 *
390 * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
391 * @param aAttribute the name of the attribute to copy
392 * @param aDestNode the destination element to operate on
393 * @param aSourceNode the source element to copy attributes from
394 * @exception NS_ERROR_NULL_POINTER at least one of the nodes is null
395 * @exception NS_ERROR_NO_INTERFACE at least one of the nodes is not an
396 * element
397 */
398 void cloneAttribute(in AString aAttribute,
399 in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode);
401 /**
402 * cloneAttributes() is similar to nsIDOMNode::cloneNode(),
403 * it assures the attribute nodes of the destination are identical
404 * with the source node by copying all existing attributes from the
405 * source and deleting those not in the source.
406 * This is used when the destination node (element) already exists
407 *
408 * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
409 * @param aDestNode the destination element to operate on
410 * @param aSourceNode the source element to copy attributes from
411 */
412 void cloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode);
414 /**
415 * createNode instantiates a new element of type aTag and inserts it
416 * into aParent at aPosition.
417 * @param aTag The type of object to create
418 * @param aParent The node to insert the new object into
419 * @param aPosition The place in aParent to insert the new node
420 * @return The node created. Caller must release aNewNode.
421 */
422 nsIDOMNode createNode(in AString tag,
423 in nsIDOMNode parent,
424 in long position);
426 /**
427 * insertNode inserts aNode into aParent at aPosition.
428 * No checking is done to verify the legality of the insertion.
429 * That is the responsibility of the caller.
430 * @param aNode The DOM Node to insert.
431 * @param aParent The node to insert the new object into
432 * @param aPosition The place in aParent to insert the new node
433 * 0=first child, 1=second child, etc.
434 * any number > number of current children = last child
435 */
436 void insertNode(in nsIDOMNode node,
437 in nsIDOMNode parent,
438 in long aPosition);
441 /**
442 * splitNode() creates a new node identical to an existing node,
443 * and split the contents between the two nodes
444 * @param aExistingRightNode the node to split.
445 * It will become the new node's next sibling.
446 * @param aOffset the offset of aExistingRightNode's
447 * content|children to do the split at
448 * @param aNewLeftNode [OUT] the new node resulting from the split,
449 * becomes aExistingRightNode's previous sibling.
450 */
451 void splitNode(in nsIDOMNode existingRightNode,
452 in long offset,
453 out nsIDOMNode newLeftNode);
455 /**
456 * joinNodes() takes 2 nodes and merge their content|children.
457 * @param aLeftNode The left node. It will be deleted.
458 * @param aRightNode The right node. It will remain after the join.
459 * @param aParent The parent of aExistingRightNode
460 *
461 * There is no requirement that the two nodes be
462 * of the same type. However, a text node can be
463 * merged only with another text node.
464 */
465 void joinNodes(in nsIDOMNode leftNode,
466 in nsIDOMNode rightNode,
467 in nsIDOMNode parent);
469 /**
470 * deleteNode removes aChild from aParent.
471 * @param aChild The node to delete
472 */
473 void deleteNode(in nsIDOMNode child);
475 /**
476 * Returns true if markNodeDirty() has any effect. Returns false if
477 * markNodeDirty() is a no-op.
478 */
479 [notxpcom] boolean outputsMozDirty();
481 /**
482 * markNodeDirty() sets a special dirty attribute on the node.
483 * Usually this will be called immediately after creating a new node.
484 * @param aNode The node for which to insert formatting.
485 */
486 void markNodeDirty(in nsIDOMNode node);
488 /* ---------- direction controller ---------- */
490 /**
491 * Switches the editor element direction; from "Left-to-Right" to
492 * "Right-to-Left", and vice versa.
493 */
494 void switchTextDirection();
496 /* ------------ Output methods -------------- */
498 /**
499 * Output methods:
500 * aFormatType is a mime type, like text/plain.
501 */
502 AString outputToString(in AString formatType,
503 in unsigned long flags);
504 void outputToStream(in nsIOutputStream aStream,
505 in AString formatType,
506 in ACString charsetOverride,
507 in unsigned long flags);
510 /* ------------ Various listeners methods --------------
511 * nsIEditor holds strong references to the editor observers, action listeners
512 * and document state listeners.
513 */
515 /** add an EditorObserver to the editors list of observers. */
516 void addEditorObserver(in nsIEditorObserver observer);
518 /** Remove an EditorObserver from the editor's list of observers. */
519 void removeEditorObserver(in nsIEditorObserver observer);
521 /** add an EditActionListener to the editors list of listeners. */
522 void addEditActionListener(in nsIEditActionListener listener);
524 /** Remove an EditActionListener from the editor's list of listeners. */
525 void removeEditActionListener(in nsIEditActionListener listener);
527 /** Add a DocumentStateListener to the editors list of doc state listeners. */
528 void addDocumentStateListener(in nsIDocumentStateListener listener);
530 /** Remove a DocumentStateListener to the editors list of doc state listeners. */
531 void removeDocumentStateListener(in nsIDocumentStateListener listener);
534 /* ------------ Debug methods -------------- */
536 /**
537 * And a debug method -- show us what the tree looks like right now
538 */
539 void dumpContentTree();
541 /** Dumps a text representation of the content tree to standard out */
542 void debugDumpContent() ;
544 /* Run unit tests. Noop in optimized builds */
545 void debugUnitTests(out long outNumTests, out long outNumTestsFailed);
547 /* checks if a node is read-only or not */
548 [notxpcom] boolean isModifiableNode(in nsIDOMNode aNode);
550 /* Set true if you want to suppress dispatching input event. */
551 attribute boolean suppressDispatchingInputEvent;
552 };
