Public Types | Public Member Functions | Public Attributes

nsIEditor Interface Reference

import "nsIEditor.idl";

Collaboration diagram for nsIEditor:

List of all members.

Public Types

typedef short EDirection

Public Member Functions

void init (in nsIDOMDocument doc, in nsIPresShellPtr shell, in nsIContent aRoot, in nsISelectionController aSelCon, in unsigned long aFlags)
 Init is to tell the implementation of nsIEditor to begin its services.
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)
void postCreate ()
 postCreate should be called after Init, and is the time that the editor tells its documentStateObservers that the document has been created.
void preDestroy (in boolean aDestroyingFrames)
 preDestroy is called before the editor goes away, and gives the editor a chance to tell its documentStateObservers that the document is going away.
void deleteSelection (in short action)
 DeleteSelection removes all nodes in the current selection.
void resetModificationCount ()
 to be used ONLY when we need to override the doc's modification state (such as when it's saved).
long getModificationCount ()
 Gets the modification count of the document we are editing.
void incrementModificationCount (in long aModCount)
 called each time we modify the document.
void doTransaction (in nsITransaction txn)
 doTransaction() fires a transaction.
void enableUndo (in boolean enable)
 turn the undo system on or off
void undo (in unsigned long count)
 undo reverses the effects of the last Do operation, if Undo is enabled in the editor.
void canUndo (out boolean isEnabled, out boolean canUndo)
 returns state information about the undo system.
void redo (in unsigned long count)
 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.
void canRedo (out boolean isEnabled, out boolean canRedo)
 returns state information about the redo system.
void beginTransaction ()
 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.
void endTransaction ()
 endTransaction is a signal to the editor that the caller is finished updating the content model.
void beginPlaceHolderTransaction (in nsIAtom name)
void endPlaceHolderTransaction ()
boolean shouldTxnSetSelection ()
void setShouldTxnSetSelection (in boolean should)
 Set the flag that prevents insertElementTxn from changing the selection.
nsIInlineSpellChecker getInlineSpellChecker (in boolean autoCreate)
 Returns the inline spell checker associated with this object.
void syncRealTimeSpell ()
 Resyncs spellchecking state (enabled/disabled).
void setSpellcheckUserOverride (in boolean enable)
 Called when the user manually overrides the spellchecking state for this editor.
void cut ()
 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?
boolean canCut ()
 Can we cut? True if the doc is modifiable, and we have a non- collapsed selection.
void copy ()
 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?
boolean canCopy ()
 Can we copy? True if we have a non-collapsed selection.
void paste (in long aSelectionType)
 paste the text in the OS clipboard at the cursor position, replacing the selected text (if any)
void pasteTransferable (in nsITransferable aTransferable)
 Paste the text in |aTransferable| at the cursor position, replacing the selected text (if any).
boolean canPaste (in long aSelectionType)
 Can we paste? True if the doc is modifiable, and we have pasteable data in the clipboard.
boolean canPasteTransferable ([optional] in nsITransferable aTransferable)
 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|.
void selectAll ()
 sets the document selection to the entire contents of the document
void beginningOfDocument ()
 sets the document selection to the beginning of the document
void endOfDocument ()
 sets the document selection to the end of the document
boolean canDrag (in nsIDOMEvent aEvent)
 canDrag decides if a drag should be started (for example, based on the current selection and mousepoint).
void doDrag (in nsIDOMEvent aEvent)
 doDrag transfers the relevant data (as appropriate) to a transferable so it can later be dropped.
void insertFromDrop (in nsIDOMEvent aEvent)
 insertFromDrop looks for a dragsession and inserts the relevant data in response to a drop.
void setAttribute (in nsIDOMElement aElement, in AString attributestr, in AString attvalue)
 setAttribute() sets the attribute of aElement.
boolean getAttributeValue (in nsIDOMElement aElement, in AString attributestr, out AString resultValue)
 getAttributeValue() retrieves the attribute's value for aElement.
