/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: NPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Netscape Public License * Version 1.1 (the "License"); you may not use this file except in * compliance with the License. You may obtain a copy of the License at * http://www.mozilla.org/NPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 1998 * the Initial Developer. All Rights Reserved. * * Contributor(s): * * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the NPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the NPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" #include "domstubs.idl" #include "nsIAtom.idl" interface nsISupportsArray; %{C++ #define NS_EDITOR_ELEMENT_NOT_FOUND \ NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_EDITOR, 1) %} [scriptable, uuid(4b0fd0d0-1dd2-11b2-bf2e-ef20fbca2c88)] 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 nsIAtom aProperty, in DOMString aAttribute, in DOMString aValue); /** * GetInlineProperty() gets the 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 nsIAtom aProperty, in DOMString aAttribute, in DOMString aValue, out boolean aFirst, out boolean aAny, out boolean aAll); void GetInlinePropertyWithAttrValue(in nsIAtom aProperty, in DOMString aAttribute, in DOMString aValue, out boolean aFirst, out boolean aAny, out boolean aAll, out DOMString outValue); /** * 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.: nsIEditorProptery::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 nsIAtom aProperty, in DOMString 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(); /* ------------ Drag/Drop methods -------------- */ /** * CanDrag decides if a drag should be started * (for example, based on the current selection and mousepoint). */ void CanDrag(in nsIDOMEvent aEvent, out boolean aCanDrag); /** * DoDrag transfers the relevant data (as appropriate) * to a transferable so it can later be dropped. */ void DoDrag(in nsIDOMEvent aEvent); /** * InsertFromDrop looks for a dragsession and inserts the * relevant data in response to a drop. */ void InsertFromDrop(in nsIDOMEvent aEvent); /* ------------ 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 */ void NodeIsBlock(in nsIDOMNode node, out boolean isBlock); /** * Insert some HTML source at the current location * * @param aInputString the string to be inserted */ void InsertHTML(in DOMString aInputString); /** 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 DOMString aSourceString); /** * Insert some HTML source, interpreting * the string argument according to the given charset. * * @param aInputString the string to be inserted * @param aCharset Charset of string * @param aParentNode Parent to insert under. * If null, insert at the current location. */ void InsertHTMLWithCharset(in DOMString aInputString, in DOMString aCharset); /** 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 documents title. */ void SetDocumentTitle(in DOMString aTitle); /* ------------ 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 DOMString aParagraphFormat); /** * GetParagraphState returns what block tag paragraph format is in the selection. * @param aMixed True if there is more than one format * @param outState Name of block tag. "" is returned for none. */ void GetParagraphState(out boolean aMixed,out DOMString outState); /** * GetFontFaceState returns what font face is in the selection. * @param aMixed True if there is more than one font face * @param outFace Name of face. Note: "tt" is returned for * tt tag. "" is returned for none. */ void GetFontFaceState(out boolean aMixed,out DOMString outFont); /** * GetFontColorState returns what font face is in the selection. * @param aMixed True if there is more than one font color * @param outColor Color string. "" is returned for none. */ void GetFontColorState(out boolean aMixed,out DOMString outColor); /** * GetFontColorState returns what font face is in the selection. * @param aMixed True if there is more than one font color * @param outColor Color string. "" is returned for none. */ void GetBackgroundColorState(out boolean aMixed,out DOMString outColor); /** * 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 DOMString aListType, in boolean entireList, in DOMString aBulletType); /** * Document me! * */ void RemoveList(in DOMString aListType); /** * Document me! * */ void Indent(in DOMString aIndent); /** * Document me! * */ void Align(in DOMString 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 * Returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found (passes NS_SUCCEEDED macro) */ void GetElementOrParentByTagName(in DOMString aTagName, in nsIDOMNode aNode, out nsIDOMElement aReturn); /** Return an element only if it is the only node selected, * such as an image, horizontal rule, etc. * 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) * Returns NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found (passes NS_SUCCEEDED macro) */ void GetSelectedElement(in DOMString aTagName, out nsIDOMElement aReturn); /** Output the contents of the section as text/HTML format */ void GetHeadContentsAsHTML(out DOMString aOutputString); /** Replace all children of with string of HTML source */ void ReplaceHeadContentsWithHTML(in DOMString 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) */ void CreateElementWithDefaults(in DOMString aTagName, out nsIDOMElement aReturn); /** 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 element * * @param aColor The HTML color string, such as "#ffccff" or "yellow" */ void SetBackgroundColor(in DOMString aColor); /** Set an attribute on the document's 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 DOMString aAttr, in DOMString aValue); //XXX Used to suppress spurious drag/drop events to workaround bug 50703 // Don't use this method! It will go away after first release! void IgnoreSpuriousDragEvent(in boolean aIgnoreSpuriousDragEvent); /** * 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 */ nsISupportsArray GetLinkedObjects(); };