1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include
"nsISupports.idl"
7 #include
"domstubs.idl"
11 interface nsISupportsArray
;
12 interface nsISelection
;
13 interface nsIContentFilter
;
23 [ptr] native Element
(mozilla
::dom
::Element
);
25 [scriptable
, uuid(87ee993e
-985f
-4a43
-a974
-0d9512da2fb0
)]
26 interface nsIHTMLEditor
: nsISupports
29 typedef short EAlignment
;
32 // used by GetAlignment()
33 const short eLeft
= 0;
34 const short eCenter
= 1;
35 const short eRight
= 2;
36 const short eJustify
= 3;
39 /* ------------ Inline property methods -------------- */
43 * AddDefaultProperty() registers a default style property with the editor
45 * @param aProperty the property to set by default
46 * @param aAttribute the attribute of the property, if applicable.
48 * Example: aProperty="font", aAttribute="color"
49 * @param aValue if aAttribute is not null, the value of the attribute.
50 * Example: aProperty="font", aAttribute="color",
53 void addDefaultProperty
(in nsIAtom aProperty
,
54 in AString aAttribute
,
58 * RemoveDefaultProperty() unregisters a default style property with the editor
60 * @param aProperty the property to remove from defaults
61 * @param aAttribute the attribute of the property, if applicable.
63 * Example: aProperty="font", aAttribute="color"
64 * @param aValue if aAttribute is not null, the value of the attribute.
65 * Example: aProperty="font", aAttribute="color",
68 void removeDefaultProperty
(in nsIAtom aProperty
,
69 in AString aAttribute
,
73 * RemoveAllDefaultProperties() unregisters all default style properties with the editor
76 void removeAllDefaultProperties
();
79 * SetInlineProperty() sets the aggregate properties on the current selection
81 * @param aProperty the property to set on the selection
82 * @param aAttribute the attribute of the property, if applicable.
84 * Example: aProperty="font", aAttribute="color"
85 * @param aValue if aAttribute is not null, the value of the attribute.
87 * Example: aProperty="font", aAttribute="color",
90 void setInlineProperty
(in nsIAtom aProperty
,
91 in AString aAttribute
,
95 * getInlineProperty() gets aggregate properties of the current selection.
96 * All object in the current selection are scanned and their attributes are
97 * represented in a list of Property object.
99 * @param aProperty the property to get on the selection
100 * @param aAttribute the attribute of the property, if applicable.
102 * Example: aProperty="font", aAttribute="color"
103 * @param aValue if aAttribute is not null, the value of the attribute.
105 * Example: aProperty="font", aAttribute="color",
107 * @param aFirst [OUT] PR_TRUE if the first text node in the
108 * selection has the property
109 * @param aAny [OUT] PR_TRUE if any of the text nodes in the
110 * selection have the property
111 * @param aAll [OUT] PR_TRUE if all of the text nodes in the
112 * selection have the property
114 void getInlineProperty
(in nsIAtom aProperty
,
115 in AString aAttribute
,
121 AString getInlinePropertyWithAttrValue
(in nsIAtom aProperty
,
122 in AString aAttribute
,
129 * removeAllInlineProperties() deletes all the inline properties from all
130 * text in the current selection.
132 void removeAllInlineProperties
();
136 * removeInlineProperty() deletes the properties from all text in the current
137 * selection. If aProperty is not set on the selection, nothing is done.
139 * @param aProperty the property to remove from the selection
140 * All atoms are for normal HTML tags (e.g.:
141 * nsIEditorProperty::font) except when you want to
142 * remove just links and not named anchors.
143 * For that, use nsIEditorProperty::href
144 * @param aAttribute the attribute of the property, if applicable.
146 * Example: aProperty=nsIEditorProptery::font,
148 * nsIEditProperty::allAttributes is special.
149 * It indicates that all content-based text properties
150 * are to be removed from the selection.
152 void removeInlineProperty
(in nsIAtom aProperty
, in AString aAttribute
);
155 * Increase font size for text in selection by 1 HTML unit
156 * All existing text is scanned for existing <FONT SIZE> attributes
157 * so they will be incremented instead of inserting new <FONT> tag
159 void increaseFontSize
();
162 * Decrease font size for text in selection by 1 HTML unit
163 * All existing text is scanned for existing <FONT SIZE> attributes
164 * so they will be decreased instead of inserting new <FONT> tag
166 void decreaseFontSize
();
168 /* ------------ HTML content methods -------------- */
171 * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
172 * This does NOT consider CSS effect on display type
174 * @param aNode the node to test
176 boolean nodeIsBlock
(in nsIDOMNode node
);
179 * Insert some HTML source at the current location
181 * @param aInputString the string to be inserted
183 void insertHTML
(in AString aInputString
);
187 * Paste the text in the OS clipboard at the cursor position, replacing
188 * the selected text (if any), but strip out any HTML styles and formatting
190 void pasteNoFormatting
(in long aSelectionType
);
193 * Rebuild the entire document from source HTML
194 * Needed to be able to edit HEAD and other outside-of-BODY content
196 * @param aSourceString HTML source string of the entire new document
198 void rebuildDocumentFromSource
(in AString aSourceString
);
201 * Insert some HTML source, interpreting
202 * the string argument according to the given context.
204 * @param aInputString the string to be inserted
205 * @param aContextStr Context of insertion
206 * @param aInfoStr Related info to aInputString
207 * @param aFlavor Transferable flavor, can be ""
208 * @param aSourceDoc document where input was dragged from (may be null)
209 * @param aDestinationNode location for insertion (such as when dropped)
210 * @param aDestinationOffset used with aDestNode to determine insert location
211 * @param aDeleteSelection used with aDestNode during drag&drop
212 * @param aCollapseSelection used with aDestNode during drag&drop
214 void insertHTMLWithContext
(in AString aInputString
,
215 in AString aContextStr
,
218 in nsIDOMDocument aSourceDoc
,
219 in nsIDOMNode aDestinationNode
,
220 in long aDestinationOffset
,
221 in boolean aDeleteSelection
);
225 * Insert an element, which may have child nodes, at the selection
226 * Used primarily to insert a new element for various insert element dialogs,
227 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
228 * be useful for other elements.
230 * @param aElement The element to insert
231 * @param aDeleteSelection Delete the selection before inserting
232 * If aDeleteSelection is PR_FALSE, then the element is inserted
233 * after the end of the selection for all element except
234 * Named Anchors, which insert before the selection
236 void insertElementAtSelection
(in nsIDOMElement aElement
,
237 in boolean aDeleteSelection
);
240 * Set the documents title.
242 void setDocumentTitle
(in AString aTitle
);
245 * Set the BaseURL for the document to the current URL
246 * but only if the page doesn't have a <base> tag
247 * This should be done after the document URL has changed,
248 * such as after saving a file
249 * This is used as base for relativizing link and image urls
251 void updateBaseURL
();
254 /* ------------ Selection manipulation -------------- */
255 /* Should these be moved to nsISelection? */
258 * Set the selection at the suppled element
260 * @param aElement An element in the document
262 void selectElement
(in nsIDOMElement aElement
);
265 * Create a collapsed selection just after aElement
267 * XXX could we parameterize SelectElement(before/select/after>?
269 * The selection is set to parent-of-aElement with an
270 * offset 1 greater than aElement's offset
271 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
272 * be useful for other elements.
274 * @param aElement An element in the document
276 void setCaretAfterElement
(in nsIDOMElement aElement
);
279 * SetParagraphFormat Insert a block paragraph tag around selection
280 * @param aParagraphFormat "p", "h1" to "h6", "address", "pre", or "blockquote"
282 void setParagraphFormat
(in AString aParagraphFormat
);
285 * getParagraphState returns what block tag paragraph format is in
287 * @param aMixed True if there is more than one format
288 * @return Name of block tag. "" is returned for none.
290 AString getParagraphState
(out boolean aMixed
);
293 * getFontFaceState returns what font face is in the selection.
294 * @param aMixed True if there is more than one font face
295 * @return Name of face. Note: "tt" is returned for
296 * tt tag. "" is returned for none.
298 AString getFontFaceState
(out boolean aMixed
);
301 * getFontColorState returns what font face is in the selection.
302 * @param aMixed True if there is more than one font color
303 * @return Color string. "" is returned for none.
305 AString getFontColorState
(out boolean aMixed
);
308 * getFontColorState returns what font face is in the selection.
309 * @param aMixed True if there is more than one font color
310 * @return Color string. "" is returned for none.
312 AString getBackgroundColorState
(out boolean aMixed
);
315 * getHighlightColorState returns what the highlight color of the selection.
316 * @param aMixed True if there is more than one font color
317 * @return Color string. "" is returned for none.
319 AString getHighlightColorState
(out boolean aMixed
);
322 * getListState returns what list type is in the selection.
323 * @param aMixed True if there is more than one type of list, or
324 * if there is some list and non-list
325 * @param aOL The company that employs me. No, really, it's
326 * true if an "ol" list is selected.
327 * @param aUL true if an "ul" list is selected.
328 * @param aDL true if a "dl" list is selected.
330 void getListState
(out boolean aMixed
, out boolean aOL
, out boolean aUL
,
334 * getListItemState returns what list item type is in the selection.
335 * @param aMixed True if there is more than one type of list item, or
336 * if there is some list and non-list
337 * @param aLI true if "li" list items are selected.
338 * @param aDT true if "dt" list items are selected.
339 * @param aDD true if "dd" list items are selected.
341 void getListItemState
(out boolean aMixed
, out boolean aLI
,
342 out boolean aDT
, out boolean aDD
);
345 * getAlignment returns what alignment is in the selection.
346 * @param aMixed True if there is more than one type of list item, or
347 * if there is some list and non-list
348 * @param aAlign enum value for first encountered alignment
349 * (left/center/right)
351 void getAlignment
(out boolean aMixed
, out short aAlign
);
357 void getIndentState
(out boolean aCanIndent
, out boolean aCanOutdent
);
363 void makeOrChangeList
(in AString aListType
, in boolean entireList
,
364 in AString aBulletType
);
370 void removeList
(in AString aListType
);
376 void indent
(in AString aIndent
);
382 void align
(in AString aAlign
);
385 * Return the input node or a parent matching the given aTagName,
386 * starting the search at the supplied node.
387 * An example of use is for testing if a node is in a table cell
388 * given a selection anchor node.
390 * @param aTagName The HTML tagname
391 * Special input values:
392 * Use "href" to get a link node
393 * (an "A" tag with the "href" attribute set)
394 * Use "anchor" or "namedanchor" to get a named anchor node
395 * (an "A" tag with the "name" attribute set)
396 * Use "list" to get an OL, UL, or DL list node
397 * Use "td" to get either a TD or TH cell node
399 * @param aNode The node in the document to start the search.
400 * If it is null, the anchor node of the current selection is used.
401 * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
402 * (passes NS_SUCCEEDED macro)
404 nsIDOMElement getElementOrParentByTagName
(in AString aTagName
,
405 in nsIDOMNode aNode
);
408 * Return an element only if it is the only node selected,
409 * such as an image, horizontal rule, etc.
410 * The exception is a link, which is more like a text attribute:
411 * The Anchor tag is returned if the selection is within the textnode(s)
412 * that are children of the "A" node.
413 * This could be a collapsed selection, i.e., a caret
414 * within the link text.
416 * @param aTagName The HTML tagname or and empty string
417 * to get any element (but only if it is the only element selected)
418 * Special input values for Links and Named anchors:
419 * Use "href" to get a link node
420 * (an "A" tag with the "href" attribute set)
421 * Use "anchor" or "namedanchor" to get a named anchor node
422 * (an "A" tag with the "name" attribute set)
423 * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
424 * (passes NS_SUCCEEDED macro)
426 nsIDOMElement getSelectedElement
(in AString aTagName
);
429 * Output the contents of the <HEAD> section as text/HTML format
431 AString getHeadContentsAsHTML
();
434 * Replace all children of <HEAD> with string of HTML source
436 void replaceHeadContentsWithHTML
(in AString aSourceToInsert
);
439 * Return a new element with default attribute values
441 * This does not rely on the selection, and is not sensitive to context.
443 * Used primarily to supply new element for various insert element dialogs
444 * (Image, Link, NamedAnchor, Table, and HorizontalRule
445 * are the only returned elements as of 7/25/99)
447 * @param aTagName The HTML tagname
448 * Special input values for Links and Named anchors:
449 * Use "href" to get a link node
450 * (an "A" tag with the "href" attribute set)
451 * Use "anchor" or "namedanchor" to get a named anchor node
452 * (an "A" tag with the "name" attribute set)
453 * @return The new element created.
455 nsIDOMElement createElementWithDefaults
(in AString aTagName
);
458 * Insert an link element as the parent of the current selection
460 * @param aElement An "A" element with a non-empty "href" attribute
462 void insertLinkAroundSelection
(in nsIDOMElement aAnchorElement
);
465 * Set the value of the "bgcolor" attribute on the document's <body> element
467 * @param aColor The HTML color string, such as "#ffccff" or "yellow"
469 void setBackgroundColor
(in AString aColor
);
473 * Set an attribute on the document's <body> element
474 * such as text, link, background colors
476 * 8/31/00 THIS ISN'T BEING USED? SHOULD WE DROP IT?
478 * @param aAttr The attribute to be set
479 * @param aValue The value of the attribute
481 void setBodyAttribute
(in AString aAttr
, in AString aValue
);
484 * Find all the nodes in the document which contain references
485 * to outside URIs (e.g. a href, img src, script src, etc.)
486 * The objects in the array will be type nsIURIRefObject.
488 * @return aNodeList the linked nodes found
490 nsISupportsArray getLinkedObjects
();
493 * A boolean which is true is the HTMLEditor has been instantiated
494 * with CSS knowledge and if the CSS pref is currently checked
496 * @return true if CSS handled and enabled
498 attribute
boolean isCSSEnabled
;
501 * Add listener for insertion override
502 * @param inFilter function which callers want called during insertion
504 void addInsertionListener
(in nsIContentFilter inFilter
);
507 * Remove listener for insertion override
508 * @param inFilter function which callers do not want called during insertion
510 void removeInsertionListener
(in nsIContentFilter inFilter
);
513 * Returns an anonymous nsDOMElement of type aTag,
514 * child of aParentNode. If aIsCreatedHidden is true, the class
515 * "hidden" is added to the created element. If aAnonClass is not
516 * the empty string, it becomes the value of the attribute "_moz_anonclass"
517 * @return a DOM Element
518 * @param aTag [IN] a string representing the desired type of
519 * the element to create
520 * @param aParentNode [IN] the parent node of the created anonymous
522 * @param aAnonClass [IN] contents of the _moz_anonclass attribute
523 * @param aIsCreatedHidden [IN] a boolean specifying if the class "hidden"
524 * is to be added to the created anonymous
527 nsIDOMElement createAnonymousElement
(in AString aTag
, in nsIDOMNode aParentNode
,
528 in AString aAnonClass
, in boolean aIsCreatedHidden
);
531 * returns the deepest container of the selection
532 * @return a DOM Element
534 nsIDOMElement getSelectionContainer
();
537 * Checks if the anonymous nodes created by the HTML editor have to be
538 * refreshed or hidden depending on a possible new state of the selection
539 * @param aSelection [IN] a selection
541 void checkSelectionStateForAnonymousButtons
(in nsISelection aSelection
);
543 boolean isAnonymousElement
(in nsIDOMElement aElement
);
546 * A boolean indicating if a return key pressed in a paragraph creates
547 * another paragraph or just inserts a <br> at the caret
549 * @return true if CR in a paragraph creates a new paragraph
551 attribute
boolean returnInParagraphCreatesNewParagraph
;
554 * Get an active editor's editing host in DOM window. If this editor isn't
555 * active in the DOM window, this returns NULL.
557 [noscript
, notxpcom
] Element GetActiveEditingHost
();