/* -*- 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 nsISelection;

interface nsISelectionController;

interface nsIDocumentStateListener;

interface nsIOutputStream;

interface nsITransactionManager;

interface nsITransaction;

interface nsIEditorObserver;

interface nsIEditActionListener;

interface nsIInlineSpellChecker;

interface nsITransferable;

%{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 nsISelection selection;

  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.

    */

  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);

  /**

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

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

    */

  void beginTransaction();

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

    */

  void endTransaction();

  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();

  /**

   * 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 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);

  /**

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

   * 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);

  /* Set true if you want to suppress dispatching input event. */

  attribute boolean suppressDispatchingInputEvent;

  /**

   * 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;

%}

};