1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/editor/idl/nsIEditor.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,552 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +#include "domstubs.idl"
1.12 +
1.13 +interface nsIURI;
1.14 +interface nsIAtom;
1.15 +interface nsIContent;
1.16 +interface nsISelection;
1.17 +interface nsISelectionController;
1.18 +interface nsIDocumentStateListener;
1.19 +interface nsIOutputStream;
1.20 +interface nsITransactionManager;
1.21 +interface nsITransaction;
1.22 +interface nsIEditorObserver;
1.23 +interface nsIEditActionListener;
1.24 +interface nsIInlineSpellChecker;
1.25 +interface nsITransferable;
1.26 +
1.27 +[scriptable, uuid(65523eab-db1f-44aa-893e-dfe57ad306f0)]
1.28 +
1.29 +interface nsIEditor : nsISupports
1.30 +{
1.31 +%{C++
1.32 + typedef short EDirection;
1.33 + typedef short EStripWrappers;
1.34 +%}
1.35 + const short eNone = 0;
1.36 + const short eNext = 1;
1.37 + const short ePrevious = 2;
1.38 + const short eNextWord = 3;
1.39 + const short ePreviousWord = 4;
1.40 + const short eToBeginningOfLine = 5;
1.41 + const short eToEndOfLine = 6;
1.42 +
1.43 + const short eStrip = 0;
1.44 + const short eNoStrip = 1;
1.45 +
1.46 + readonly attribute nsISelection selection;
1.47 +
1.48 + /**
1.49 + * Init is to tell the implementation of nsIEditor to begin its services
1.50 + * @param aDoc The dom document interface being observed
1.51 + * @param aRoot This is the root of the editable section of this
1.52 + * document. If it is null then we get root
1.53 + * from document body.
1.54 + * @param aSelCon this should be used to get the selection location
1.55 + * (will be null for HTML editors)
1.56 + * @param aFlags A bitmask of flags for specifying the behavior
1.57 + * of the editor.
1.58 + */
1.59 + [noscript] void init(in nsIDOMDocument doc,
1.60 + in nsIContent aRoot,
1.61 + in nsISelectionController aSelCon,
1.62 + in unsigned long aFlags,
1.63 + in AString initialValue);
1.64 +
1.65 + void setAttributeOrEquivalent(in nsIDOMElement element,
1.66 + in AString sourceAttrName,
1.67 + in AString sourceAttrValue,
1.68 + in boolean aSuppressTransaction);
1.69 + void removeAttributeOrEquivalent(in nsIDOMElement element,
1.70 + in DOMString sourceAttrName,
1.71 + in boolean aSuppressTransaction);
1.72 +
1.73 + /**
1.74 + * postCreate should be called after Init, and is the time that the editor
1.75 + * tells its documentStateObservers that the document has been created.
1.76 + */
1.77 + void postCreate();
1.78 +
1.79 + /**
1.80 + * preDestroy is called before the editor goes away, and gives the editor a
1.81 + * chance to tell its documentStateObservers that the document is going away.
1.82 + * @param aDestroyingFrames set to true when the frames being edited
1.83 + * are being destroyed (so there is no need to modify any nsISelections,
1.84 + * nor is it safe to do so)
1.85 + */
1.86 + void preDestroy(in boolean aDestroyingFrames);
1.87 +
1.88 + /** edit flags for this editor. May be set at any time. */
1.89 + attribute unsigned long flags;
1.90 +
1.91 + /**
1.92 + * the MimeType of the document
1.93 + */
1.94 + attribute string contentsMIMEType;
1.95 +
1.96 + /** Returns true if we have a document that is not marked read-only */
1.97 + readonly attribute boolean isDocumentEditable;
1.98 +
1.99 + /** Returns true if the current selection anchor is editable */
1.100 + readonly attribute boolean isSelectionEditable;
1.101 +
1.102 + /**
1.103 + * the DOM Document this editor is associated with, refcounted.
1.104 + */
1.105 + readonly attribute nsIDOMDocument document;
1.106 +
1.107 + /** the body element, i.e. the root of the editable document.
1.108 + */
1.109 + readonly attribute nsIDOMElement rootElement;
1.110 +
1.111 + /**
1.112 + * the selection controller for the current presentation, refcounted.
1.113 + */
1.114 + readonly attribute nsISelectionController selectionController;
1.115 +
1.116 +
1.117 + /* ------------ Selected content removal -------------- */
1.118 +
1.119 + /**
1.120 + * DeleteSelection removes all nodes in the current selection.
1.121 + * @param aDir if eNext, delete to the right (for example, the DEL key)
1.122 + * if ePrevious, delete to the left (for example, the BACKSPACE key)
1.123 + * @param stripWrappers If eStrip, strip any empty inline elements left
1.124 + * behind after the deletion; if eNoStrip, don't. If in
1.125 + * doubt, pass eStrip -- eNoStrip is only for if you're
1.126 + * about to insert text or similar right after.
1.127 + */
1.128 + void deleteSelection(in short action, in short stripWrappers);
1.129 +
1.130 +
1.131 + /* ------------ Document info and file methods -------------- */
1.132 +
1.133 + /** Returns true if the document has no *meaningful* content */
1.134 + readonly attribute boolean documentIsEmpty;
1.135 +
1.136 + /** Returns true if the document is modifed and needs saving */
1.137 + readonly attribute boolean documentModified;
1.138 +
1.139 + /** Sets the current 'Save' document character set */
1.140 + attribute ACString documentCharacterSet;
1.141 +
1.142 + /** to be used ONLY when we need to override the doc's modification
1.143 + * state (such as when it's saved).
1.144 + */
1.145 + void resetModificationCount();
1.146 +
1.147 + /** Gets the modification count of the document we are editing.
1.148 + * @return the modification count of the document being edited.
1.149 + * Zero means unchanged.
1.150 + */
1.151 + long getModificationCount();
1.152 +
1.153 + /** called each time we modify the document.
1.154 + * Increments the modification count of the document.
1.155 + * @param aModCount the number of modifications by which
1.156 + * to increase or decrease the count
1.157 + */
1.158 + void incrementModificationCount(in long aModCount);
1.159 +
1.160 + /* ------------ Transaction methods -------------- */
1.161 +
1.162 + /** transactionManager Get the transaction manager the editor is using.
1.163 + */
1.164 + attribute nsITransactionManager transactionManager;
1.165 +
1.166 + /** doTransaction() fires a transaction.
1.167 + * It is provided here so clients can create their own transactions.
1.168 + * If a transaction manager is present, it is used.
1.169 + * Otherwise, the transaction is just executed directly.
1.170 + *
1.171 + * @param aTxn the transaction to execute
1.172 + */
1.173 + void doTransaction(in nsITransaction txn);
1.174 +
1.175 +
1.176 + /** turn the undo system on or off
1.177 + * @param aEnable if PR_TRUE, the undo system is turned on if available
1.178 + * if PR_FALSE the undo system is turned off if it
1.179 + * was previously on
1.180 + * @return if aEnable is PR_TRUE, returns NS_OK if
1.181 + * the undo system could be initialized properly
1.182 + * if aEnable is PR_FALSE, returns NS_OK.
1.183 + */
1.184 + void enableUndo(in boolean enable);
1.185 +
1.186 + /**
1.187 + * The number of items on the undo stack.
1.188 + */
1.189 + readonly attribute long numberOfUndoItems;
1.190 +
1.191 + /**
1.192 + * The number of items on the redo stack.
1.193 + */
1.194 + readonly attribute long numberOfRedoItems;
1.195 +
1.196 + /** undo reverses the effects of the last Do operation,
1.197 + * if Undo is enabled in the editor.
1.198 + * It is provided here so clients need no knowledge of whether
1.199 + * the editor has a transaction manager or not.
1.200 + * If a transaction manager is present, it is told to undo,
1.201 + * and the result of that undo is returned.
1.202 + * Otherwise, the Undo request is ignored and an
1.203 + * error NS_ERROR_NOT_AVAILABLE is returned.
1.204 + *
1.205 + */
1.206 + void undo(in unsigned long count);
1.207 +
1.208 + /** returns state information about the undo system.
1.209 + * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
1.210 + * @param aCanUndo [OUT] PR_TRUE if at least one transaction is
1.211 + * currently ready to be undone.
1.212 + */
1.213 + void canUndo(out boolean isEnabled, out boolean canUndo);
1.214 +
1.215 + /** redo reverses the effects of the last Undo operation
1.216 + * It is provided here so clients need no knowledge of whether
1.217 + * the editor has a transaction manager or not.
1.218 + * If a transaction manager is present, it is told to redo and the
1.219 + * result of the previously undone transaction is reapplied to the document.
1.220 + * If no transaction is available for Redo, or if the document
1.221 + * has no transaction manager, the Redo request is ignored and an
1.222 + * error NS_ERROR_NOT_AVAILABLE is returned.
1.223 + *
1.224 + */
1.225 + void redo(in unsigned long count);
1.226 +
1.227 + /** returns state information about the redo system.
1.228 + * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
1.229 + * @param aCanRedo [OUT] PR_TRUE if at least one transaction is
1.230 + currently ready to be redone.
1.231 + */
1.232 + void canRedo(out boolean isEnabled, out boolean canRedo);
1.233 +
1.234 + /** beginTransaction is a signal from the caller to the editor that
1.235 + * the caller will execute multiple updates to the content tree
1.236 + * that should be treated as a single logical operation,
1.237 + * in the most efficient way possible.<br>
1.238 + * All transactions executed between a call to beginTransaction and
1.239 + * endTransaction will be undoable as an atomic action.<br>
1.240 + * endTransaction must be called after beginTransaction.<br>
1.241 + * Calls to beginTransaction can be nested, as long as endTransaction
1.242 + * is called once per beginUpdate.
1.243 + */
1.244 + void beginTransaction();
1.245 +
1.246 + /** endTransaction is a signal to the editor that the caller is
1.247 + * finished updating the content model.<br>
1.248 + * beginUpdate must be called before endTransaction is called.<br>
1.249 + * Calls to beginTransaction can be nested, as long as endTransaction
1.250 + * is called once per beginTransaction.
1.251 + */
1.252 + void endTransaction();
1.253 +
1.254 + void beginPlaceHolderTransaction(in nsIAtom name);
1.255 + void endPlaceHolderTransaction();
1.256 + boolean shouldTxnSetSelection();
1.257 +
1.258 + /** Set the flag that prevents insertElementTxn from changing the selection
1.259 + * @param should Set false to suppress changing the selection;
1.260 + * i.e., before using InsertElement() to insert
1.261 + * under <head> element
1.262 + * WARNING: You must be very careful to reset back to PR_TRUE after
1.263 + * setting PR_FALSE, else selection/caret is trashed
1.264 + * for further editing.
1.265 + */
1.266 + void setShouldTxnSetSelection(in boolean should);
1.267 +
1.268 + /* ------------ Inline Spell Checking methods -------------- */
1.269 +
1.270 + /** Returns the inline spell checker associated with this object. The spell
1.271 + * checker is lazily created, so this function may create the object for
1.272 + * you during this call.
1.273 + * @param autoCreate If true, this will create a spell checker object
1.274 + * if one does not exist yet for this editor. If false
1.275 + * and the object has not been created, this function
1.276 + * WILL RETURN NULL.
1.277 + */
1.278 + nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);
1.279 +
1.280 + /** Resyncs spellchecking state (enabled/disabled). This should be called
1.281 + * when anything that affects spellchecking state changes, such as the
1.282 + * spellcheck attribute value.
1.283 + */
1.284 + void syncRealTimeSpell();
1.285 +
1.286 + /** Called when the user manually overrides the spellchecking state for this
1.287 + * editor.
1.288 + * @param enable The new state of spellchecking in this editor, as
1.289 + * requested by the user.
1.290 + */
1.291 + void setSpellcheckUserOverride(in boolean enable);
1.292 +
1.293 + /* ------------ Clipboard methods -------------- */
1.294 +
1.295 + /** cut the currently selected text, putting it into the OS clipboard
1.296 + * What if no text is selected?
1.297 + * What about mixed selections?
1.298 + * What are the clipboard formats?
1.299 + */
1.300 + void cut();
1.301 +
1.302 + /** Can we cut? True if the doc is modifiable, and we have a non-
1.303 + * collapsed selection.
1.304 + */
1.305 + boolean canCut();
1.306 +
1.307 + /** copy the currently selected text, putting it into the OS clipboard
1.308 + * What if no text is selected?
1.309 + * What about mixed selections?
1.310 + * What are the clipboard formats?
1.311 + */
1.312 + void copy();
1.313 +
1.314 + /** Can we copy? True if we have a non-collapsed selection.
1.315 + */
1.316 + boolean canCopy();
1.317 +
1.318 + /** paste the text in the OS clipboard at the cursor position, replacing
1.319 + * the selected text (if any)
1.320 + */
1.321 + void paste(in long aSelectionType);
1.322 +
1.323 + /** Paste the text in |aTransferable| at the cursor position, replacing the
1.324 + * selected text (if any).
1.325 + */
1.326 + void pasteTransferable(in nsITransferable aTransferable);
1.327 +
1.328 + /** Can we paste? True if the doc is modifiable, and we have
1.329 + * pasteable data in the clipboard.
1.330 + */
1.331 + boolean canPaste(in long aSelectionType);
1.332 +
1.333 + /** Can we paste |aTransferable| or, if |aTransferable| is null, will a call
1.334 + * to pasteTransferable later possibly succeed if given an instance of
1.335 + * nsITransferable then? True if the doc is modifiable, and, if
1.336 + * |aTransfeable| is non-null, we have pasteable data in |aTransfeable|.
1.337 + */
1.338 + boolean canPasteTransferable([optional] in nsITransferable aTransferable);
1.339 +
1.340 + /* ------------ Selection methods -------------- */
1.341 +
1.342 + /** sets the document selection to the entire contents of the document */
1.343 + void selectAll();
1.344 +
1.345 + /** sets the document selection to the beginning of the document */
1.346 + void beginningOfDocument();
1.347 +
1.348 + /** sets the document selection to the end of the document */
1.349 + void endOfDocument();
1.350 +
1.351 + /* ------------ Node manipulation methods -------------- */
1.352 +
1.353 + /**
1.354 + * setAttribute() sets the attribute of aElement.
1.355 + * No checking is done to see if aAttribute is a legal attribute of the node,
1.356 + * or if aValue is a legal value of aAttribute.
1.357 + *
1.358 + * @param aElement the content element to operate on
1.359 + * @param aAttribute the string representation of the attribute to set
1.360 + * @param aValue the value to set aAttribute to
1.361 + */
1.362 + void setAttribute(in nsIDOMElement aElement, in AString attributestr,
1.363 + in AString attvalue);
1.364 +
1.365 + /**
1.366 + * getAttributeValue() retrieves the attribute's value for aElement.
1.367 + *
1.368 + * @param aElement the content element to operate on
1.369 + * @param aAttribute the string representation of the attribute to get
1.370 + * @param aResultValue [OUT] the value of aAttribute.
1.371 + * Only valid if aResultIsSet is PR_TRUE
1.372 + * @return PR_TRUE if aAttribute is set on the current node,
1.373 + * PR_FALSE if it is not.
1.374 + */
1.375 + boolean getAttributeValue(in nsIDOMElement aElement,
1.376 + in AString attributestr,
1.377 + out AString resultValue);
1.378 +
1.379 + /**
1.380 + * removeAttribute() deletes aAttribute from the attribute list of aElement.
1.381 + * If aAttribute is not an attribute of aElement, nothing is done.
1.382 + *
1.383 + * @param aElement the content element to operate on
1.384 + * @param aAttribute the string representation of the attribute to get
1.385 + */
1.386 + void removeAttribute(in nsIDOMElement aElement,
1.387 + in AString aAttribute);
1.388 +
1.389 + /**
1.390 + * cloneAttribute() copies the attribute from the source node to
1.391 + * the destination node and delete those not in the source.
1.392 + *
1.393 + * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
1.394 + * @param aAttribute the name of the attribute to copy
1.395 + * @param aDestNode the destination element to operate on
1.396 + * @param aSourceNode the source element to copy attributes from
1.397 + * @exception NS_ERROR_NULL_POINTER at least one of the nodes is null
1.398 + * @exception NS_ERROR_NO_INTERFACE at least one of the nodes is not an
1.399 + * element
1.400 + */
1.401 + void cloneAttribute(in AString aAttribute,
1.402 + in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode);
1.403 +
1.404 + /**
1.405 + * cloneAttributes() is similar to nsIDOMNode::cloneNode(),
1.406 + * it assures the attribute nodes of the destination are identical
1.407 + * with the source node by copying all existing attributes from the
1.408 + * source and deleting those not in the source.
1.409 + * This is used when the destination node (element) already exists
1.410 + *
1.411 + * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
1.412 + * @param aDestNode the destination element to operate on
1.413 + * @param aSourceNode the source element to copy attributes from
1.414 + */
1.415 + void cloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode);
1.416 +
1.417 + /**
1.418 + * createNode instantiates a new element of type aTag and inserts it
1.419 + * into aParent at aPosition.
1.420 + * @param aTag The type of object to create
1.421 + * @param aParent The node to insert the new object into
1.422 + * @param aPosition The place in aParent to insert the new node
1.423 + * @return The node created. Caller must release aNewNode.
1.424 + */
1.425 + nsIDOMNode createNode(in AString tag,
1.426 + in nsIDOMNode parent,
1.427 + in long position);
1.428 +
1.429 + /**
1.430 + * insertNode inserts aNode into aParent at aPosition.
1.431 + * No checking is done to verify the legality of the insertion.
1.432 + * That is the responsibility of the caller.
1.433 + * @param aNode The DOM Node to insert.
1.434 + * @param aParent The node to insert the new object into
1.435 + * @param aPosition The place in aParent to insert the new node
1.436 + * 0=first child, 1=second child, etc.
1.437 + * any number > number of current children = last child
1.438 + */
1.439 + void insertNode(in nsIDOMNode node,
1.440 + in nsIDOMNode parent,
1.441 + in long aPosition);
1.442 +
1.443 +
1.444 + /**
1.445 + * splitNode() creates a new node identical to an existing node,
1.446 + * and split the contents between the two nodes
1.447 + * @param aExistingRightNode the node to split.
1.448 + * It will become the new node's next sibling.
1.449 + * @param aOffset the offset of aExistingRightNode's
1.450 + * content|children to do the split at
1.451 + * @param aNewLeftNode [OUT] the new node resulting from the split,
1.452 + * becomes aExistingRightNode's previous sibling.
1.453 + */
1.454 + void splitNode(in nsIDOMNode existingRightNode,
1.455 + in long offset,
1.456 + out nsIDOMNode newLeftNode);
1.457 +
1.458 + /**
1.459 + * joinNodes() takes 2 nodes and merge their content|children.
1.460 + * @param aLeftNode The left node. It will be deleted.
1.461 + * @param aRightNode The right node. It will remain after the join.
1.462 + * @param aParent The parent of aExistingRightNode
1.463 + *
1.464 + * There is no requirement that the two nodes be
1.465 + * of the same type. However, a text node can be
1.466 + * merged only with another text node.
1.467 + */
1.468 + void joinNodes(in nsIDOMNode leftNode,
1.469 + in nsIDOMNode rightNode,
1.470 + in nsIDOMNode parent);
1.471 +
1.472 + /**
1.473 + * deleteNode removes aChild from aParent.
1.474 + * @param aChild The node to delete
1.475 + */
1.476 + void deleteNode(in nsIDOMNode child);
1.477 +
1.478 + /**
1.479 + * Returns true if markNodeDirty() has any effect. Returns false if
1.480 + * markNodeDirty() is a no-op.
1.481 + */
1.482 + [notxpcom] boolean outputsMozDirty();
1.483 +
1.484 + /**
1.485 + * markNodeDirty() sets a special dirty attribute on the node.
1.486 + * Usually this will be called immediately after creating a new node.
1.487 + * @param aNode The node for which to insert formatting.
1.488 + */
1.489 + void markNodeDirty(in nsIDOMNode node);
1.490 +
1.491 +/* ---------- direction controller ---------- */
1.492 +
1.493 + /**
1.494 + * Switches the editor element direction; from "Left-to-Right" to
1.495 + * "Right-to-Left", and vice versa.
1.496 + */
1.497 + void switchTextDirection();
1.498 +
1.499 +/* ------------ Output methods -------------- */
1.500 +
1.501 + /**
1.502 + * Output methods:
1.503 + * aFormatType is a mime type, like text/plain.
1.504 + */
1.505 + AString outputToString(in AString formatType,
1.506 + in unsigned long flags);
1.507 + void outputToStream(in nsIOutputStream aStream,
1.508 + in AString formatType,
1.509 + in ACString charsetOverride,
1.510 + in unsigned long flags);
1.511 +
1.512 +
1.513 + /* ------------ Various listeners methods --------------
1.514 + * nsIEditor holds strong references to the editor observers, action listeners
1.515 + * and document state listeners.
1.516 + */
1.517 +
1.518 + /** add an EditorObserver to the editors list of observers. */
1.519 + void addEditorObserver(in nsIEditorObserver observer);
1.520 +
1.521 + /** Remove an EditorObserver from the editor's list of observers. */
1.522 + void removeEditorObserver(in nsIEditorObserver observer);
1.523 +
1.524 + /** add an EditActionListener to the editors list of listeners. */
1.525 + void addEditActionListener(in nsIEditActionListener listener);
1.526 +
1.527 + /** Remove an EditActionListener from the editor's list of listeners. */
1.528 + void removeEditActionListener(in nsIEditActionListener listener);
1.529 +
1.530 + /** Add a DocumentStateListener to the editors list of doc state listeners. */
1.531 + void addDocumentStateListener(in nsIDocumentStateListener listener);
1.532 +
1.533 + /** Remove a DocumentStateListener to the editors list of doc state listeners. */
1.534 + void removeDocumentStateListener(in nsIDocumentStateListener listener);
1.535 +
1.536 +
1.537 + /* ------------ Debug methods -------------- */
1.538 +
1.539 + /**
1.540 + * And a debug method -- show us what the tree looks like right now
1.541 + */
1.542 + void dumpContentTree();
1.543 +
1.544 + /** Dumps a text representation of the content tree to standard out */
1.545 + void debugDumpContent() ;
1.546 +
1.547 + /* Run unit tests. Noop in optimized builds */
1.548 + void debugUnitTests(out long outNumTests, out long outNumTestsFailed);
1.549 +
1.550 + /* checks if a node is read-only or not */
1.551 + [notxpcom] boolean isModifiableNode(in nsIDOMNode aNode);
1.552 +
1.553 + /* Set true if you want to suppress dispatching input event. */
1.554 + attribute boolean suppressDispatchingInputEvent;
1.555 +};
