/* -*- Mode: C++; tab-width: 2; 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 nsIContent;

interface nsIArray;

interface nsISelection;

%{C++

namespace mozilla {

namespace dom {

class Element;

}

}

%}

[ptr] native Element (mozilla::dom::Element);

[scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)]

interface nsIHTMLEditor : nsISupports

{

%{C++

  typedef short EAlignment;

%}

  // used by GetAlignment()

  const short eLeft = 0;

  const short eCenter = 1;

  const short eRight = 2;

  const short eJustify = 3;

  /* ------------ Inline property methods -------------- */

  /**

   * SetInlineProperty() sets the aggregate properties on the current selection

   *

   * @param aProperty   the property to set on the selection

   * @param aAttribute  the attribute of the property, if applicable.

   *                    May be null.

   *                    Example: aProperty="font", aAttribute="color"

   * @param aValue      if aAttribute is not null, the value of the attribute.

   *                    May be null.

   *                    Example: aProperty="font", aAttribute="color",

   *                             aValue="0x00FFFF"

   */

  void setInlineProperty(in AString aProperty,

                         in AString aAttribute,

                         in AString aValue);

  /**

   * getInlineProperty() gets aggregate properties of the current selection.

   * All object in the current selection are scanned and their attributes are

   * represented in a list of Property object.

   *

   * @param aProperty   the property to get on the selection

   * @param aAttribute  the attribute of the property, if applicable.

   *                    May be null.

   *                    Example: aProperty="font", aAttribute="color"

   * @param aValue      if aAttribute is not null, the value of the attribute.

   *                    May be null.

   *                    Example: aProperty="font", aAttribute="color",

   *                             aValue="0x00FFFF"

   * @param aFirst      [OUT] PR_TRUE if the first text node in the

   *                          selection has the property

   * @param aAny        [OUT] PR_TRUE if any of the text nodes in the

   *                          selection have the property

   * @param aAll        [OUT] PR_TRUE if all of the text nodes in the

   *                          selection have the property

   */

  void getInlineProperty(in AString aProperty,

                         in AString aAttribute,

                         in AString aValue,

                         out boolean aFirst,

                         out boolean aAny,

                         out boolean aAll);

  AString getInlinePropertyWithAttrValue(in AString aProperty,

                                         in AString aAttribute,

                                         in AString aValue,

                                         out boolean aFirst,

                                         out boolean aAny,

                                         out boolean aAll);

  /**

   * removeAllInlineProperties() deletes all the inline properties from all

   * text in the current selection.

   */

  void removeAllInlineProperties();

  /**

   * removeInlineProperty() deletes the properties from all text in the current

   * selection.  If aProperty is not set on the selection, nothing is done.

   *

   * @param aProperty   the property to remove from the selection

   *                    All atoms are for normal HTML tags (e.g.:

   *                    nsIEditorProperty::font) except when you want to

   *                    remove just links and not named anchors.

   *                    For that, use nsIEditorProperty::href

   * @param aAttribute  the attribute of the property, if applicable.

   *                    May be null.

   *                    Example: aProperty=nsIEditorProptery::font,

   *                    aAttribute="color"

   *                    nsIEditProperty::allAttributes is special.

   *                    It indicates that all content-based text properties

   *                    are to be removed from the selection.

   */

  void removeInlineProperty(in AString aProperty, in AString aAttribute);

  /**

   *  Increase font size for text in selection by 1 HTML unit

   *  All existing text is scanned for existing <FONT SIZE> attributes

   *  so they will be incremented instead of inserting new <FONT> tag

   */

  void increaseFontSize();

  /**

   *  Decrease font size for text in selection by 1 HTML unit

   *  All existing text is scanned for existing <FONT SIZE> attributes

   *  so they will be decreased instead of inserting new <FONT> tag

   */

  void decreaseFontSize();

  /* ------------ HTML content methods -------------- */

  /**

   * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.

   *   This does NOT consider CSS effect on display type

   *

   * @param aNode      the node to test

   */

  boolean nodeIsBlock(in nsIDOMNode node);

  /**

   * Insert some HTML source at the current location

   *

   * @param aInputString   the string to be inserted

   */

  void insertHTML(in AString aInputString);

  /**

    * Paste the text in the OS clipboard at the cursor position, replacing

    * the selected text (if any), but strip out any HTML styles and formatting

    */

  void pasteNoFormatting(in long aSelectionType);

  /**

   *  Rebuild the entire document from source HTML

   *  Needed to be able to edit HEAD and other outside-of-BODY content

   *

   *  @param aSourceString   HTML source string of the entire new document

   */

  void rebuildDocumentFromSource(in AString aSourceString);

  /**

   * Insert some HTML source, interpreting

   * the string argument according to the given context.

   *

   * @param aInputString   the string to be inserted

   * @param aContextStr    Context of insertion

   * @param aInfoStr       Related info to aInputString

   * @param aFlavor        Transferable flavor, can be ""

   * @param aSourceDoc          document where input was dragged from (may be null)

   * @param aDestinationNode    location for insertion (such as when dropped)

   * @param aDestinationOffset  used with aDestNode to determine insert location

   * @param aDeleteSelection    used with aDestNode during drag&drop

   * @param aCollapseSelection  used with aDestNode during drag&drop

   */

  void insertHTMLWithContext(in AString aInputString,

                             in AString aContextStr,

                             in AString aInfoStr,

                             in AString aFlavor,

                             in nsIDOMDocument aSourceDoc,

                             in nsIDOMNode aDestinationNode,

                             in long aDestinationOffset,

                             in boolean aDeleteSelection);

  /**

    * Insert an element, which may have child nodes, at the selection

    * Used primarily to insert a new element for various insert element dialogs,

    *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should

    *   be useful for other elements.

    *

    * @param aElement           The element to insert

    * @param aDeleteSelection   Delete the selection before inserting

    *     If aDeleteSelection is PR_FALSE, then the element is inserted

    *     after the end of the selection for all element except

    *     Named Anchors, which insert before the selection

    */

  void insertElementAtSelection(in nsIDOMElement aElement,

                                in boolean aDeleteSelection);

  /**

   *   Set the BaseURL for the document to the current URL

   *     but only if the page doesn't have a <base> tag

   *   This should be done after the document URL has changed,

   *     such as after saving a file

   *   This is used as base for relativizing link and image urls

   */

  void updateBaseURL();

  /* ------------ Selection manipulation -------------- */

  /* Should these be moved to nsISelection? */

  /**

    * Set the selection at the suppled element

    *

    * @param aElement   An element in the document

    */

  void selectElement(in nsIDOMElement aElement);

  /**

    * Create a collapsed selection just after aElement

    *

    * XXX could we parameterize SelectElement(before/select/after>?

    *

    * The selection is set to parent-of-aElement with an

    *   offset 1 greater than aElement's offset

    *   but it enforces the HTML 4.0 DTD "CanContain" rules, so it should

    *   be useful for other elements.

    *

    * @param aElement  An element in the document

    */

  void setCaretAfterElement(in nsIDOMElement aElement);

  /**

   * SetParagraphFormat       Insert a block paragraph tag around selection

   * @param aParagraphFormat  "p", "h1" to "h6", "address", "pre", or "blockquote"

   */

  void setParagraphFormat(in AString aParagraphFormat);

  /**

   * getParagraphState returns what block tag paragraph format is in

   * the selection.

   * @param aMixed     True if there is more than one format

   * @return           Name of block tag. "" is returned for none.

   */

  AString getParagraphState(out boolean aMixed);

  /**

   * getFontFaceState returns what font face is in the selection.

   * @param aMixed    True if there is more than one font face

   * @return          Name of face.  Note: "tt" is returned for

   *                  tt tag.  "" is returned for none.

   */

  AString getFontFaceState(out boolean aMixed);

  /**

   * getFontColorState returns what font face is in the selection.

   * @param aMixed     True if there is more than one font color

   * @return           Color string. "" is returned for none.

   */

  AString getFontColorState(out boolean aMixed);

  /**

   * getFontColorState returns what font face is in the selection.

   * @param aMixed     True if there is more than one font color

   * @return           Color string. "" is returned for none.

   */

  AString getBackgroundColorState(out boolean aMixed);

  /**

   * getHighlightColorState returns what the highlight color of the selection.

   * @param aMixed     True if there is more than one font color

   * @return           Color string. "" is returned for none.

   */

  AString getHighlightColorState(out boolean aMixed);

  /**

   * getListState returns what list type is in the selection.

   * @param aMixed    True if there is more than one type of list, or

   *                  if there is some list and non-list

   * @param aOL       The company that employs me.  No, really, it's

   *                  true if an "ol" list is selected.

   * @param aUL       true if an "ul" list is selected.

   * @param aDL       true if a "dl" list is selected.

   */

  void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,

                    out boolean aDL);

  /**

   * getListItemState returns what list item type is in the selection.

   * @param aMixed    True if there is more than one type of list item, or

   *                  if there is some list and non-list

   * @param aLI       true if "li" list items are selected.

   * @param aDT       true if "dt" list items are selected.

   * @param aDD       true if "dd" list items are selected.

   */

  void getListItemState(out boolean aMixed, out boolean aLI,

                        out boolean aDT, out boolean aDD);

  /**

   * getAlignment     returns what alignment is in the selection.

   * @param aMixed    True if there is more than one type of list item, or

   *                  if there is some list and non-list

   * @param aAlign    enum value for first encountered alignment

   *                  (left/center/right)

   */

  void getAlignment(out boolean aMixed, out short aAlign);

  /**

   * Document me!

   *

   */

  void getIndentState(out boolean aCanIndent, out boolean aCanOutdent);

  /**

   * Document me!

   *

   */

  void makeOrChangeList(in AString aListType, in boolean entireList,

                        in AString aBulletType);

  /**

   * Document me!

   *

   */

  void removeList(in AString aListType);

  /**

   * Document me!

   *

   */

  void indent(in AString aIndent);

  /**

   * Document me!

   *

   */

  void  align(in AString aAlign);

  /**

   * Return the input node or a parent matching the given aTagName,

   *   starting the search at the supplied node.

   * An example of use is for testing if a node is in a table cell

   *   given a selection anchor node.

   *

   * @param aTagName  The HTML tagname

   *  Special input values:

   *    Use "href" to get a link node

   *      (an "A" tag with the "href" attribute set)

   *    Use "anchor" or "namedanchor" to get a named anchor node

   *      (an "A" tag with the "name" attribute set)

   *    Use "list" to get an OL, UL, or DL list node

   *    Use "td" to get either a TD or TH cell node

   *

   * @param aNode    The node in the document to start the search.

   *     If it is null, the anchor node of the current selection is used.

   * @return         NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found

   *                 (passes NS_SUCCEEDED macro)

   */

  nsIDOMElement getElementOrParentByTagName(in AString aTagName,

                                            in nsIDOMNode aNode);

  /**

   * Return an Element only if it is the only node selected,

   *    such as an image, horizontal rule, etc.  The return type is

   *    nsISupports for implementation convenience; the returned object,

   *    if not null, is always a DOM Element.

   *

   * The exception is a link, which is more like a text attribute:

   *    The Anchor tag is returned if the selection is within the textnode(s)

   *    that are children of the "A" node.

   *    This could be a collapsed selection, i.e., a caret

   *    within the link text.

   *

   * @param aTagName  The HTML tagname or and empty string

   *       to get any element (but only if it is the only element selected)

   *    Special input values for Links and Named anchors:

   *    Use "href" to get a link node

   *      (an "A" tag with the "href" attribute set)

   *    Use "anchor" or "namedanchor" to get a named anchor node

   *      (an "A" tag with the "name" attribute set)

   * @return the element as described above

   */

  nsISupports getSelectedElement(in AString aTagName);

  /**

   * Replace all children of <HEAD> with string of HTML source

   */

  void replaceHeadContentsWithHTML(in AString aSourceToInsert);

  /**

   * Return a new element with default attribute values

   *

   * This does not rely on the selection, and is not sensitive to context.

   *

   * Used primarily to supply new element for various insert element dialogs

   *  (Image, Link, NamedAnchor, Table, and HorizontalRule

   *   are the only returned elements as of 7/25/99)

   *

   * @param aTagName  The HTML tagname

   *    Special input values for Links and Named anchors:

   *    Use "href" to get a link node

   *      (an "A" tag with the "href" attribute set)

   *    Use "anchor" or "namedanchor" to get a named anchor node

   *      (an "A" tag with the "name" attribute set)

   * @return          The new element created.

   */

  nsIDOMElement createElementWithDefaults(in AString aTagName);

  /**

   * Insert an link element as the parent of the current selection

   *

   * @param aElement   An "A" element with a non-empty "href" attribute

   */

  void insertLinkAroundSelection(in nsIDOMElement aAnchorElement);

  /**

   * Set the value of the "bgcolor" attribute on the document's <body> element

   *

   * @param aColor  The HTML color string, such as "#ffccff" or "yellow"

   */

  void setBackgroundColor(in AString aColor);

  /**

   * Set an attribute on the document's <body> element

   *    such as text, link, background colors

   *

   * 8/31/00 THIS ISN'T BEING USED? SHOULD WE DROP IT?

   *

   * @param aAttr   The attribute to be set

   * @param aValue  The value of the attribute

   */

  void setBodyAttribute(in AString aAttr, in AString aValue);

  /**

   * Find all the nodes in the document which contain references

   * to outside URIs (e.g. a href, img src, script src, etc.)

   * The objects in the array will be type nsIURIRefObject.

   *

   * @return aNodeList    the linked nodes found

   */

  nsIArray getLinkedObjects();

  /**

   * A boolean which is true is the HTMLEditor has been instantiated

   * with CSS knowledge and if the CSS pref is currently checked

   *

   * @return    true if CSS handled and enabled

   */

  attribute boolean isCSSEnabled;

  /**

   * returns the deepest container of the selection

   * @return a DOM Element

   */

  nsIDOMElement getSelectionContainer();

  /**

   * Checks if the anonymous nodes created by the HTML editor have to be

   * refreshed or hidden depending on a possible new state of the selection

   * @param aSelection [IN] a selection

   */

  void checkSelectionStateForAnonymousButtons(in nsISelection aSelection);

  boolean isAnonymousElement(in nsIDOMElement aElement);

  /**

   * A boolean indicating if a return key pressed in a paragraph creates

   * another paragraph or just inserts a 
 at the caret

   *

   * @return    true if CR in a paragraph creates a new paragraph

   */

  attribute boolean returnInParagraphCreatesNewParagraph;

  /**

   * Get an active editor's editing host in DOM window.  If this editor isn't

   * active in the DOM window, this returns NULL.

   */

  [noscript, notxpcom] Element GetActiveEditingHost();

};