/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * The contents of this file are subject to the Netscape Public License * Version 1.0 (the "NPL"); you may not use this file except in * compliance with the NPL. You may obtain a copy of the NPL at * http://www.mozilla.org/NPL/ * * Software distributed under the NPL is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL * for the specific language governing rights and limitations under the * NPL. * * The Initial Developer of this code under the NPL is Netscape * Communications Corporation. Portions created by Netscape are * Copyright (C) 1998 Netscape Communications Corporation. All Rights * Reserved. */ #ifndef nsIEditor_h__ #define nsIEditor_h__ #include "nsISupports.h" #include "nscore.h" class nsIAtom; class nsIDOMElement; class nsIDOMNode; class nsITransaction; class nsIEditActionListener; class nsIFileSpec; class nsIDOMTextRangeList; class nsICSSStyleSheet; /* Editor interface to outside world */ #define NS_IEDITOR_IID \ {/* A3C5EE71-742E-11d2-8F2C-006008310194*/ \ 0xa3c5ee71, 0x742e, 0x11d2, \ {0x8f, 0x2c, 0x0, 0x60, 0x8, 0x31, 0x1, 0x94} } #define NS_IEDITORFACTORY_IID \ { /* {E2F4C7F1-864A-11d2-8F38-006008310194}*/ \ 0xe2f4c7f1, 0x864a, 0x11d2, \ { 0x8f, 0x38, 0x0, 0x60, 0x8, 0x31, 0x1, 0x94 } } #define NS_ITEXTEDITORFACTORY_IID \ { /* {4a1f5ce0-c1f9-11d2-8f4c-006008159b0c}*/ \ 0x4a1f5ce0, 0xc1f9, 0x11d2, \ { 0x8f, 0x4c, 0x0, 0x60, 0x8, 0x15, 0x9b, 0xc } } #define NS_IHTMLEDITORFACTORY_IID \ { /* BD62F312-CB8A-11d2-983A-00805F8AA8B8 */ \ 0xbd62f312, 0xcb8a, 0x11d2, \ { 0x98, 0x3a, 0x0, 0x80, 0x5f, 0x8a, 0xa8, 0xb8 } } class nsIDOMDocument; class nsIDOMSelection; class nsIPresShell; class nsString; /** * A generic editor interface. *

