mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-01 06:35:42 +00:00
552 lines
21 KiB
Plaintext
552 lines
21 KiB
Plaintext
/* -*- 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(753b38d1-ee03-4e58-a650-1076ccccdb7f)]
|
|
|
|
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;
|
|
|
|
/**
|
|
* 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)
|
|
* @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();
|
|
|
|
/** 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;
|
|
};
|