Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-12-28 11:28:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
8b454010c1
gecko-dev/editor/idl/nsIEditor.idl

554 lines
21 KiB
Plaintext
Raw Blame History

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is the Mozilla browser.
*
* The Initial Developer of the Original Code is
* Netscape Communications, Inc.
* Portions created by the Initial Developer are Copyright (C) 1999
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Daniel Glazman <glazman@netscape.com>
* Akkana Peck <akkana@netscape.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
#include "domstubs.idl"
interface nsIURI;
interface nsIAtom;
interface nsISelection;
interface nsISelectionController;
interface nsIDocumentStateListener;
interface nsIOutputStream;
interface nsITransactionManager;
interface nsITransaction;
interface nsIEditorObserver;
interface nsIEditActionListener;
interface nsIInlineSpellChecker;
%{C++
class nsIPresShell;
class nsIContent;
typedef short EDirection;
%}
[ptr] native nsIPresShellPtr(nsIPresShell);
[ptr] native nsIContentPtr(nsIContent);
[scriptable, uuid(e7cb6526-0809-47ee-b484-a6f297e536c0)]
interface nsIEditor : nsISupports
{
%{C++
typedef short EDirection;
%}
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;
/**
* Init 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.
* @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
* @param aFlags A bitmask of flags for specifying the behavior
* of the editor.
*/
[noscript] void init(in nsIDOMDocument doc, in nsIPresShellPtr shell,
in nsIContentPtr 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.
*/
void preDestroy();
/** 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;
/**
* 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)
*/
void deleteSelection(in short action);
/* ------------ 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.
*
*/
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);
/* ------------ 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);
/** Can we paste? True if the doc is modifiable, and we have
* pasteable data in the clipboard.
*/
boolean canPaste(in long aSelectionType);
/* ------------ 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();
/* ------------ Drag/Drop methods -------------- */
/**
* canDrag decides if a drag should be started
* (for example, based on the current selection and mousepoint).
*/
boolean canDrag(in nsIDOMEvent aEvent);
/**
* doDrag transfers the relevant data (as appropriate)
* to a transferable so it can later be dropped.
*/
void doDrag(in nsIDOMEvent aEvent);
/**
* insertFromDrop looks for a dragsession and inserts the
* relevant data in response to a drop.
*/
void insertFromDrop(in nsIDOMEvent aEvent);
/* ------------ 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);
/**
* 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 -------------- */
/** 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);
};
Reference in New Issue View Git Blame Copy Permalink