summaryrefslogtreecommitdiffstats
path: root/editor/nsIHTMLEditor.idl
diff options
context:
space:
mode:
Diffstat (limited to 'editor/nsIHTMLEditor.idl')
-rw-r--r--editor/nsIHTMLEditor.idl559
1 files changed, 559 insertions, 0 deletions
diff --git a/editor/nsIHTMLEditor.idl b/editor/nsIHTMLEditor.idl
new file mode 100644
index 000000000..27bca9dbe
--- /dev/null
+++ b/editor/nsIHTMLEditor.idl
@@ -0,0 +1,559 @@
+/* -*- 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 nsIAtom;
+interface nsIContent;
+interface nsIArray;
+interface nsISelection;
+interface nsIContentFilter;
+
+%{C++
+namespace mozilla {
+namespace dom {
+class Element;
+}
+}
+%}
+
+[ptr] native Element (mozilla::dom::Element);
+
+[scriptable, 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 -------------- */
+
+
+ /**
+ * AddDefaultProperty() registers a default style property with the editor
+ *
+ * @param aProperty the property to set by default
+ * @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.
+ * Example: aProperty="font", aAttribute="color",
+ * aValue="0x00FFFF"
+ */
+ void addDefaultProperty(in nsIAtom aProperty,
+ in AString aAttribute,
+ in AString aValue);
+
+ /**
+ * RemoveDefaultProperty() unregisters a default style property with the editor
+ *
+ * @param aProperty the property to remove from defaults
+ * @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.
+ * Example: aProperty="font", aAttribute="color",
+ * aValue="0x00FFFF"
+ */
+ void removeDefaultProperty(in nsIAtom aProperty,
+ in AString aAttribute,
+ in AString aValue);
+
+ /**
+ * RemoveAllDefaultProperties() unregisters all default style properties with the editor
+ *
+ */
+ void removeAllDefaultProperties();
+
+ /**
+ * 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 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 nsIAtom aProperty,
+ in AString aAttribute,
+ in AString aValue,
+ out boolean aFirst,
+ out boolean aAny,
+ out boolean aAll);
+
+ AString getInlinePropertyWithAttrValue(in nsIAtom 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 nsIAtom 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 documents title.
+ */
+ void setDocumentTitle(in AString aTitle);
+
+ /**
+ * 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 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 NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
+ * (passes NS_SUCCEEDED macro)
+ */
+ nsIDOMElement getSelectedElement(in AString aTagName);
+
+ /**
+ * Output the contents of the <HEAD> section as text/HTML format
+ */
+ AString getHeadContentsAsHTML();
+
+ /**
+ * 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;
+
+ /**
+ * Add listener for insertion override
+ * @param inFilter function which callers want called during insertion
+ */
+ void addInsertionListener(in nsIContentFilter inFilter);
+
+ /**
+ * Remove listener for insertion override
+ * @param inFilter function which callers do not want called during insertion
+ */
+ void removeInsertionListener(in nsIContentFilter inFilter);
+
+ /**
+ * Returns an anonymous nsDOMElement of type aTag,
+ * child of aParentNode. If aIsCreatedHidden is true, the class
+ * "hidden" is added to the created element. If aAnonClass is not
+ * the empty string, it becomes the value of the attribute "_moz_anonclass"
+ * @return a DOM Element
+ * @param aTag [IN] a string representing the desired type of
+ * the element to create
+ * @param aParentNode [IN] the parent node of the created anonymous
+ * element
+ * @param aAnonClass [IN] contents of the _moz_anonclass attribute
+ * @param aIsCreatedHidden [IN] a boolean specifying if the class "hidden"
+ * is to be added to the created anonymous
+ * element
+ */
+ nsIDOMElement createAnonymousElement(in AString aTag, in nsIDOMNode aParentNode,
+ in AString aAnonClass, in boolean aIsCreatedHidden);
+
+ /**
+ * 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 <br> 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();
+};
+