1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 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"
12 interface nsISelectionController
;
13 interface nsIDocumentStateListener
;
14 interface nsIOutputStream
;
15 interface nsITransactionManager
;
16 interface nsITransaction
;
17 interface nsIEditorObserver
;
18 interface nsIEditActionListener
;
19 interface nsIInlineSpellChecker
;
20 interface nsITransferable
;
32 } // namespace mozilla
35 [scriptable
, builtinclass
, uuid(094be624
-f0bf
-400f
-89e2
-6a84baab9474
)]
36 interface nsIEditor
: nsISupports
39 typedef short EDirection
;
40 typedef short EStripWrappers
;
42 const short eNone
= 0;
43 const short eNext
= 1;
44 const short ePrevious
= 2;
45 const short eNextWord
= 3;
46 const short ePreviousWord
= 4;
47 const short eToBeginningOfLine
= 5;
48 const short eToEndOfLine
= 6;
50 const short eStrip
= 0;
51 const short eNoStrip
= 1;
53 readonly attribute Selection selection
;
55 void setAttributeOrEquivalent
(in Element element
,
56 in AString sourceAttrName
,
57 in AString sourceAttrValue
,
58 in boolean aSuppressTransaction
);
59 void removeAttributeOrEquivalent
(in Element element
,
60 in AString sourceAttrName
,
61 in boolean aSuppressTransaction
);
63 /** edit flags for this editor. May be set at any time. */
64 attribute
unsigned long flags
;
67 * the MimeType of the document
69 attribute
string contentsMIMEType
;
71 /** Returns true if we have a document that is not marked read-only */
72 readonly attribute
boolean isDocumentEditable
;
74 /** Returns true if the current selection anchor is editable */
75 readonly attribute
boolean isSelectionEditable
;
78 * the DOM Document this editor is associated with, refcounted.
80 readonly attribute Document document
;
82 /** the body element, i.e. the root of the editable document.
84 readonly attribute Element rootElement
;
87 * the selection controller for the current presentation, refcounted.
89 readonly attribute nsISelectionController selectionController
;
92 /* ------------ Selected content removal -------------- */
95 * DeleteSelection removes all nodes in the current selection.
96 * @param aDir if eNext, delete to the right (for example, the DEL key)
97 * if ePrevious, delete to the left (for example, the BACKSPACE key)
98 * @param stripWrappers If eStrip, strip any empty inline elements left
99 * behind after the deletion; if eNoStrip, don't. If in
100 * doubt, pass eStrip -- eNoStrip is only for if you're
101 * about to insert text or similar right after.
103 void deleteSelection
(in short action
, in short stripWrappers
);
106 /* ------------ Document info and file methods -------------- */
108 /** Returns true if the document has no *meaningful* content */
109 readonly attribute
boolean documentIsEmpty
;
111 /** Returns true if the document is modifed and needs saving */
112 readonly attribute
boolean documentModified
;
114 /** Sets the current 'Save' document character set */
115 attribute ACString documentCharacterSet
;
117 /** to be used ONLY when we need to override the doc's modification
118 * state (such as when it's saved).
120 void resetModificationCount
();
122 /** Gets the modification count of the document we are editing.
123 * @return the modification count of the document being edited.
124 * Zero means unchanged.
126 long getModificationCount
();
128 /** called each time we modify the document.
129 * Increments the modification count of the document.
130 * @param aModCount the number of modifications by which
131 * to increase or decrease the count
133 void incrementModificationCount
(in long aModCount
);
135 /* ------------ Transaction methods -------------- */
137 /** transactionManager Get the transaction manager the editor is using.
139 readonly attribute nsITransactionManager transactionManager
;
141 /** doTransaction() fires a transaction.
142 * It is provided here so clients can create their own transactions.
143 * If a transaction manager is present, it is used.
144 * Otherwise, the transaction is just executed directly.
146 * @param aTxn the transaction to execute
148 void doTransaction
(in nsITransaction txn
);
151 /** turn the undo system on or off
152 * @param aEnable if PR_TRUE, the undo system is turned on if available
153 * if PR_FALSE the undo system is turned off if it
155 * @return if aEnable is PR_TRUE, returns NS_OK if
156 * the undo system could be initialized properly
157 * if aEnable is PR_FALSE, returns NS_OK.
159 void enableUndo
(in boolean enable
);
161 /** undo reverses the effects of the last Do operation,
162 * if Undo is enabled in the editor.
163 * It is provided here so clients need no knowledge of whether
164 * the editor has a transaction manager or not.
165 * If a transaction manager is present, it is told to undo,
166 * and the result of that undo is returned.
167 * Otherwise, the Undo request is ignored and an
168 * error NS_ERROR_NOT_AVAILABLE is returned.
171 void undo
(in unsigned long count
);
173 /** returns state information about the undo system.
174 * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
175 * @param aCanUndo [OUT] PR_TRUE if at least one transaction is
176 * currently ready to be undone.
178 void canUndo
(out boolean isEnabled
, out boolean canUndo
);
180 /** redo reverses the effects of the last Undo operation
181 * It is provided here so clients need no knowledge of whether
182 * the editor has a transaction manager or not.
183 * If a transaction manager is present, it is told to redo and the
184 * result of the previously undone transaction is reapplied to the document.
185 * If no transaction is available for Redo, or if the document
186 * has no transaction manager, the Redo request is ignored and an
187 * error NS_ERROR_NOT_AVAILABLE is returned.
190 void redo
(in unsigned long count
);
192 /** returns state information about the redo system.
193 * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
194 * @param aCanRedo [OUT] PR_TRUE if at least one transaction is
195 currently ready to be redone.
197 void canRedo
(out boolean isEnabled
, out boolean canRedo
);
199 /** beginTransaction is a signal from the caller to the editor that
200 * the caller will execute multiple updates to the content tree
201 * that should be treated as a single logical operation,
202 * in the most efficient way possible.<br>
203 * All transactions executed between a call to beginTransaction and
204 * endTransaction will be undoable as an atomic action.<br>
205 * endTransaction must be called after beginTransaction.<br>
206 * Calls to beginTransaction can be nested, as long as endTransaction
207 * is called once per beginUpdate.
209 void beginTransaction
();
211 /** endTransaction is a signal to the editor that the caller is
212 * finished updating the content model.<br>
213 * beginUpdate must be called before endTransaction is called.<br>
214 * Calls to beginTransaction can be nested, as long as endTransaction
215 * is called once per beginTransaction.
217 void endTransaction
();
220 * While setting the flag with this method to false, CreateElementTransaction,
221 * DeleteRangeTransaction, DeleteTextTransaction, InsertNodeTransaction,
222 * InsertTextTransaction and SplitNodeTransaction won't change Selection
223 * after modifying the DOM tree.
224 * Note that calling this with false does not guarantee that Selection won't
225 * be changed because other transaction may ignore this flag, editor itself
226 * may change selection, and current selection may become invalid after
227 * changing the DOM tree, etc.
228 * After calling this method with true, the caller should guarantee that
229 * Selection should be positioned where user expects.
231 * @param should false if you don't want above transactions to modify
232 * Selection automatically after modifying the DOM tree.
233 * Note that calling this with false does not guarantee
234 * that Selection is never changed.
236 void setShouldTxnSetSelection
(in boolean should
);
238 /* ------------ Inline Spell Checking methods -------------- */
240 /** Returns the inline spell checker associated with this object. The spell
241 * checker is lazily created, so this function may create the object for
242 * you during this call.
243 * @param autoCreate If true, this will create a spell checker object
244 * if one does not exist yet for this editor. If false
245 * and the object has not been created, this function
248 nsIInlineSpellChecker getInlineSpellChecker
(in boolean autoCreate
);
250 /** Called when the user manually overrides the spellchecking state for this
252 * @param enable The new state of spellchecking in this editor, as
253 * requested by the user.
255 void setSpellcheckUserOverride
(in boolean enable
);
257 /* ------------ Clipboard methods -------------- */
259 /** cut the currently selected text, putting it into the OS clipboard
260 * What if no text is selected?
261 * What about mixed selections?
262 * What are the clipboard formats?
266 /** Can we cut? True if the doc is modifiable, and we have a non-
267 * collapsed selection.
271 /** copy the currently selected text, putting it into the OS clipboard
272 * What if no text is selected?
273 * What about mixed selections?
274 * What are the clipboard formats?
278 /** Can we copy? True if we have a non-collapsed selection.
282 /** Can we delete? True if we have a non-collapsed selection.
286 /** paste the text in the OS clipboard at the cursor position, replacing
287 * the selected text (if any)
289 void paste
(in long aSelectionType
);
291 /** Paste the text in |aTransferable| at the cursor position, replacing the
292 * selected text (if any).
294 void pasteTransferable
(in nsITransferable aTransferable
);
296 /** Can we paste? True if the doc is modifiable, and we have
297 * pasteable data in the clipboard.
299 boolean canPaste
(in long aSelectionType
);
301 /* ------------ Selection methods -------------- */
303 /** sets the document selection to the entire contents of the document */
307 * Collapses selection at start of the document. If it's an HTML editor,
308 * collapses selection at start of current editing host (<body> element if
309 * it's in designMode) instead. If there is a non-editable node before any
310 * editable text nodes or inline elements which can have text nodes as their
311 * children, collapses selection at start of the editing host. If there is
312 * an editable text node which is not collapsed, collapses selection at
313 * start of the text node. If there is an editable inline element which
314 * cannot have text nodes as its child, collapses selection at before the
315 * element node. Otherwise, collapses selection at start of the editing
318 void beginningOfDocument
();
320 /** sets the document selection to the end of the document */
321 void endOfDocument
();
323 /* ------------ Node manipulation methods -------------- */
326 * setAttribute() sets the attribute of aElement.
327 * No checking is done to see if aAttribute is a legal attribute of the node,
328 * or if aValue is a legal value of aAttribute.
330 * @param aElement the content element to operate on
331 * @param aAttribute the string representation of the attribute to set
332 * @param aValue the value to set aAttribute to
334 void setAttribute
(in Element aElement
, in AString attributestr
,
335 in AString attvalue
);
338 * getAttributeValue() retrieves the attribute's value for aElement.
340 * @param aElement the content element to operate on
341 * @param aAttribute the string representation of the attribute to get
342 * @param aResultValue [OUT] the value of aAttribute.
343 * Only valid if aResultIsSet is PR_TRUE
344 * @return PR_TRUE if aAttribute is set on the current node,
345 * PR_FALSE if it is not.
347 boolean getAttributeValue
(in Element aElement
,
348 in AString attributestr
,
349 out AString resultValue
);
352 * removeAttribute() deletes aAttribute from the attribute list of aElement.
353 * If aAttribute is not an attribute of aElement, nothing is done.
355 * @param aElement the content element to operate on
356 * @param aAttribute the string representation of the attribute to get
358 void removeAttribute
(in Element aElement
,
359 in AString aAttribute
);
362 * cloneAttribute() copies the attribute from the source node to
363 * the destination node and delete those not in the source.
365 * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
366 * @param aAttribute the name of the attribute to copy
367 * @param aDestElement the destination element to operate on
368 * @param aSourceElement the source element to copy attributes from
369 * @exception NS_ERROR_NULL_POINTER at least one of the elements is null
371 void cloneAttribute
(in AString aAttribute
,
372 in Element aDestElement
, in Element aSourceElement
);
375 * cloneAttributes() is similar to Node::cloneNode(),
376 * it assures the attribute nodes of the destination are identical
377 * with the source node by copying all existing attributes from the
378 * source and deleting those not in the source.
379 * This is used when the destination element already exists
381 * @param aDestNode the destination element to operate on
382 * @param aSourceNode the source element to copy attributes from
384 void cloneAttributes
(in Element aDestElement
, in Element aSourceElement
);
387 * insertNode inserts aNode into aParent at aPosition.
388 * No checking is done to verify the legality of the insertion.
389 * That is the responsibility of the caller.
390 * @param aNode The DOM Node to insert.
391 * @param aParent The node to insert the new object into
392 * @param aPosition The place in aParent to insert the new node
393 * 0=first child, 1=second child, etc.
394 * any number > number of current children = last child
396 void insertNode
(in Node node
,
402 * splitNode() creates a new node identical to an existing node,
403 * and split the contents between the two nodes
404 * @param aExistingRightNode the node to split.
405 * It will become the new node's next sibling.
406 * @param aOffset the offset of aExistingRightNode's
407 * content|children to do the split at
408 * @param aNewLeftNode [OUT] the new node resulting from the split,
409 * becomes aExistingRightNode's previous sibling.
411 void splitNode
(in Node existingRightNode
,
413 out Node newLeftNode
);
416 * joinNodes() takes 2 nodes and merge their content|children.
417 * @param aLeftNode The left node. It will be deleted.
418 * @param aRightNode The right node. It will remain after the join.
419 * @param aParent The parent of aExistingRightNode
421 * There is no requirement that the two nodes be
422 * of the same type. However, a text node can be
423 * merged only with another text node.
425 void joinNodes
(in Node leftNode
,
430 * deleteNode removes aChild from aParent.
431 * @param aChild The node to delete
433 void deleteNode
(in Node child
);
436 * markNodeDirty() sets a special dirty attribute on the node.
437 * Usually this will be called immediately after creating a new node.
438 * @param aNode The node for which to insert formatting.
440 void markNodeDirty
(in Node node
);
442 /* ------------ Output methods -------------- */
446 * aFormatType is a mime type, like text/plain.
448 AString outputToString
(in AString formatType
,
449 in unsigned long flags
);
451 /* ------------ Various listeners methods --------------
452 * nsIEditor holds strong references to the editor observers, action listeners
453 * and document state listeners.
456 /** add an EditorObserver to the editors list of observers. */
457 void addEditorObserver
(in nsIEditorObserver observer
);
459 /** Remove an EditorObserver from the editor's list of observers. */
460 void removeEditorObserver
(in nsIEditorObserver observer
);
462 /** add an EditActionListener to the editors list of listeners. */
463 void addEditActionListener
(in nsIEditActionListener listener
);
465 /** Remove an EditActionListener from the editor's list of listeners. */
466 void removeEditActionListener
(in nsIEditActionListener listener
);
468 /** Add a DocumentStateListener to the editors list of doc state listeners. */
469 void addDocumentStateListener
(in nsIDocumentStateListener listener
);
471 /** Remove a DocumentStateListener to the editors list of doc state listeners. */
472 void removeDocumentStateListener
(in nsIDocumentStateListener listener
);
475 * forceCompositionEnd() force the composition end
477 void forceCompositionEnd
();
480 * whether this editor has active IME transaction
482 readonly attribute
boolean composing
;
486 * AsEditorBase() returns a pointer to EditorBase class.
488 * In order to avoid circular dependency issues, this method is defined
489 * in mozilla/EditorBase.h. Consumers need to #include that header.
491 inline mozilla
::EditorBase
* AsEditorBase
();
492 inline
const mozilla
::EditorBase
* AsEditorBase
() const;
495 * AsTextEditor() returns a pointer to TextEditor class.
497 * In order to avoid circular dependency issues, this method is defined
498 * in mozilla/TextEditor.h. Consumers need to #include that header.
500 inline mozilla
::TextEditor
* AsTextEditor
();
501 inline
const mozilla
::TextEditor
* AsTextEditor
() const;
504 * AsHTMLEditor() returns a pointer to HTMLEditor class.
506 * In order to avoid circular dependency issues, this method is defined
507 * in mozilla/HTMLEditor.h. Consumers need to #include that header.
509 inline mozilla
::HTMLEditor
* AsHTMLEditor
();
510 inline
const mozilla
::HTMLEditor
* AsHTMLEditor
() const;