/* -*- 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; webidl Document; webidl Element; webidl Node; webidl Selection; [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 attributes * so they will be incremented instead of inserting new tag */ void increaseFontSize(); /** * Decrease font size for text in selection by 1 HTML unit * All existing text is scanned for existing attributes * so they will be decreased instead of inserting new 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 Node 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 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 Element aElement, in boolean aDeleteSelection); /** * Set the BaseURL for the document to the current URL * but only if the page doesn't have a 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 Selection? */ /** * Set the selection at the suppled element * * @param aElement An element in the document */ void selectElement(in Element 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 Element 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 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) */ Element getElementOrParentByTagName(in AString aTagName, in Node 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); /** * 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. */ Element 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 Element aAnchorElement); /** * Set the value of the "bgcolor" attribute on the document's element * * @param aColor The HTML color string, such as "#ffccff" or "yellow" */ void setBackgroundColor(in AString aColor); /** * 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; /** * 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 Selection aSelection); boolean isAnonymousElement(in Element 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; };