/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the Mozilla browser. * * The Initial Developer of the Original Code is * Netscape Communications, Inc. * Portions created by the Initial Developer are Copyright (C) 1999 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Daniel Glazman * Akkana Peck * * Alternatively, the contents of this file may be used under the terms of * either of the GNU General Public License Version 2 or later (the "GPL"), * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #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(94479B76-7FD7-47D3-BB1E-5B77846339D2)] interface nsIEditor : nsISupports { %{C++ typedef short EDirection; %} 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; readonly attribute nsISelection selection; /** * 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); 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) */ void deleteSelection(in short action); /* ------------ 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); /** 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.
* 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. */ 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 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(); /** 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); /** * 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); /** * Will be set to true if the last keypress event that the editor has handled * has been trusted. The value will only be valid when the edit action listeners * are being called, and will throw upon access at all other times. */ readonly attribute boolean lastKeypressEventTrusted; };