* nsIEditor is the base interface used by applications to communicate with the editor. * It makes no assumptions about the kind of content it is editing, * other than the content being a DOM tree. */ class nsIEditor : public nsISupports{ public: typedef enum { eDoNothing, eDeleteRight, eDeleteLeft } ECollapsedSelectionAction; static nsString& GetTextNodeTag(); static const nsIID& GetIID() { static nsIID iid = NS_IEDITOR_IID; return iid; } /** * Init tells is to tell the implementation of nsIEditor to begin its services * @param aDoc The dom document interface being observed * @param aPresShell TEMP: The presentation shell displaying the document * once events can tell us from what pres shell they originated, * this will no longer be necessary and the editor will no longer be * linked to a single pres shell. */ NS_IMETHOD Init(nsIDOMDocument *aDoc, nsIPresShell *aPresShell )=0; /** * return the DOM Document this editor is associated with * * @param aDoc [OUT] the dom interface being observed, refcounted */ NS_IMETHOD GetDocument(nsIDOMDocument **aDoc)=0; /** * return the presentation shell this editor is associated with * * @param aPS [OUT] the pres shell, refcounted */ NS_IMETHOD GetPresShell(nsIPresShell **aPS)=0; /** * return the DOM Selection for the presentation shell that has focus * (or most recently had focus.) * @param aSelection [OUT] the dom interface for the selection */ NS_IMETHOD GetSelection(nsIDOMSelection **aSelection)=0; /** * 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 */ NS_IMETHOD SetAttribute(nsIDOMElement * aElement, const nsString& aAttribute, const nsString& aValue)=0; /** * 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 the value of aAttribute. only valid if aResultIsSet is PR_TRUE * @param aResultIsSet PR_TRUE if aAttribute is set on the current node, PR_FALSE if it is not. */ NS_IMETHOD GetAttributeValue(nsIDOMElement * aElement, const nsString& aAttribute, nsString& aResultValue, PRBool& aResultIsSet)=0; /** * 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 */ NS_IMETHOD RemoveAttribute(nsIDOMElement * aElement, const nsString& aAttribute)=0; /** * 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 * @param aNewNode [OUT] The node created. Caller must release aNewNode. */ NS_IMETHOD CreateNode(const nsString& aTag, nsIDOMNode * aParent, PRInt32 aPosition, nsIDOMNode ** aNewNode)=0; /** * 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 */ NS_IMETHOD InsertNode(nsIDOMNode * aNode, nsIDOMNode * aParent, PRInt32 aPosition)=0; /** * InsertText() Inserts a string at the current location, given by the selection. * If the selection is not collapsed, the selection is deleted and the insertion * takes place at the resulting collapsed selection. * * NOTE: what happens if the string contains a CR? * * @param aString the string to be inserted */ NS_IMETHOD InsertText(const nsString& aStringToInsert)=0; /** * BeginComposition() Handles the start of inline input composition. */ NS_IMETHOD BeginComposition(void) = 0; /** * SetCompositionString() Sets the inline input composition string. * BeginComposition must be called prior to this. */ NS_IMETHOD SetCompositionString(const nsString& aCompositionString, nsIDOMTextRangeList* aTextRangeList) = 0; /** * BeginComposition() Handles the end of inline input composition. */ NS_IMETHOD EndComposition(void) = 0; /** * DeleteNode removes aChild from aParent. * @param aChild The node to delete */ NS_IMETHOD DeleteNode(nsIDOMNode * aChild)=0; /** * DeleteSelection removes all nodes in the current selection. * @param aAction: direction to delete if selection is collapsed: * if eDeleteRight, delete to the right (for example, the DEL key) * if DeleteLeft, delete to the left (for example, the BACKSPACE key) */ NS_IMETHOD DeleteSelection(nsIEditor::ECollapsedSelectionAction aAction)=0; /** * DeleteSelectionAndCreateNode combines DeleteSelection and CreateNode * It deletes only if there is something selected (doesn't do DEL, BACKSPACE action) * @param aTag The type of object to create * @param aNewNode [OUT] The node created. Caller must release aNewNode. */ NS_IMETHOD DeleteSelectionAndCreateNode(const nsString& aTag, nsIDOMNode ** aNewNode)=0; /** * 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. */ NS_IMETHOD SplitNode(nsIDOMNode *aExistingRightNode, PRInt32 aOffset, nsIDOMNode **aNewLeftNode)=0; /** * JoinNodes() takes 2 nodes and merge their content|children. * @param aNodeToKeep The left node. It will remain after the join. * @param aNodeToJoin The right node. * There is no requirement that the two nodes be of the same type. * @param aParent The parent of aExistingRightNode * @param aNodeToKeepIsFirst if PR_TRUE, the contents|children of aNodeToKeep come before the * contents|children of aNodeToJoin, otherwise their positions are switched. */ NS_IMETHOD JoinNodes(nsIDOMNode *aLeftNode, nsIDOMNode *aRightNode, nsIDOMNode *aParent)=0; /** * Insert a break into the content model.
* The interpretation of a break is up to the rule system: * it may enter a character, split a node in the tree, etc. */ NS_IMETHOD InsertBreak()=0; /** turn the undo system on or off * @param aEnable if PR_TRUE, the undo system is turned on if it is 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. */ NS_IMETHOD EnableUndo(PRBool aEnable)=0; /** Do() 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 */ NS_IMETHOD Do(nsITransaction *aTxn)=0; /** 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. * */ NS_IMETHOD Undo(PRUint32 aCount)=0; /** 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. */ NS_IMETHOD CanUndo(PRBool &aIsEnabled, PRBool &aCanUndo)=0; /** 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. * */ NS_IMETHOD Redo(PRUint32 aCount)=0; /** 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. */ NS_IMETHOD CanRedo(PRBool &aIsEnabled, PRBool &aCanRedo)=0; /** 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. */ NS_IMETHOD BeginTransaction()=0; /** 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. */ NS_IMETHOD EndTransaction()=0; /** Get the layout's frame object associated with the node * Needed when we must get geometric layout info, such as what column a table cell is in. * @param aNode The DOM node we need the frame for * @param aLayoutObject The pointer where the resulting object is placed */ NS_IMETHOD GetLayoutObject(nsIDOMNode *aNode, nsISupports **aLayoutObject)=0; /** scroll the viewport so the selection is in view. * @param aScrollToBegin PR_TRUE if the beginning of the selection is to be scrolled into view. * PR_FALSE if the end of the selection is to be scrolled into view */ NS_IMETHOD ScrollIntoView(PRBool aScrollToBegin)=0; /** sets the document selection to the entire contents of the document */ NS_IMETHOD SelectAll()=0; /** sets the document selection to the beginning of the document */ NS_IMETHOD BeginningOfDocument()=0; /** sets the document selection to the end of the document */ NS_IMETHOD EndOfDocument()=0; /** 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? */ NS_IMETHOD Cut()=0; /** 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? */ NS_IMETHOD Copy()=0; /** paste the text in the OS clipboard at the cursor position, replacing * the selected text (if any) */ NS_IMETHOD Paste()=0; /** paste the text in the OS clipboard at the cursor position, * replacing the selected text (if any). * Method of quotation will depend on what type of editor we are, * and also on preference settings. * @param aCitation The "mid" URL of the source message */ NS_IMETHOD PasteAsQuotation()=0; /** insert a string as quoted text, * replacing the selected text (if any). * Method of quotation will depend on what type of editor we are, * and also on preference settings. * @param aQuotedText The actual text to be quoted * @param aCitation The "mid" URL of the source message */ NS_IMETHOD InsertAsQuotation(const nsString& aQuotedText)=0; /** load and apply the style sheet, specified by aURL, to * the editor's document. This can involve asynchronous * network I/O * @param aURL The style sheet to be loaded and applied. */ NS_IMETHOD ApplyStyleSheet(const nsString& aURL)=0; /** Add the given Style Sheet to the editor's document * This is always synchronous * @param aSheet The style sheet to be applied. */ NS_IMETHOD AddStyleSheet(nsICSSStyleSheet* aSheet)=0; /** Remove the given Style Sheet from the editor's document * This is always synchronous * @param aSheet The style sheet to be applied. */ NS_IMETHOD RemoveStyleSheet(nsICSSStyleSheet* aSheet)=0; /** add an EditActionListener to the editors list of listeners. */ NS_IMETHOD AddEditActionListener(nsIEditActionListener *aListener)=0; /** Remove an EditActionListener from the editor's list of listeners. */ NS_IMETHOD RemoveEditActionListener(nsIEditActionListener *aListener)=0; /** Dumps a text representation of the content tree to standard out */ NS_IMETHOD DebugDumpContent() const =0; /* Run unit tests. Noop in optimized builds */ NS_IMETHOD DebugUnitTests(PRInt32 *outNumTests, PRInt32 *outNumTestsFailed)=0; /* Start logging */ NS_IMETHOD StartLogging(nsIFileSpec *aLogFile)=0; /* Stop logging */ NS_IMETHOD StopLogging()=0; }; #endif //nsIEditor_h__