mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-25 05:41:12 +00:00
9405d61cb8
`CanCut()`, `CanCopy()` and `CanPaste()` return error only when the editor has already been destroyed or not been initialized yet, or when failed to access clipboard when the document is not HTML/XHTML. `CanDelete()` returns error only when the editor has already been destroyed or not been initialized yet. So, these error result won't be exposed to the web in most cases and such exception shouldn't stop any content script because Chrome basically does not throw exception in such situation as far as I know. Therefore, there should be overloads of them to return `bool` result directly for making their callers simpler. Differential Revision: https://phabricator.services.mozilla.com/D28608 --HG-- extra : moz-landing-system : lando
522 lines
19 KiB
Plaintext
522 lines
19 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 nsIContent;
|
|
interface nsISelectionController;
|
|
interface nsIDocumentStateListener;
|
|
interface nsIOutputStream;
|
|
interface nsITransactionManager;
|
|
interface nsITransaction;
|
|
interface nsIEditorObserver;
|
|
interface nsIEditActionListener;
|
|
interface nsIInlineSpellChecker;
|
|
interface nsITransferable;
|
|
|
|
webidl Document;
|
|
webidl Element;
|
|
webidl Node;
|
|
webidl Selection;
|
|
|
|
%{C++
|
|
namespace mozilla {
|
|
class EditorBase;
|
|
class HTMLEditor;
|
|
class TextEditor;
|
|
} // namespace mozilla
|
|
%}
|
|
|
|
[scriptable, builtinclass, 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 Selection selection;
|
|
|
|
[can_run_script]
|
|
void setAttributeOrEquivalent(in Element element,
|
|
in AString sourceAttrName,
|
|
in AString sourceAttrValue,
|
|
in boolean aSuppressTransaction);
|
|
[can_run_script]
|
|
void removeAttributeOrEquivalent(in Element element,
|
|
in AString sourceAttrName,
|
|
in boolean aSuppressTransaction);
|
|
|
|
/** 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 Document document;
|
|
|
|
/** the body element, i.e. the root of the editable document.
|
|
*/
|
|
readonly attribute Element 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.
|
|
*/
|
|
readonly 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.
|
|
*
|
|
*/
|
|
[can_run_script]
|
|
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.
|
|
*
|
|
*/
|
|
[can_run_script]
|
|
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();
|
|
|
|
/**
|
|
* While setting the flag with this method to false, CreateElementTransaction,
|
|
* DeleteRangeTransaction, DeleteTextTransaction, InsertNodeTransaction,
|
|
* InsertTextTransaction and SplitNodeTransaction won't change Selection
|
|
* after modifying the DOM tree.
|
|
* Note that calling this with false does not guarantee that Selection won't
|
|
* be changed because other transaction may ignore this flag, editor itself
|
|
* may change selection, and current selection may become invalid after
|
|
* changing the DOM tree, etc.
|
|
* After calling this method with true, the caller should guarantee that
|
|
* Selection should be positioned where user expects.
|
|
*
|
|
* @param should false if you don't want above transactions to modify
|
|
* Selection automatically after modifying the DOM tree.
|
|
* Note that calling this with false does not guarantee
|
|
* that Selection is never changed.
|
|
*/
|
|
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);
|
|
|
|
/** 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)
|
|
*/
|
|
[can_run_script]
|
|
void paste(in long aClipboardType);
|
|
|
|
/** Paste the text in |aTransferable| at the cursor position, replacing the
|
|
* selected text (if any).
|
|
*/
|
|
[can_run_script]
|
|
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 aClipboardType);
|
|
|
|
/* ------------ Selection methods -------------- */
|
|
|
|
/** sets the document selection to the entire contents of the document */
|
|
[can_run_script]
|
|
void selectAll();
|
|
|
|
/**
|
|
* Collapses selection at start of the document. If it's an HTML editor,
|
|
* collapses selection at start of current editing host (<body> element if
|
|
* it's in designMode) instead. If there is a non-editable node before any
|
|
* editable text nodes or inline elements which can have text nodes as their
|
|
* children, collapses selection at start of the editing host. If there is
|
|
* an editable text node which is not collapsed, collapses selection at
|
|
* start of the text node. If there is an editable inline element which
|
|
* cannot have text nodes as its child, collapses selection at before the
|
|
* element node. Otherwise, collapses selection at start of the editing
|
|
* host.
|
|
*/
|
|
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 Element 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 Element 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 Element 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 aDestElement the destination element to operate on
|
|
* @param aSourceElement the source element to copy attributes from
|
|
* @exception NS_ERROR_NULL_POINTER at least one of the elements is null
|
|
*/
|
|
void cloneAttribute(in AString aAttribute,
|
|
in Element aDestElement, in Element aSourceElement);
|
|
|
|
/**
|
|
* cloneAttributes() is similar to Node::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 element already exists
|
|
*
|
|
* @param aDestNode the destination element to operate on
|
|
* @param aSourceNode the source element to copy attributes from
|
|
*/
|
|
[can_run_script]
|
|
void cloneAttributes(in Element aDestElement, in Element aSourceElement);
|
|
|
|
/**
|
|
* 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
|
|
*/
|
|
[can_run_script]
|
|
void insertNode(in Node node,
|
|
in Node 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 Node existingRightNode,
|
|
in long offset,
|
|
out Node 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 Node leftNode,
|
|
in Node rightNode,
|
|
in Node parent);
|
|
|
|
/**
|
|
* deleteNode removes aChild from aParent.
|
|
* @param aChild The node to delete
|
|
*/
|
|
void deleteNode(in Node 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 Node node);
|
|
|
|
/* ------------ Output methods -------------- */
|
|
|
|
/**
|
|
* Output methods:
|
|
* aFormatType is a mime type, like text/plain.
|
|
*/
|
|
AString outputToString(in AString formatType,
|
|
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);
|
|
|
|
/**
|
|
* forceCompositionEnd() force the composition end
|
|
*/
|
|
void forceCompositionEnd();
|
|
|
|
/**
|
|
* whether this editor has active IME transaction
|
|
*/
|
|
readonly attribute boolean composing;
|
|
|
|
%{C++
|
|
/**
|
|
* AsEditorBase() returns a pointer to EditorBase class.
|
|
*
|
|
* In order to avoid circular dependency issues, this method is defined
|
|
* in mozilla/EditorBase.h. Consumers need to #include that header.
|
|
*/
|
|
inline mozilla::EditorBase* AsEditorBase();
|
|
inline const mozilla::EditorBase* AsEditorBase() const;
|
|
|
|
/**
|
|
* AsTextEditor() returns a pointer to TextEditor class.
|
|
*
|
|
* In order to avoid circular dependency issues, this method is defined
|
|
* in mozilla/TextEditor.h. Consumers need to #include that header.
|
|
*/
|
|
inline mozilla::TextEditor* AsTextEditor();
|
|
inline const mozilla::TextEditor* AsTextEditor() const;
|
|
|
|
/**
|
|
* AsHTMLEditor() returns a pointer to HTMLEditor class.
|
|
*
|
|
* In order to avoid circular dependency issues, this method is defined
|
|
* in mozilla/HTMLEditor.h. Consumers need to #include that header.
|
|
*/
|
|
inline mozilla::HTMLEditor* AsHTMLEditor();
|
|
inline const mozilla::HTMLEditor* AsHTMLEditor() const;
|
|
%}
|
|
};
|