void removeAttribute (in nsIDOMElement aElement, in AString aAttribute)
 removeAttribute() deletes aAttribute from the attribute list of aElement.
void cloneAttribute (in AString aAttribute, in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode)
 cloneAttribute() copies the attribute from the source node to the destination node and delete those not in the source.
void cloneAttributes (in nsIDOMNode destNode, in nsIDOMNode sourceNode)
 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.
nsIDOMNode createNode (in AString tag, in nsIDOMNode parent, in long position)
 createNode instantiates a new element of type aTag and inserts it into aParent at aPosition.
void insertNode (in nsIDOMNode node, in nsIDOMNode parent, in long aPosition)
 insertNode inserts aNode into aParent at aPosition.
void splitNode (in nsIDOMNode existingRightNode, in long offset, out nsIDOMNode newLeftNode)
 splitNode() creates a new node identical to an existing node, and split the contents between the two nodes
void joinNodes (in nsIDOMNode leftNode, in nsIDOMNode rightNode, in nsIDOMNode parent)
 joinNodes() takes 2 nodes and merge their content|children.
void deleteNode (in nsIDOMNode child)
 deleteNode removes aChild from aParent.
void markNodeDirty (in nsIDOMNode node)
 markNodeDirty() sets a special dirty attribute on the node.
void switchTextDirection ()
 Switches the editor element direction; from "Left-to-Right" to "Right-to-Left", and vice versa.
AString outputToString (in AString formatType, in unsigned long flags)
 Output methods: aFormatType is a mime type, like text/plain.
void outputToStream (in nsIOutputStream aStream, in AString formatType, in ACString charsetOverride, in unsigned long flags)
void addEditorObserver (in nsIEditorObserver observer)
 add an EditorObserver to the editors list of observers.
void removeEditorObserver (in nsIEditorObserver observer)
 Remove an EditorObserver from the editor's list of observers.
void addEditActionListener (in nsIEditActionListener listener)
 add an EditActionListener to the editors list of listeners.
void removeEditActionListener (in nsIEditActionListener listener)
 Remove an EditActionListener from the editor's list of listeners.
void addDocumentStateListener (in nsIDocumentStateListener listener)
 Add a DocumentStateListener to the editors list of doc state listeners.
void removeDocumentStateListener (in nsIDocumentStateListener listener)
 Remove a DocumentStateListener to the editors list of doc state listeners.
void dumpContentTree ()
 And a debug method -- show us what the tree looks like right now.
void debugDumpContent ()
 Dumps a text representation of the content tree to standard out.
void debugUnitTests (out long outNumTests, out long outNumTestsFailed)
boolean isModifiableNode (in nsIDOMNode aNode)

Public Attributes

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
attribute unsigned long flags
 edit flags for this editor.
attribute string contentsMIMEType
 the MimeType of the document
readonly attribute boolean isDocumentEditable
 Returns true if we have a document that is not marked read-only.
readonly attribute nsIDOMDocument document
 the DOM Document this editor is associated with, refcounted.
readonly attribute nsIDOMElement rootElement
 the body element, i.e.
readonly attribute
nsISelectionController 
selectionController
 the selection controller for the current presentation, refcounted.
readonly attribute boolean documentIsEmpty
 Returns true if the document has no *meaningful* content.
readonly attribute boolean documentModified
 Returns true if the document is modifed and needs saving.
attribute ACString documentCharacterSet
 Sets the current 'Save' document character set.
attribute nsITransactionManager transactionManager
 transactionManager Get the transaction manager the editor is using.

Member Typedef Documentation

typedef short nsIEditor::EDirection

Member Function Documentation

void nsIEditor::addDocumentStateListener ( in nsIDocumentStateListener  listener  ) 

Add a DocumentStateListener to the editors list of doc state listeners.

void nsIEditor::addEditActionListener ( in nsIEditActionListener  listener  ) 

add an EditActionListener to the editors list of listeners.

