summaryrefslogtreecommitdiffstats
path: root/editor/nsIEditor.idl
diff options
context:
space:
mode:
Diffstat (limited to 'editor/nsIEditor.idl')
-rw-r--r--editor/nsIEditor.idl567
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;
+};