1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/editor/idl/nsIHTMLEditor.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,565 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +#include "domstubs.idl"
1.11 +
1.12 +interface nsIAtom;
1.13 +interface nsIContent;
1.14 +interface nsISupportsArray;
1.15 +interface nsISelection;
1.16 +interface nsIContentFilter;
1.17 +
1.18 +%{C++
1.19 +namespace mozilla {
1.20 +namespace dom {
1.21 +class Element;
1.22 +}
1.23 +}
1.24 +%}
1.25 +
1.26 +[ptr] native Element (mozilla::dom::Element);
1.27 +
1.28 +[scriptable, uuid(833f30de-94c7-4630-a852-2300ef329d7b)]
1.29 +
1.30 +interface nsIHTMLEditor : nsISupports
1.31 +{
1.32 +%{C++
1.33 + typedef short EAlignment;
1.34 +%}
1.35 +
1.36 + // used by GetAlignment()
1.37 + const short eLeft = 0;
1.38 + const short eCenter = 1;
1.39 + const short eRight = 2;
1.40 + const short eJustify = 3;
1.41 +
1.42 +
1.43 + /* ------------ Inline property methods -------------- */
1.44 +
1.45 +
1.46 + /**
1.47 + * AddDefaultProperty() registers a default style property with the editor
1.48 + *
1.49 + * @param aProperty the property to set by default
1.50 + * @param aAttribute the attribute of the property, if applicable.
1.51 + * May be null.
1.52 + * Example: aProperty="font", aAttribute="color"
1.53 + * @param aValue if aAttribute is not null, the value of the attribute.
1.54 + * Example: aProperty="font", aAttribute="color",
1.55 + * aValue="0x00FFFF"
1.56 + */
1.57 + void addDefaultProperty(in nsIAtom aProperty,
1.58 + in AString aAttribute,
1.59 + in AString aValue);
1.60 +
1.61 + /**
1.62 + * RemoveDefaultProperty() unregisters a default style property with the editor
1.63 + *
1.64 + * @param aProperty the property to remove from defaults
1.65 + * @param aAttribute the attribute of the property, if applicable.
1.66 + * May be null.
1.67 + * Example: aProperty="font", aAttribute="color"
1.68 + * @param aValue if aAttribute is not null, the value of the attribute.
1.69 + * Example: aProperty="font", aAttribute="color",
1.70 + * aValue="0x00FFFF"
1.71 + */
1.72 + void removeDefaultProperty(in nsIAtom aProperty,
1.73 + in AString aAttribute,
1.74 + in AString aValue);
1.75 +
1.76 + /**
1.77 + * RemoveAllDefaultProperties() unregisters all default style properties with the editor
1.78 + *
1.79 + */
1.80 + void removeAllDefaultProperties();
1.81 +
1.82 + /**
1.83 + * SetInlineProperty() sets the aggregate properties on the current selection
1.84 + *
1.85 + * @param aProperty the property to set on the selection
1.86 + * @param aAttribute the attribute of the property, if applicable.
1.87 + * May be null.
1.88 + * Example: aProperty="font", aAttribute="color"
1.89 + * @param aValue if aAttribute is not null, the value of the attribute.
1.90 + * May be null.
1.91 + * Example: aProperty="font", aAttribute="color",
1.92 + * aValue="0x00FFFF"
1.93 + */
1.94 + void setInlineProperty(in nsIAtom aProperty,
1.95 + in AString aAttribute,
1.96 + in AString aValue);
1.97 +
1.98 + /**
1.99 + * getInlineProperty() gets aggregate properties of the current selection.
1.100 + * All object in the current selection are scanned and their attributes are
1.101 + * represented in a list of Property object.
1.102 + *
1.103 + * @param aProperty the property to get on the selection
1.104 + * @param aAttribute the attribute of the property, if applicable.
1.105 + * May be null.
1.106 + * Example: aProperty="font", aAttribute="color"
1.107 + * @param aValue if aAttribute is not null, the value of the attribute.
1.108 + * May be null.
1.109 + * Example: aProperty="font", aAttribute="color",
1.110 + * aValue="0x00FFFF"
1.111 + * @param aFirst [OUT] PR_TRUE if the first text node in the
1.112 + * selection has the property
1.113 + * @param aAny [OUT] PR_TRUE if any of the text nodes in the
1.114 + * selection have the property
1.115 + * @param aAll [OUT] PR_TRUE if all of the text nodes in the
1.116 + * selection have the property
1.117 + */
1.118 + void getInlineProperty(in nsIAtom aProperty,
1.119 + in AString aAttribute,
1.120 + in AString aValue,
1.121 + out boolean aFirst,
1.122 + out boolean aAny,
1.123 + out boolean aAll);
1.124 +
1.125 + AString getInlinePropertyWithAttrValue(in nsIAtom aProperty,
1.126 + in AString aAttribute,
1.127 + in AString aValue,
1.128 + out boolean aFirst,
1.129 + out boolean aAny,
1.130 + out boolean aAll);
1.131 +
1.132 + /**
1.133 + * removeAllInlineProperties() deletes all the inline properties from all
1.134 + * text in the current selection.
1.135 + */
1.136 + void removeAllInlineProperties();
1.137 +
1.138 +
1.139 + /**
1.140 + * removeInlineProperty() deletes the properties from all text in the current
1.141 + * selection. If aProperty is not set on the selection, nothing is done.
1.142 + *
1.143 + * @param aProperty the property to remove from the selection
1.144 + * All atoms are for normal HTML tags (e.g.:
1.145 + * nsIEditorProperty::font) except when you want to
1.146 + * remove just links and not named anchors.
1.147 + * For that, use nsIEditorProperty::href
1.148 + * @param aAttribute the attribute of the property, if applicable.
1.149 + * May be null.
1.150 + * Example: aProperty=nsIEditorProptery::font,
1.151 + * aAttribute="color"
1.152 + * nsIEditProperty::allAttributes is special.
1.153 + * It indicates that all content-based text properties
1.154 + * are to be removed from the selection.
1.155 + */
1.156 + void removeInlineProperty(in nsIAtom aProperty, in AString aAttribute);
1.157 +
1.158 + /**
1.159 + * Increase font size for text in selection by 1 HTML unit
1.160 + * All existing text is scanned for existing <FONT SIZE> attributes
1.161 + * so they will be incremented instead of inserting new <FONT> tag
1.162 + */
1.163 + void increaseFontSize();
1.164 +
1.165 + /**
1.166 + * Decrease font size for text in selection by 1 HTML unit
1.167 + * All existing text is scanned for existing <FONT SIZE> attributes
1.168 + * so they will be decreased instead of inserting new <FONT> tag
1.169 + */
1.170 + void decreaseFontSize();
1.171 +
1.172 + /* ------------ HTML content methods -------------- */
1.173 +
1.174 + /**
1.175 + * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
1.176 + * This does NOT consider CSS effect on display type
1.177 + *
1.178 + * @param aNode the node to test
1.179 + */
1.180 + boolean nodeIsBlock(in nsIDOMNode node);
1.181 +
1.182 + /**
1.183 + * Insert some HTML source at the current location
1.184 + *
1.185 + * @param aInputString the string to be inserted
1.186 + */
1.187 + void insertHTML(in AString aInputString);
1.188 +
1.189 +
1.190 + /**
1.191 + * Paste the text in the OS clipboard at the cursor position, replacing
1.192 + * the selected text (if any), but strip out any HTML styles and formatting
1.193 + */
1.194 + void pasteNoFormatting(in long aSelectionType);
1.195 +
1.196 + /**
1.197 + * Rebuild the entire document from source HTML
1.198 + * Needed to be able to edit HEAD and other outside-of-BODY content
1.199 + *
1.200 + * @param aSourceString HTML source string of the entire new document
1.201 + */
1.202 + void rebuildDocumentFromSource(in AString aSourceString);
1.203 +
1.204 + /**
1.205 + * Insert some HTML source, interpreting
1.206 + * the string argument according to the given context.
1.207 + *
1.208 + * @param aInputString the string to be inserted
1.209 + * @param aContextStr Context of insertion
1.210 + * @param aInfoStr Related info to aInputString
1.211 + * @param aFlavor Transferable flavor, can be ""
1.212 + * @param aSourceDoc document where input was dragged from (may be null)
1.213 + * @param aDestinationNode location for insertion (such as when dropped)
1.214 + * @param aDestinationOffset used with aDestNode to determine insert location
1.215 + * @param aDeleteSelection used with aDestNode during drag&drop
1.216 + * @param aCollapseSelection used with aDestNode during drag&drop
1.217 + */
1.218 + void insertHTMLWithContext(in AString aInputString,
1.219 + in AString aContextStr,
1.220 + in AString aInfoStr,
1.221 + in AString aFlavor,
1.222 + in nsIDOMDocument aSourceDoc,
1.223 + in nsIDOMNode aDestinationNode,
1.224 + in long aDestinationOffset,
1.225 + in boolean aDeleteSelection);
1.226 +
1.227 +
1.228 + /**
1.229 + * Insert an element, which may have child nodes, at the selection
1.230 + * Used primarily to insert a new element for various insert element dialogs,
1.231 + * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
1.232 + * be useful for other elements.
1.233 + *
1.234 + * @param aElement The element to insert
1.235 + * @param aDeleteSelection Delete the selection before inserting
1.236 + * If aDeleteSelection is PR_FALSE, then the element is inserted
1.237 + * after the end of the selection for all element except
1.238 + * Named Anchors, which insert before the selection
1.239 + */
1.240 + void insertElementAtSelection(in nsIDOMElement aElement,
1.241 + in boolean aDeleteSelection);
1.242 +
1.243 + /**
1.244 + * Set the documents title.
1.245 + */
1.246 + void setDocumentTitle(in AString aTitle);
1.247 +
1.248 + /**
1.249 + * Set the BaseURL for the document to the current URL
1.250 + * but only if the page doesn't have a <base> tag
1.251 + * This should be done after the document URL has changed,
1.252 + * such as after saving a file
1.253 + * This is used as base for relativizing link and image urls
1.254 + */
1.255 + void updateBaseURL();
1.256 +
1.257 +
1.258 + /* ------------ Selection manipulation -------------- */
1.259 + /* Should these be moved to nsISelection? */
1.260 +
1.261 + /**
1.262 + * Set the selection at the suppled element
1.263 + *
1.264 + * @param aElement An element in the document
1.265 + */
1.266 + void selectElement(in nsIDOMElement aElement);
1.267 +
1.268 + /**
1.269 + * Create a collapsed selection just after aElement
1.270 + *
1.271 + * XXX could we parameterize SelectElement(before/select/after>?
1.272 + *
1.273 + * The selection is set to parent-of-aElement with an
1.274 + * offset 1 greater than aElement's offset
1.275 + * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
1.276 + * be useful for other elements.
1.277 + *
1.278 + * @param aElement An element in the document
1.279 + */
1.280 + void setCaretAfterElement(in nsIDOMElement aElement);
1.281 +
1.282 + /**
1.283 + * SetParagraphFormat Insert a block paragraph tag around selection
1.284 + * @param aParagraphFormat "p", "h1" to "h6", "address", "pre", or "blockquote"
1.285 + */
1.286 + void setParagraphFormat(in AString aParagraphFormat);
1.287 +
1.288 + /**
1.289 + * getParagraphState returns what block tag paragraph format is in
1.290 + * the selection.
1.291 + * @param aMixed True if there is more than one format
1.292 + * @return Name of block tag. "" is returned for none.
1.293 + */
1.294 + AString getParagraphState(out boolean aMixed);
1.295 +
1.296 + /**
1.297 + * getFontFaceState returns what font face is in the selection.
1.298 + * @param aMixed True if there is more than one font face
1.299 + * @return Name of face. Note: "tt" is returned for
1.300 + * tt tag. "" is returned for none.
1.301 + */
1.302 + AString getFontFaceState(out boolean aMixed);
1.303 +
1.304 + /**
1.305 + * getFontColorState returns what font face is in the selection.
1.306 + * @param aMixed True if there is more than one font color
1.307 + * @return Color string. "" is returned for none.
1.308 + */
1.309 + AString getFontColorState(out boolean aMixed);
1.310 +
1.311 + /**
1.312 + * getFontColorState returns what font face is in the selection.
1.313 + * @param aMixed True if there is more than one font color
1.314 + * @return Color string. "" is returned for none.
1.315 + */
1.316 + AString getBackgroundColorState(out boolean aMixed);
1.317 +
1.318 + /**
1.319 + * getHighlightColorState returns what the highlight color of the selection.
1.320 + * @param aMixed True if there is more than one font color
1.321 + * @return Color string. "" is returned for none.
1.322 + */
1.323 + AString getHighlightColorState(out boolean aMixed);
1.324 +
1.325 + /**
1.326 + * getListState returns what list type is in the selection.
1.327 + * @param aMixed True if there is more than one type of list, or
1.328 + * if there is some list and non-list
1.329 + * @param aOL The company that employs me. No, really, it's
1.330 + * true if an "ol" list is selected.
1.331 + * @param aUL true if an "ul" list is selected.
1.332 + * @param aDL true if a "dl" list is selected.
1.333 + */
1.334 + void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
1.335 + out boolean aDL);
1.336 +
1.337 + /**
1.338 + * getListItemState returns what list item type is in the selection.
1.339 + * @param aMixed True if there is more than one type of list item, or
1.340 + * if there is some list and non-list
1.341 + * @param aLI true if "li" list items are selected.
1.342 + * @param aDT true if "dt" list items are selected.
1.343 + * @param aDD true if "dd" list items are selected.
1.344 + */
1.345 + void getListItemState(out boolean aMixed, out boolean aLI,
1.346 + out boolean aDT, out boolean aDD);
1.347 +
1.348 + /**
1.349 + * getAlignment returns what alignment is in the selection.
1.350 + * @param aMixed True if there is more than one type of list item, or
1.351 + * if there is some list and non-list
1.352 + * @param aAlign enum value for first encountered alignment
1.353 + * (left/center/right)
1.354 + */
1.355 + void getAlignment(out boolean aMixed, out short aAlign);
1.356 +
1.357 + /**
1.358 + * Document me!
1.359 + *
1.360 + */
1.361 + void getIndentState(out boolean aCanIndent, out boolean aCanOutdent);
1.362 +
1.363 + /**
1.364 + * Document me!
1.365 + *
1.366 + */
1.367 + void makeOrChangeList(in AString aListType, in boolean entireList,
1.368 + in AString aBulletType);
1.369 +
1.370 + /**
1.371 + * Document me!
1.372 + *
1.373 + */
1.374 + void removeList(in AString aListType);
1.375 +
1.376 + /**
1.377 + * Document me!
1.378 + *
1.379 + */
1.380 + void indent(in AString aIndent);
1.381 +
1.382 + /**
1.383 + * Document me!
1.384 + *
1.385 + */
1.386 + void align(in AString aAlign);
1.387 +
1.388 + /**
1.389 + * Return the input node or a parent matching the given aTagName,
1.390 + * starting the search at the supplied node.
1.391 + * An example of use is for testing if a node is in a table cell
1.392 + * given a selection anchor node.
1.393 + *
1.394 + * @param aTagName The HTML tagname
1.395 + * Special input values:
1.396 + * Use "href" to get a link node
1.397 + * (an "A" tag with the "href" attribute set)
1.398 + * Use "anchor" or "namedanchor" to get a named anchor node
1.399 + * (an "A" tag with the "name" attribute set)
1.400 + * Use "list" to get an OL, UL, or DL list node
1.401 + * Use "td" to get either a TD or TH cell node
1.402 + *
1.403 + * @param aNode The node in the document to start the search.
1.404 + * If it is null, the anchor node of the current selection is used.
1.405 + * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.406 + * (passes NS_SUCCEEDED macro)
1.407 + */
1.408 + nsIDOMElement getElementOrParentByTagName(in AString aTagName,
1.409 + in nsIDOMNode aNode);
1.410 +
1.411 + /**
1.412 + * Return an element only if it is the only node selected,
1.413 + * such as an image, horizontal rule, etc.
1.414 + * The exception is a link, which is more like a text attribute:
1.415 + * The Anchor tag is returned if the selection is within the textnode(s)
1.416 + * that are children of the "A" node.
1.417 + * This could be a collapsed selection, i.e., a caret
1.418 + * within the link text.
1.419 + *
1.420 + * @param aTagName The HTML tagname or and empty string
1.421 + * to get any element (but only if it is the only element selected)
1.422 + * Special input values for Links and Named anchors:
1.423 + * Use "href" to get a link node
1.424 + * (an "A" tag with the "href" attribute set)
1.425 + * Use "anchor" or "namedanchor" to get a named anchor node
1.426 + * (an "A" tag with the "name" attribute set)
1.427 + * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
1.428 + * (passes NS_SUCCEEDED macro)
1.429 + */
1.430 + nsIDOMElement getSelectedElement(in AString aTagName);
1.431 +
1.432 + /**
1.433 + * Output the contents of the <HEAD> section as text/HTML format
1.434 + */
1.435 + AString getHeadContentsAsHTML();
1.436 +
1.437 + /**
1.438 + * Replace all children of <HEAD> with string of HTML source
1.439 + */
1.440 + void replaceHeadContentsWithHTML(in AString aSourceToInsert);
1.441 +
1.442 + /**
1.443 + * Return a new element with default attribute values
1.444 + *
1.445 + * This does not rely on the selection, and is not sensitive to context.
1.446 + *
1.447 + * Used primarily to supply new element for various insert element dialogs
1.448 + * (Image, Link, NamedAnchor, Table, and HorizontalRule
1.449 + * are the only returned elements as of 7/25/99)
1.450 + *
1.451 + * @param aTagName The HTML tagname
1.452 + * Special input values for Links and Named anchors:
1.453 + * Use "href" to get a link node
1.454 + * (an "A" tag with the "href" attribute set)
1.455 + * Use "anchor" or "namedanchor" to get a named anchor node
1.456 + * (an "A" tag with the "name" attribute set)
1.457 + * @return The new element created.
1.458 + */
1.459 + nsIDOMElement createElementWithDefaults(in AString aTagName);
1.460 +
1.461 + /**
1.462 + * Insert an link element as the parent of the current selection
1.463 + *
1.464 + * @param aElement An "A" element with a non-empty "href" attribute
1.465 + */
1.466 + void insertLinkAroundSelection(in nsIDOMElement aAnchorElement);
1.467 +
1.468 + /**
1.469 + * Set the value of the "bgcolor" attribute on the document's <body> element
1.470 + *
1.471 + * @param aColor The HTML color string, such as "#ffccff" or "yellow"
1.472 + */
1.473 + void setBackgroundColor(in AString aColor);
1.474 +
1.475 +
1.476 + /**
1.477 + * Set an attribute on the document's <body> element
1.478 + * such as text, link, background colors
1.479 + *
1.480 + * 8/31/00 THIS ISN'T BEING USED? SHOULD WE DROP IT?
1.481 + *
1.482 + * @param aAttr The attribute to be set
1.483 + * @param aValue The value of the attribute
1.484 + */
1.485 + void setBodyAttribute(in AString aAttr, in AString aValue);
1.486 +
1.487 + /**
1.488 + * Find all the nodes in the document which contain references
1.489 + * to outside URIs (e.g. a href, img src, script src, etc.)
1.490 + * The objects in the array will be type nsIURIRefObject.
1.491 + *
1.492 + * @return aNodeList the linked nodes found
1.493 + */
1.494 + nsISupportsArray getLinkedObjects();
1.495 +
1.496 + /**
1.497 + * A boolean which is true is the HTMLEditor has been instantiated
1.498 + * with CSS knowledge and if the CSS pref is currently checked
1.499 + *
1.500 + * @return true if CSS handled and enabled
1.501 + */
1.502 + attribute boolean isCSSEnabled;
1.503 +
1.504 + /**
1.505 + * Add listener for insertion override
1.506 + * @param inFilter function which callers want called during insertion
1.507 + */
1.508 + void addInsertionListener(in nsIContentFilter inFilter);
1.509 +
1.510 + /**
1.511 + * Remove listener for insertion override
1.512 + * @param inFilter function which callers do not want called during insertion
1.513 + */
1.514 + void removeInsertionListener(in nsIContentFilter inFilter);
1.515 +
1.516 + /**
1.517 + * Returns an anonymous nsDOMElement of type aTag,
1.518 + * child of aParentNode. If aIsCreatedHidden is true, the class
1.519 + * "hidden" is added to the created element. If aAnonClass is not
1.520 + * the empty string, it becomes the value of the attribute "_moz_anonclass"
1.521 + * @return a DOM Element
1.522 + * @param aTag [IN] a string representing the desired type of
1.523 + * the element to create
1.524 + * @param aParentNode [IN] the parent node of the created anonymous
1.525 + * element
1.526 + * @param aAnonClass [IN] contents of the _moz_anonclass attribute
1.527 + * @param aIsCreatedHidden [IN] a boolean specifying if the class "hidden"
1.528 + * is to be added to the created anonymous
1.529 + * element
1.530 + */
1.531 + nsIDOMElement createAnonymousElement(in AString aTag, in nsIDOMNode aParentNode,
1.532 + in AString aAnonClass, in boolean aIsCreatedHidden);
1.533 +
1.534 + /**
1.535 + * returns the deepest container of the selection
1.536 + * @return a DOM Element
1.537 + */
1.538 + nsIDOMElement getSelectionContainer();
1.539 +
1.540 + /**
1.541 + * Checks if the anonymous nodes created by the HTML editor have to be
1.542 + * refreshed or hidden depending on a possible new state of the selection
1.543 + * @param aSelection [IN] a selection
1.544 + */
1.545 + void checkSelectionStateForAnonymousButtons(in nsISelection aSelection);
1.546 +
1.547 + boolean isAnonymousElement(in nsIDOMElement aElement);
1.548 +
1.549 + /**
1.550 + * A boolean indicating if a return key pressed in a paragraph creates
1.551 + * another paragraph or just inserts a <br> at the caret
1.552 + *
1.553 + * @return true if CR in a paragraph creates a new paragraph
1.554 + */
1.555 + attribute boolean returnInParagraphCreatesNewParagraph;
1.556 +
1.557 + /**
1.558 + * Checks whether a BR node is visible to the user.
1.559 + */
1.560 + boolean breakIsVisible(in nsIDOMNode aNode);
1.561 +
1.562 + /**
1.563 + * Get an active editor's editing host in DOM window. If this editor isn't
1.564 + * active in the DOM window, this returns NULL.
1.565 + */
1.566 + [noscript, notxpcom] Element GetActiveEditingHost();
1.567 +};
1.568 +