void nsIEditor::addEditorObserver ( in nsIEditorObserver  observer  ) 

add an EditorObserver to the editors list of observers.

void nsIEditor::beginningOfDocument (  ) 

sets the document selection to the beginning of the document

void nsIEditor::beginPlaceHolderTransaction ( in nsIAtom  name  ) 
void nsIEditor::beginTransaction (  ) 

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.

boolean nsIEditor::canCopy (  ) 

Can we copy? True if we have a non-collapsed selection.

boolean nsIEditor::canCut (  ) 

Can we cut? True if the doc is modifiable, and we have a non- collapsed selection.

boolean nsIEditor::canDrag ( in nsIDOMEvent  aEvent  ) 

canDrag decides if a drag should be started (for example, based on the current selection and mousepoint).

boolean nsIEditor::canPaste ( in long  aSelectionType  ) 

Can we paste? True if the doc is modifiable, and we have pasteable data in the clipboard.

boolean nsIEditor::canPasteTransferable ( [optional] in nsITransferable  aTransferable  ) 

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|.

void nsIEditor::canRedo ( out boolean  isEnabled,
out boolean  canRedo 
)

returns state information about the redo system.

Parameters:
aIsEnabled [OUT] PR_TRUE if redo is enabled
aCanRedo [OUT] PR_TRUE if at least one transaction is currently ready to be redone.
void nsIEditor::canUndo ( out boolean  isEnabled,
out boolean  canUndo 
)

returns state information about the undo system.

Parameters:
aIsEnabled [OUT] PR_TRUE if undo is enabled
aCanUndo [OUT] PR_TRUE if at least one transaction is currently ready to be undone.
void nsIEditor::cloneAttribute ( in AString  aAttribute,
in nsIDOMNode  aDestNode,
in nsIDOMNode  aSourceNode 
)

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)

Parameters:
aAttribute the name of the attribute to copy
aDestNode the destination element to operate on
aSourceNode the source element to copy attributes from
Exceptions:
NS_ERROR_NULL_POINTER at least one of the nodes is null
NS_ERROR_NO_INTERFACE at least one of the nodes is not an element
void nsIEditor::cloneAttributes ( in nsIDOMNode  destNode,
in nsIDOMNode  sourceNode 
)

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)

Parameters:
aDestNode the destination element to operate on
aSourceNode the source element to copy attributes from
void nsIEditor::copy (  ) 

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?

nsIDOMNode nsIEditor::createNode ( in AString  tag,
in nsIDOMNode  parent,
in long  position 
)

createNode instantiates a new element of type aTag and inserts it into aParent at aPosition.

Parameters:
aTag The type of object to create
aParent The node to insert the new object into
aPosition The place in aParent to insert the new node
Returns:
The node created. Caller must release aNewNode.
void nsIEditor::cut (  ) 

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 nsIEditor::debugDumpContent (  ) 

Dumps a text representation of the content tree to standard out.

void nsIEditor::debugUnitTests ( out long  outNumTests,
out long  outNumTestsFailed 
)
void nsIEditor::deleteNode ( in nsIDOMNode  child  ) 

deleteNode removes aChild from aParent.

Parameters:
aChild The node to delete
void nsIEditor::deleteSelection ( in short  action  ) 

DeleteSelection removes all nodes in the current selection.

Parameters:
aDir if eNext, delete to the right (for example, the DEL key) if ePrevious, delete to the left (for example, the BACKSPACE key)
void nsIEditor::doDrag ( in nsIDOMEvent  aEvent  ) 

doDrag transfers the relevant data (as appropriate) to a transferable so it can later be dropped.

void nsIEditor::doTransaction ( in nsITransaction  txn  ) 

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.

Parameters:
aTxn the transaction to execute
void nsIEditor::dumpContentTree (  ) 

And a debug method -- show us what the tree looks like right now.

void nsIEditor::enableUndo ( in boolean  enable  ) 

turn the undo system on or off

