Add m-esr52 at 52.6.0

1 files changed, 567 insertions, 0 deletions

diff --git a/editor/nsIEditor.idl b/editor/nsIEditor.idl
new file mode 100644
index 0000000000..bb9026d0ee
--- /dev/null
+++ b/editor/nsIEditor.idl
@@ -0,0 +1,567 @@
+/* -*- 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(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 nsISelection selection;
+
+  /**
+   * Finalizes selection and caret for the editor.
+   */
+  [noscript] void finalizeSelection();
+
+  /**
+   * 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();
+
+  /** 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)
+    */
+  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;
+
+  /**
+   * True if an edit action is being handled (in other words, between calls of
+   * nsIEditorObserver::BeforeEditAction() and nsIEditorObserver::EditAction()
+   * or nsIEditorObserver::CancelEditAction().  Otherwise, false.
+   */
+  [noscript] readonly attribute boolean isInEditAction;
+};