The Tor Browser: editor/idl/nsIEditor.idl@6474c204b198 (annotated)

editor/idl/nsIEditor.idl@6474c204b198 (annotated)

editor/idl/nsIEditor.idl

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /* -*- 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(65523eab-db1f-44aa-893e-dfe57ad306f0)]
 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,
                        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();
   /** 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;
 };

The Tor Browser / annotate

editor/idl/nsIEditor.idl@6474c204b198 (annotated)

editor/idl/nsIEditor.idl