Parameters:
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
Returns:
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 nsIEditor::endOfDocument (  ) 

sets the document selection to the end of the document

void nsIEditor::endPlaceHolderTransaction (  ) 
void nsIEditor::endTransaction (  ) 

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.

boolean nsIEditor::getAttributeValue ( in nsIDOMElement  aElement,
in AString  attributestr,
out AString  resultValue 
)

getAttributeValue() retrieves the attribute's value for aElement.

Parameters:
aElement the content element to operate on
aAttribute the string representation of the attribute to get
aResultValue [OUT] the value of aAttribute. Only valid if aResultIsSet is PR_TRUE
Returns:
PR_TRUE if aAttribute is set on the current node, PR_FALSE if it is not.
nsIInlineSpellChecker nsIEditor::getInlineSpellChecker ( in boolean  autoCreate  ) 

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.

Parameters:
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.
long nsIEditor::getModificationCount (  ) 

Gets the modification count of the document we are editing.

Returns:
the modification count of the document being edited. Zero means unchanged.
void nsIEditor::incrementModificationCount ( in long  aModCount  ) 

called each time we modify the document.

Increments the modification count of the document.

Parameters:
aModCount the number of modifications by which to increase or decrease the count
void nsIEditor::init ( in nsIDOMDocument  doc,
in nsIPresShellPtr  shell,
in nsIContent  aRoot,
in nsISelectionController  aSelCon,
in unsigned long  aFlags 
)

Init is to tell the implementation of nsIEditor to begin its services.

Parameters:
aDoc The dom document interface being observed
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.
aRoot This is the root of the editable section of this document. If it is null then we get root from document body.
aSelCon this should be used to get the selection location
aFlags A bitmask of flags for specifying the behavior of the editor.
void nsIEditor::insertFromDrop ( in nsIDOMEvent  aEvent  ) 

insertFromDrop looks for a dragsession and inserts the relevant data in response to a drop.

void nsIEditor::insertNode ( in nsIDOMNode  node,
in nsIDOMNode  parent,
in long  aPosition 
)

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.

Parameters:
aNode The DOM Node to insert.
aParent The node to insert the new object into
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
boolean nsIEditor::isModifiableNode ( in nsIDOMNode  aNode  ) 
void nsIEditor::joinNodes ( in nsIDOMNode  leftNode,
in nsIDOMNode  rightNode,
in nsIDOMNode  parent 
)

joinNodes() takes 2 nodes and merge their content|children.

Parameters:
aLeftNode The left node. It will be deleted.
aRightNode The right node. It will remain after the join.
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 nsIEditor::markNodeDirty ( in nsIDOMNode  node  ) 

markNodeDirty() sets a special dirty attribute on the node.

Usually this will be called immediately after creating a new node.

Parameters:
aNode The node for which to insert formatting.
void nsIEditor::outputToStream ( in nsIOutputStream  aStream,
in AString  formatType,
in ACString  charsetOverride,
in unsigned long  flags 
)
AString nsIEditor::outputToString ( in AString  formatType,
in unsigned long  flags 
)

Output methods: aFormatType is a mime type, like text/plain.

void nsIEditor::paste ( in long  aSelectionType  ) 

paste the text in the OS clipboard at the cursor position, replacing the selected text (if any)

void nsIEditor::pasteTransferable ( in nsITransferable  aTransferable  ) 

Paste the text in |aTransferable| at the cursor position, replacing the selected text (if any).

void nsIEditor::postCreate (  ) 

postCreate should be called after Init, and is the time that the editor tells its documentStateObservers that the document has been created.

void nsIEditor::preDestroy ( in boolean  aDestroyingFrames  ) 

preDestroy is called before the editor goes away, and gives the editor a chance to tell its documentStateObservers that the document is going away.

Parameters:
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 nsIEditor::redo ( in unsigned long  count  ) 

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 nsIEditor::removeAttribute ( in nsIDOMElement  aElement,
in AString  aAttribute 
)

