diff options
Diffstat (limited to 'editor/nsIEditor.idl')
| -rw-r--r-- | editor/nsIEditor.idl | 567 |
1 files changed, 567 insertions, 0 deletions
diff --git a/editor/nsIEditor.idl b/editor/nsIEditor.idl new file mode 100644 index 000000000..bb9026d0e --- /dev/null +++ b/editor/nsIEditor.idl @@ -0,0 +1,567 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" +#include "domstubs.idl" + +interface nsIURI; +interface nsIAtom; +interface nsIContent; +interface nsISelection; +interface nsISelectionController; +interface nsIDocumentStateListener; +interface nsIOutputStream; +interface nsITransactionManager; +interface nsITransaction; +interface nsIEditorObserver; +interface nsIEditActionListener; +interface nsIInlineSpellChecker; +interface nsITransferable; + +[scriptable, uuid(094be624-f0bf-400f-89e2-6a84baab9474)] +interface nsIEditor : nsISupports +{ +%{C++ + typedef short EDirection; + typedef short EStripWrappers; +%} + const short eNone = 0; + const short eNext = 1; + const short ePrevious = 2; + const short eNextWord = 3; + const short ePreviousWord = 4; + const short eToBeginningOfLine = 5; + const short eToEndOfLine = 6; + + const short eStrip = 0; + const short eNoStrip = 1; + + readonly attribute nsISelection selection; + + /** + * Finalizes selection and caret for the editor. + */ + [noscript] void finalizeSelection(); + + /** + * Init is to tell the implementation of nsIEditor to begin its services + * @param aDoc The dom document interface being observed + * @param aRoot This is the root of the editable section of this + * document. If it is null then we get root + * from document body. + * @param aSelCon this should be used to get the selection location + * (will be null for HTML editors) + * @param aFlags A bitmask of flags for specifying the behavior + * of the editor. + */ + [noscript] void init(in nsIDOMDocument doc, + in nsIContent aRoot, + in nsISelectionController aSelCon, + in unsigned long aFlags, + in AString initialValue); + + void setAttributeOrEquivalent(in nsIDOMElement element, + in AString sourceAttrName, + in AString sourceAttrValue, + in boolean aSuppressTransaction); + void removeAttributeOrEquivalent(in nsIDOMElement element, + in DOMString sourceAttrName, + in boolean aSuppressTransaction); + + /** + * postCreate should be called after Init, and is the time that the editor + * tells its documentStateObservers that the document has been created. + */ + void postCreate(); + + /** + * preDestroy is called before the editor goes away, and gives the editor a + * chance to tell its documentStateObservers that the document is going away. + * @param aDestroyingFrames set to true when the frames being edited + * are being destroyed (so there is no need to modify any nsISelections, + * nor is it safe to do so) + */ + void preDestroy(in boolean aDestroyingFrames); + + /** edit flags for this editor. May be set at any time. */ + attribute unsigned long flags; + + /** + * the MimeType of the document + */ + attribute string contentsMIMEType; + + /** Returns true if we have a document that is not marked read-only */ + readonly attribute boolean isDocumentEditable; + + /** Returns true if the current selection anchor is editable */ + readonly attribute boolean isSelectionEditable; + + /** + * the DOM Document this editor is associated with, refcounted. + */ + readonly attribute nsIDOMDocument document; + + /** the body element, i.e. the root of the editable document. + */ + readonly attribute nsIDOMElement rootElement; + + /** + * the selection controller for the current presentation, refcounted. + */ + readonly attribute nsISelectionController selectionController; + + + /* ------------ Selected content removal -------------- */ + + /** + * DeleteSelection removes all nodes in the current selection. + * @param aDir if eNext, delete to the right (for example, the DEL key) + * if ePrevious, delete to the left (for example, the BACKSPACE key) + * @param stripWrappers If eStrip, strip any empty inline elements left + * behind after the deletion; if eNoStrip, don't. If in + * doubt, pass eStrip -- eNoStrip is only for if you're + * about to insert text or similar right after. + */ + void deleteSelection(in short action, in short stripWrappers); + + + /* ------------ Document info and file methods -------------- */ + + /** Returns true if the document has no *meaningful* content */ + readonly attribute boolean documentIsEmpty; + + /** Returns true if the document is modifed and needs saving */ + readonly attribute boolean documentModified; + + /** Sets the current 'Save' document character set */ + attribute ACString documentCharacterSet; + + /** to be used ONLY when we need to override the doc's modification + * state (such as when it's saved). + */ + void resetModificationCount(); + + /** Gets the modification count of the document we are editing. + * @return the modification count of the document being edited. + * Zero means unchanged. + */ + long getModificationCount(); + + /** called each time we modify the document. + * Increments the modification count of the document. + * @param aModCount the number of modifications by which + * to increase or decrease the count + */ + void incrementModificationCount(in long aModCount); + + /* ------------ Transaction methods -------------- */ + + /** transactionManager Get the transaction manager the editor is using. + */ + attribute nsITransactionManager transactionManager; + + /** doTransaction() fires a transaction. + * It is provided here so clients can create their own transactions. + * If a transaction manager is present, it is used. + * Otherwise, the transaction is just executed directly. + * + * @param aTxn the transaction to execute + */ + void doTransaction(in nsITransaction txn); + + + /** turn the undo system on or off + * @param aEnable if PR_TRUE, the undo system is turned on if available + * if PR_FALSE the undo system is turned off if it + * was previously on + * @return if aEnable is PR_TRUE, returns NS_OK if + * the undo system could be initialized properly + * if aEnable is PR_FALSE, returns NS_OK. + */ + void enableUndo(in boolean enable); + + /** + * The number of items on the undo stack. + */ + readonly attribute long numberOfUndoItems; + + /** + * The number of items on the redo stack. + */ + readonly attribute long numberOfRedoItems; + + /** undo reverses the effects of the last Do operation, + * if Undo is enabled in the editor. + * It is provided here so clients need no knowledge of whether + * the editor has a transaction manager or not. + * If a transaction manager is present, it is told to undo, + * and the result of that undo is returned. + * Otherwise, the Undo request is ignored and an + * error NS_ERROR_NOT_AVAILABLE is returned. + * + */ + void undo(in unsigned long count); + + /** returns state information about the undo system. + * @param aIsEnabled [OUT] PR_TRUE if undo is enabled + * @param aCanUndo [OUT] PR_TRUE if at least one transaction is + * currently ready to be undone. + */ + void canUndo(out boolean isEnabled, out boolean canUndo); + + /** redo reverses the effects of the last Undo operation + * It is provided here so clients need no knowledge of whether + * the editor has a transaction manager or not. + * If a transaction manager is present, it is told to redo and the + * result of the previously undone transaction is reapplied to the document. + * If no transaction is available for Redo, or if the document + * has no transaction manager, the Redo request is ignored and an + * error NS_ERROR_NOT_AVAILABLE is returned. + * + */ + void redo(in unsigned long count); + + /** returns state information about the redo system. + * @param aIsEnabled [OUT] PR_TRUE if redo is enabled + * @param aCanRedo [OUT] PR_TRUE if at least one transaction is + currently ready to be redone. + */ + void canRedo(out boolean isEnabled, out boolean canRedo); + + /** beginTransaction is a signal from the caller to the editor that + * the caller will execute multiple updates to the content tree + * that should be treated as a single logical operation, + * in the most efficient way possible.<br> + * All transactions executed between a call to beginTransaction and + * endTransaction will be undoable as an atomic action.<br> + * endTransaction must be called after beginTransaction.<br> + * Calls to beginTransaction can be nested, as long as endTransaction + * is called once per beginUpdate. + */ + void beginTransaction(); + + /** endTransaction is a signal to the editor that the caller is + * finished updating the content model.<br> + * beginUpdate must be called before endTransaction is called.<br> + * Calls to beginTransaction can be nested, as long as endTransaction + * is called once per beginTransaction. + */ + void endTransaction(); + + void beginPlaceHolderTransaction(in nsIAtom name); + void endPlaceHolderTransaction(); + boolean shouldTxnSetSelection(); + + /** Set the flag that prevents insertElementTxn from changing the selection + * @param should Set false to suppress changing the selection; + * i.e., before using InsertElement() to insert + * under <head> element + * WARNING: You must be very careful to reset back to PR_TRUE after + * setting PR_FALSE, else selection/caret is trashed + * for further editing. + */ + void setShouldTxnSetSelection(in boolean should); + + /* ------------ Inline Spell Checking methods -------------- */ + + /** Returns the inline spell checker associated with this object. The spell + * checker is lazily created, so this function may create the object for + * you during this call. + * @param autoCreate If true, this will create a spell checker object + * if one does not exist yet for this editor. If false + * and the object has not been created, this function + * WILL RETURN NULL. + */ + nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate); + + /** Resyncs spellchecking state (enabled/disabled). This should be called + * when anything that affects spellchecking state changes, such as the + * spellcheck attribute value. + */ + void syncRealTimeSpell(); + + /** Called when the user manually overrides the spellchecking state for this + * editor. + * @param enable The new state of spellchecking in this editor, as + * requested by the user. + */ + void setSpellcheckUserOverride(in boolean enable); + + /* ------------ Clipboard methods -------------- */ + + /** cut the currently selected text, putting it into the OS clipboard + * What if no text is selected? + * What about mixed selections? + * What are the clipboard formats? + */ + void cut(); + + /** Can we cut? True if the doc is modifiable, and we have a non- + * collapsed selection. + */ + boolean canCut(); + + /** copy the currently selected text, putting it into the OS clipboard + * What if no text is selected? + * What about mixed selections? + * What are the clipboard formats? + */ + void copy(); + + /** Can we copy? True if we have a non-collapsed selection. + */ + boolean canCopy(); + + /** Can we delete? True if we have a non-collapsed selection. + */ + boolean canDelete(); + + /** paste the text in the OS clipboard at the cursor position, replacing + * the selected text (if any) + */ + void paste(in long aSelectionType); + + /** Paste the text in |aTransferable| at the cursor position, replacing the + * selected text (if any). + */ + void pasteTransferable(in nsITransferable aTransferable); + + /** Can we paste? True if the doc is modifiable, and we have + * pasteable data in the clipboard. + */ + boolean canPaste(in long aSelectionType); + + /** Can we paste |aTransferable| or, if |aTransferable| is null, will a call + * to pasteTransferable later possibly succeed if given an instance of + * nsITransferable then? True if the doc is modifiable, and, if + * |aTransfeable| is non-null, we have pasteable data in |aTransfeable|. + */ + boolean canPasteTransferable([optional] in nsITransferable aTransferable); + + /* ------------ Selection methods -------------- */ + + /** sets the document selection to the entire contents of the document */ + void selectAll(); + + /** sets the document selection to the beginning of the document */ + void beginningOfDocument(); + + /** sets the document selection to the end of the document */ + void endOfDocument(); + + /* ------------ Node manipulation methods -------------- */ + + /** + * setAttribute() sets the attribute of aElement. + * No checking is done to see if aAttribute is a legal attribute of the node, + * or if aValue is a legal value of aAttribute. + * + * @param aElement the content element to operate on + * @param aAttribute the string representation of the attribute to set + * @param aValue the value to set aAttribute to + */ + void setAttribute(in nsIDOMElement aElement, in AString attributestr, + in AString attvalue); + + /** + * getAttributeValue() retrieves the attribute's value for aElement. + * + * @param aElement the content element to operate on + * @param aAttribute the string representation of the attribute to get + * @param aResultValue [OUT] the value of aAttribute. + * Only valid if aResultIsSet is PR_TRUE + * @return PR_TRUE if aAttribute is set on the current node, + * PR_FALSE if it is not. + */ + boolean getAttributeValue(in nsIDOMElement aElement, + in AString attributestr, + out AString resultValue); + + /** + * removeAttribute() deletes aAttribute from the attribute list of aElement. + * If aAttribute is not an attribute of aElement, nothing is done. + * + * @param aElement the content element to operate on + * @param aAttribute the string representation of the attribute to get + */ + void removeAttribute(in nsIDOMElement aElement, + in AString aAttribute); + + /** + * cloneAttribute() copies the attribute from the source node to + * the destination node and delete those not in the source. + * + * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes) + * @param aAttribute the name of the attribute to copy + * @param aDestNode the destination element to operate on + * @param aSourceNode the source element to copy attributes from + * @exception NS_ERROR_NULL_POINTER at least one of the nodes is null + * @exception NS_ERROR_NO_INTERFACE at least one of the nodes is not an + * element + */ + void cloneAttribute(in AString aAttribute, + in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode); + + /** + * cloneAttributes() is similar to nsIDOMNode::cloneNode(), + * it assures the attribute nodes of the destination are identical + * with the source node by copying all existing attributes from the + * source and deleting those not in the source. + * This is used when the destination node (element) already exists + * + * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes) + * @param aDestNode the destination element to operate on + * @param aSourceNode the source element to copy attributes from + */ + void cloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode); + + /** + * createNode instantiates a new element of type aTag and inserts it + * into aParent at aPosition. + * @param aTag The type of object to create + * @param aParent The node to insert the new object into + * @param aPosition The place in aParent to insert the new node + * @return The node created. Caller must release aNewNode. + */ + nsIDOMNode createNode(in AString tag, + in nsIDOMNode parent, + in long position); + + /** + * insertNode inserts aNode into aParent at aPosition. + * No checking is done to verify the legality of the insertion. + * That is the responsibility of the caller. + * @param aNode The DOM Node to insert. + * @param aParent The node to insert the new object into + * @param aPosition The place in aParent to insert the new node + * 0=first child, 1=second child, etc. + * any number > number of current children = last child + */ + void insertNode(in nsIDOMNode node, + in nsIDOMNode parent, + in long aPosition); + + + /** + * splitNode() creates a new node identical to an existing node, + * and split the contents between the two nodes + * @param aExistingRightNode the node to split. + * It will become the new node's next sibling. + * @param aOffset the offset of aExistingRightNode's + * content|children to do the split at + * @param aNewLeftNode [OUT] the new node resulting from the split, + * becomes aExistingRightNode's previous sibling. + */ + void splitNode(in nsIDOMNode existingRightNode, + in long offset, + out nsIDOMNode newLeftNode); + + /** + * joinNodes() takes 2 nodes and merge their content|children. + * @param aLeftNode The left node. It will be deleted. + * @param aRightNode The right node. It will remain after the join. + * @param aParent The parent of aExistingRightNode + * + * There is no requirement that the two nodes be + * of the same type. However, a text node can be + * merged only with another text node. + */ + void joinNodes(in nsIDOMNode leftNode, + in nsIDOMNode rightNode, + in nsIDOMNode parent); + + /** + * deleteNode removes aChild from aParent. + * @param aChild The node to delete + */ + void deleteNode(in nsIDOMNode child); + + /** + * Returns true if markNodeDirty() has any effect. Returns false if + * markNodeDirty() is a no-op. + */ + [notxpcom] boolean outputsMozDirty(); + + /** + * markNodeDirty() sets a special dirty attribute on the node. + * Usually this will be called immediately after creating a new node. + * @param aNode The node for which to insert formatting. + */ + void markNodeDirty(in nsIDOMNode node); + +/* ---------- direction controller ---------- */ + + /** + * Switches the editor element direction; from "Left-to-Right" to + * "Right-to-Left", and vice versa. + */ + void switchTextDirection(); + +/* ------------ Output methods -------------- */ + + /** + * Output methods: + * aFormatType is a mime type, like text/plain. + */ + AString outputToString(in AString formatType, + in unsigned long flags); + void outputToStream(in nsIOutputStream aStream, + in AString formatType, + in ACString charsetOverride, + in unsigned long flags); + + + /* ------------ Various listeners methods -------------- + * nsIEditor holds strong references to the editor observers, action listeners + * and document state listeners. + */ + + /** add an EditorObserver to the editors list of observers. */ + void addEditorObserver(in nsIEditorObserver observer); + + /** Remove an EditorObserver from the editor's list of observers. */ + void removeEditorObserver(in nsIEditorObserver observer); + + /** add an EditActionListener to the editors list of listeners. */ + void addEditActionListener(in nsIEditActionListener listener); + + /** Remove an EditActionListener from the editor's list of listeners. */ + void removeEditActionListener(in nsIEditActionListener listener); + + /** Add a DocumentStateListener to the editors list of doc state listeners. */ + void addDocumentStateListener(in nsIDocumentStateListener listener); + + /** Remove a DocumentStateListener to the editors list of doc state listeners. */ + void removeDocumentStateListener(in nsIDocumentStateListener listener); + + + /* ------------ Debug methods -------------- */ + + /** + * And a debug method -- show us what the tree looks like right now + */ + void dumpContentTree(); + + /** Dumps a text representation of the content tree to standard out */ + void debugDumpContent() ; + + /* Run unit tests. Noop in optimized builds */ + void debugUnitTests(out long outNumTests, out long outNumTestsFailed); + + /* checks if a node is read-only or not */ + [notxpcom] boolean isModifiableNode(in nsIDOMNode aNode); + + /* Set true if you want to suppress dispatching input event. */ + attribute boolean suppressDispatchingInputEvent; + + /** + * True if an edit action is being handled (in other words, between calls of + * nsIEditorObserver::BeforeEditAction() and nsIEditorObserver::EditAction() + * or nsIEditorObserver::CancelEditAction(). Otherwise, false. + */ + [noscript] readonly attribute boolean isInEditAction; +}; |