/* -*- 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 nsIContent; interface nsISelectionController; interface nsIDocumentStateListener; interface nsIOutputStream; interface nsITransactionManager; interface nsITransaction; interface nsIEditorObserver; interface nsIEditActionListener; interface nsIInlineSpellChecker; interface nsITransferable; webidl Document; webidl Element; webidl Node; webidl Selection; %{C++ namespace mozilla { class EditorBase; class HTMLEditor; class TextEditor; } // namespace mozilla %} [scriptable, builtinclass, 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 Selection selection; [can_run_script] void setAttributeOrEquivalent(in Element element, in AString sourceAttrName, in AString sourceAttrValue, in boolean aSuppressTransaction); [can_run_script] void removeAttributeOrEquivalent(in Element element, in AString sourceAttrName, in boolean aSuppressTransaction); /** 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 Document document; /** the body element, i.e. the root of the editable document. */ readonly attribute Element 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. */ [can_run_script] 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 */ [can_run_script] // setter only attribute ACString documentCharacterSet; /** to be used ONLY when we need to override the doc's modification * state (such as when it's saved). */ [can_run_script] 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 */ [can_run_script] void incrementModificationCount(in long aModCount); /* ------------ Transaction methods -------------- */ /** transactionManager Get the transaction manager the editor is using. */ readonly 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 */ [can_run_script] 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); /** 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. * */ [can_run_script] 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. * */ [can_run_script] 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.
* All transactions executed between a call to beginTransaction and * endTransaction will be undoable as an atomic action.
* endTransaction must be called after beginTransaction.
* 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.
* beginUpdate must be called before endTransaction is called.
* Calls to beginTransaction can be nested, as long as endTransaction * is called once per beginTransaction. */ [can_run_script] void endTransaction(); /** * While setting the flag with this method to false, CreateElementTransaction, * DeleteRangeTransaction, DeleteTextTransaction, InsertNodeTransaction, * InsertTextTransaction and SplitNodeTransaction won't change Selection * after modifying the DOM tree. * Note that calling this with false does not guarantee that Selection won't * be changed because other transaction may ignore this flag, editor itself * may change selection, and current selection may become invalid after * changing the DOM tree, etc. * After calling this method with true, the caller should guarantee that * Selection should be positioned where user expects. * * @param should false if you don't want above transactions to modify * Selection automatically after modifying the DOM tree. * Note that calling this with false does not guarantee * that Selection is never changed. */ 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); /** 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? */ [can_run_script] 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) */ [can_run_script] void paste(in long aClipboardType); /** Paste the text in |aTransferable| at the cursor position, replacing the * selected text (if any). */ [can_run_script] 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 aClipboardType); /* ------------ Selection methods -------------- */ /** sets the document selection to the entire contents of the document */ [can_run_script] void selectAll(); /** * Collapses selection at start of the document. If it's an HTML editor, * collapses selection at start of current editing host ( element if * it's in designMode) instead. If there is a non-editable node before any * editable text nodes or inline elements which can have text nodes as their * children, collapses selection at start of the editing host. If there is * an editable text node which is not collapsed, collapses selection at * start of the text node. If there is an editable inline element which * cannot have text nodes as its child, collapses selection at before the * element node. Otherwise, collapses selection at start of the editing * host. */ 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 */ [can_run_script] void setAttribute(in Element 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 Element 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 */ [can_run_script] void removeAttribute(in Element 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 aDestElement the destination element to operate on * @param aSourceElement the source element to copy attributes from * @exception NS_ERROR_NULL_POINTER at least one of the elements is null */ [can_run_script] void cloneAttribute(in AString aAttribute, in Element aDestElement, in Element aSourceElement); /** * cloneAttributes() is similar to Node::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 element already exists * * @param aDestNode the destination element to operate on * @param aSourceNode the source element to copy attributes from */ [can_run_script] void cloneAttributes(in Element aDestElement, in Element aSourceElement); /** * 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 */ [can_run_script] void insertNode(in Node node, in Node 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. */ [can_run_script] void splitNode(in Node existingRightNode, in long offset, out Node 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. */ [can_run_script] void joinNodes(in Node leftNode, in Node rightNode, in Node parent); /** * deleteNode removes aChild from aParent. * @param aChild The node to delete */ [can_run_script] void deleteNode(in Node child); /** * 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 Node node); /* ------------ Output methods -------------- */ /** * Output methods: * aFormatType is a mime type, like text/plain. */ AString outputToString(in AString formatType, 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); /** * forceCompositionEnd() force the composition end */ void forceCompositionEnd(); /** * whether this editor has active IME transaction */ readonly attribute boolean composing; %{C++ /** * AsEditorBase() returns a pointer to EditorBase class. * * In order to avoid circular dependency issues, this method is defined * in mozilla/EditorBase.h. Consumers need to #include that header. */ inline mozilla::EditorBase* AsEditorBase(); inline const mozilla::EditorBase* AsEditorBase() const; /** * AsTextEditor() returns a pointer to TextEditor class. * * In order to avoid circular dependency issues, this method is defined * in mozilla/TextEditor.h. Consumers need to #include that header. */ inline mozilla::TextEditor* AsTextEditor(); inline const mozilla::TextEditor* AsTextEditor() const; /** * AsHTMLEditor() returns a pointer to HTMLEditor class. * * In order to avoid circular dependency issues, this method is defined * in mozilla/HTMLEditor.h. Consumers need to #include that header. */ inline mozilla::HTMLEditor* AsHTMLEditor(); inline const mozilla::HTMLEditor* AsHTMLEditor() const; %} };