removeAttribute() deletes aAttribute from the attribute list of aElement.

If aAttribute is not an attribute of aElement, nothing is done.

Parameters:
aElement the content element to operate on
aAttribute the string representation of the attribute to get
void nsIEditor::removeAttributeOrEquivalent ( in nsIDOMElement  element,
in DOMString  sourceAttrName,
in boolean  aSuppressTransaction 
)
void nsIEditor::removeDocumentStateListener ( in nsIDocumentStateListener  listener  ) 

Remove a DocumentStateListener to the editors list of doc state listeners.

void nsIEditor::removeEditActionListener ( in nsIEditActionListener  listener  ) 

Remove an EditActionListener from the editor's list of listeners.

void nsIEditor::removeEditorObserver ( in nsIEditorObserver  observer  ) 

Remove an EditorObserver from the editor's list of observers.

void nsIEditor::resetModificationCount (  ) 

to be used ONLY when we need to override the doc's modification state (such as when it's saved).

void nsIEditor::selectAll (  ) 

sets the document selection to the entire contents of the document

void nsIEditor::setAttribute ( in nsIDOMElement  aElement,
in AString  attributestr,
in AString  attvalue 
)

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.

Parameters:
aElement the content element to operate on
aAttribute the string representation of the attribute to set
aValue the value to set aAttribute to
void nsIEditor::setAttributeOrEquivalent ( in nsIDOMElement  element,
in AString  sourceAttrName,
in AString  sourceAttrValue,
in boolean  aSuppressTransaction 
)
void nsIEditor::setShouldTxnSetSelection ( in boolean  should  ) 

Set the flag that prevents insertElementTxn from changing the selection.

Parameters:
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 nsIEditor::setSpellcheckUserOverride ( in boolean  enable  ) 

Called when the user manually overrides the spellchecking state for this editor.

Parameters:
enable The new state of spellchecking in this editor, as requested by the user.
boolean nsIEditor::shouldTxnSetSelection (  ) 
void nsIEditor::splitNode ( in nsIDOMNode  existingRightNode,
in long  offset,
out nsIDOMNode  newLeftNode 
)

splitNode() creates a new node identical to an existing node, and split the contents between the two nodes

Parameters:
aExistingRightNode the node to split. It will become the new node's next sibling.
aOffset the offset of aExistingRightNode's content|children to do the split at
aNewLeftNode [OUT] the new node resulting from the split, becomes aExistingRightNode's previous sibling.
void nsIEditor::switchTextDirection (  ) 

Switches the editor element direction; from "Left-to-Right" to "Right-to-Left", and vice versa.

void nsIEditor::syncRealTimeSpell (  ) 

Resyncs spellchecking state (enabled/disabled).

This should be called when anything that affects spellchecking state changes, such as the spellcheck attribute value.

void nsIEditor::undo ( in unsigned long  count  ) 

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.


Member Data Documentation

attribute string nsIEditor::contentsMIMEType

the MimeType of the document

readonly attribute nsIDOMDocument nsIEditor::document

the DOM Document this editor is associated with, refcounted.

attribute ACString nsIEditor::documentCharacterSet

Sets the current 'Save' document character set.

readonly attribute boolean nsIEditor::documentIsEmpty

Returns true if the document has no *meaningful* content.

Returns true if the document is modifed and needs saving.

const short nsIEditor::eNext = 1
const short nsIEditor::eNextWord = 3
const short nsIEditor::eNone = 0
const short nsIEditor::ePrevious = 2
const short nsIEditor::ePreviousWord = 4
const short nsIEditor::eToEndOfLine = 6
attribute unsigned long nsIEditor::flags

edit flags for this editor.

May be set at any time.

Returns true if we have a document that is not marked read-only.

the body element, i.e.

the root of the editable document.

readonly attribute nsISelection nsIEditor::selection

the selection controller for the current presentation, refcounted.

transactionManager Get the transaction manager the editor is using.


The documentation for this interface was generated from the following file: