editor/idl/nsIHTMLEditor.idl@6474c204b198
editor/idl/nsIHTMLEditor.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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"
9 interface nsIAtom;
10 interface nsIContent;
11 interface nsISupportsArray;
12 interface nsISelection;
13 interface nsIContentFilter;
15 %{C++
16 namespace mozilla {
17 namespace dom {
18 class Element;
19 }
20 }
21 %}
23 [ptr] native Element (mozilla::dom::Element);
25 [scriptable, uuid(833f30de-94c7-4630-a852-2300ef329d7b)]
27 interface nsIHTMLEditor : nsISupports
28 {
29 %{C++
30 typedef short EAlignment;
31 %}
33 // used by GetAlignment()
34 const short eLeft = 0;
35 const short eCenter = 1;
36 const short eRight = 2;
37 const short eJustify = 3;
40 /* ------------ Inline property methods -------------- */
43 /**
44 * AddDefaultProperty() registers a default style property with the editor
45 *
46 * @param aProperty the property to set by default
47 * @param aAttribute the attribute of the property, if applicable.
48 * May be null.
49 * Example: aProperty="font", aAttribute="color"
50 * @param aValue if aAttribute is not null, the value of the attribute.
51 * Example: aProperty="font", aAttribute="color",
52 * aValue="0x00FFFF"
53 */
54 void addDefaultProperty(in nsIAtom aProperty,
55 in AString aAttribute,
56 in AString aValue);
58 /**
59 * RemoveDefaultProperty() unregisters a default style property with the editor
60 *
61 * @param aProperty the property to remove from defaults
62 * @param aAttribute the attribute of the property, if applicable.
63 * May be null.
64 * Example: aProperty="font", aAttribute="color"
65 * @param aValue if aAttribute is not null, the value of the attribute.
66 * Example: aProperty="font", aAttribute="color",
67 * aValue="0x00FFFF"
68 */
69 void removeDefaultProperty(in nsIAtom aProperty,
70 in AString aAttribute,
71 in AString aValue);
73 /**
74 * RemoveAllDefaultProperties() unregisters all default style properties with the editor
75 *
76 */
77 void removeAllDefaultProperties();
79 /**
80 * SetInlineProperty() sets the aggregate properties on the current selection
81 *
82 * @param aProperty the property to set on the selection
83 * @param aAttribute the attribute of the property, if applicable.
84 * May be null.
85 * Example: aProperty="font", aAttribute="color"
86 * @param aValue if aAttribute is not null, the value of the attribute.
87 * May be null.
88 * Example: aProperty="font", aAttribute="color",
89 * aValue="0x00FFFF"
90 */
91 void setInlineProperty(in nsIAtom aProperty,
92 in AString aAttribute,
93 in AString aValue);
95 /**
96 * getInlineProperty() gets aggregate properties of the current selection.
97 * All object in the current selection are scanned and their attributes are
98 * represented in a list of Property object.
99 *
100 * @param aProperty the property to get on the selection
101 * @param aAttribute the attribute of the property, if applicable.
102 * May be null.
103 * Example: aProperty="font", aAttribute="color"
104 * @param aValue if aAttribute is not null, the value of the attribute.
105 * May be null.
106 * Example: aProperty="font", aAttribute="color",
107 * aValue="0x00FFFF"
108 * @param aFirst [OUT] PR_TRUE if the first text node in the
109 * selection has the property
110 * @param aAny [OUT] PR_TRUE if any of the text nodes in the
111 * selection have the property
112 * @param aAll [OUT] PR_TRUE if all of the text nodes in the
113 * selection have the property
114 */
115 void getInlineProperty(in nsIAtom aProperty,
116 in AString aAttribute,
117 in AString aValue,
118 out boolean aFirst,
119 out boolean aAny,
120 out boolean aAll);
122 AString getInlinePropertyWithAttrValue(in nsIAtom aProperty,
123 in AString aAttribute,
124 in AString aValue,
125 out boolean aFirst,
126 out boolean aAny,
127 out boolean aAll);
129 /**
130 * removeAllInlineProperties() deletes all the inline properties from all
131 * text in the current selection.
132 */
133 void removeAllInlineProperties();
136 /**
137 * removeInlineProperty() deletes the properties from all text in the current
138 * selection. If aProperty is not set on the selection, nothing is done.
139 *
140 * @param aProperty the property to remove from the selection
141 * All atoms are for normal HTML tags (e.g.:
142 * nsIEditorProperty::font) except when you want to
143 * remove just links and not named anchors.
144 * For that, use nsIEditorProperty::href
145 * @param aAttribute the attribute of the property, if applicable.
146 * May be null.
147 * Example: aProperty=nsIEditorProptery::font,
148 * aAttribute="color"
149 * nsIEditProperty::allAttributes is special.
150 * It indicates that all content-based text properties
151 * are to be removed from the selection.
152 */
153 void removeInlineProperty(in nsIAtom aProperty, in AString aAttribute);
155 /**
156 * Increase font size for text in selection by 1 HTML unit
157 * All existing text is scanned for existing <FONT SIZE> attributes
158 * so they will be incremented instead of inserting new <FONT> tag
159 */
160 void increaseFontSize();
162 /**
163 * Decrease font size for text in selection by 1 HTML unit
164 * All existing text is scanned for existing <FONT SIZE> attributes
165 * so they will be decreased instead of inserting new <FONT> tag
166 */
167 void decreaseFontSize();
169 /* ------------ HTML content methods -------------- */
171 /**
172 * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
173 * This does NOT consider CSS effect on display type
174 *
175 * @param aNode the node to test
176 */
177 boolean nodeIsBlock(in nsIDOMNode node);
179 /**
180 * Insert some HTML source at the current location
181 *
182 * @param aInputString the string to be inserted
183 */
184 void insertHTML(in AString aInputString);
187 /**
188 * Paste the text in the OS clipboard at the cursor position, replacing
189 * the selected text (if any), but strip out any HTML styles and formatting
190 */
191 void pasteNoFormatting(in long aSelectionType);
193 /**
194 * Rebuild the entire document from source HTML
195 * Needed to be able to edit HEAD and other outside-of-BODY content
196 *
197 * @param aSourceString HTML source string of the entire new document
198 */
199 void rebuildDocumentFromSource(in AString aSourceString);
201 /**
202 * Insert some HTML source, interpreting
203 * the string argument according to the given context.
204 *
205 * @param aInputString the string to be inserted
206 * @param aContextStr Context of insertion
207 * @param aInfoStr Related info to aInputString
208 * @param aFlavor Transferable flavor, can be ""
209 * @param aSourceDoc document where input was dragged from (may be null)
210 * @param aDestinationNode location for insertion (such as when dropped)
211 * @param aDestinationOffset used with aDestNode to determine insert location
212 * @param aDeleteSelection used with aDestNode during drag&drop
213 * @param aCollapseSelection used with aDestNode during drag&drop
214 */
215 void insertHTMLWithContext(in AString aInputString,
216 in AString aContextStr,
217 in AString aInfoStr,
218 in AString aFlavor,
219 in nsIDOMDocument aSourceDoc,
220 in nsIDOMNode aDestinationNode,
221 in long aDestinationOffset,
222 in boolean aDeleteSelection);
225 /**
226 * Insert an element, which may have child nodes, at the selection
227 * Used primarily to insert a new element for various insert element dialogs,
228 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
229 * be useful for other elements.
230 *
231 * @param aElement The element to insert
232 * @param aDeleteSelection Delete the selection before inserting
233 * If aDeleteSelection is PR_FALSE, then the element is inserted
234 * after the end of the selection for all element except
235 * Named Anchors, which insert before the selection
236 */
237 void insertElementAtSelection(in nsIDOMElement aElement,
238 in boolean aDeleteSelection);
240 /**
241 * Set the documents title.
242 */
243 void setDocumentTitle(in AString aTitle);
245 /**
246 * Set the BaseURL for the document to the current URL
247 * but only if the page doesn't have a <base> tag
248 * This should be done after the document URL has changed,
249 * such as after saving a file
250 * This is used as base for relativizing link and image urls
251 */
252 void updateBaseURL();
255 /* ------------ Selection manipulation -------------- */
256 /* Should these be moved to nsISelection? */
258 /**
259 * Set the selection at the suppled element
260 *
261 * @param aElement An element in the document
262 */
263 void selectElement(in nsIDOMElement aElement);
265 /**
266 * Create a collapsed selection just after aElement
267 *
268 * XXX could we parameterize SelectElement(before/select/after>?
269 *
270 * The selection is set to parent-of-aElement with an
271 * offset 1 greater than aElement's offset
272 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
273 * be useful for other elements.
274 *
275 * @param aElement An element in the document
276 */
277 void setCaretAfterElement(in nsIDOMElement aElement);
279 /**
280 * SetParagraphFormat Insert a block paragraph tag around selection
281 * @param aParagraphFormat "p", "h1" to "h6", "address", "pre", or "blockquote"
282 */
283 void setParagraphFormat(in AString aParagraphFormat);
285 /**
286 * getParagraphState returns what block tag paragraph format is in
287 * the selection.
288 * @param aMixed True if there is more than one format
289 * @return Name of block tag. "" is returned for none.
290 */
291 AString getParagraphState(out boolean aMixed);
293 /**
294 * getFontFaceState returns what font face is in the selection.
295 * @param aMixed True if there is more than one font face
296 * @return Name of face. Note: "tt" is returned for
297 * tt tag. "" is returned for none.
298 */
299 AString getFontFaceState(out boolean aMixed);
301 /**
302 * getFontColorState returns what font face is in the selection.
303 * @param aMixed True if there is more than one font color
304 * @return Color string. "" is returned for none.
305 */
306 AString getFontColorState(out boolean aMixed);
308 /**
309 * getFontColorState returns what font face is in the selection.
310 * @param aMixed True if there is more than one font color
311 * @return Color string. "" is returned for none.
312 */
313 AString getBackgroundColorState(out boolean aMixed);
315 /**
316 * getHighlightColorState returns what the highlight color of the selection.
317 * @param aMixed True if there is more than one font color
318 * @return Color string. "" is returned for none.
319 */
320 AString getHighlightColorState(out boolean aMixed);
322 /**
323 * getListState returns what list type is in the selection.
324 * @param aMixed True if there is more than one type of list, or
325 * if there is some list and non-list
326 * @param aOL The company that employs me. No, really, it's
327 * true if an "ol" list is selected.
328 * @param aUL true if an "ul" list is selected.
329 * @param aDL true if a "dl" list is selected.
330 */
331 void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
332 out boolean aDL);
334 /**
335 * getListItemState returns what list item type is in the selection.
336 * @param aMixed True if there is more than one type of list item, or
337 * if there is some list and non-list
338 * @param aLI true if "li" list items are selected.
339 * @param aDT true if "dt" list items are selected.
340 * @param aDD true if "dd" list items are selected.
341 */
342 void getListItemState(out boolean aMixed, out boolean aLI,
343 out boolean aDT, out boolean aDD);
345 /**
346 * getAlignment returns what alignment is in the selection.
347 * @param aMixed True if there is more than one type of list item, or
348 * if there is some list and non-list
349 * @param aAlign enum value for first encountered alignment
350 * (left/center/right)
351 */
352 void getAlignment(out boolean aMixed, out short aAlign);
354 /**
355 * Document me!
356 *
357 */
358 void getIndentState(out boolean aCanIndent, out boolean aCanOutdent);
360 /**
361 * Document me!
362 *
363 */
364 void makeOrChangeList(in AString aListType, in boolean entireList,
365 in AString aBulletType);
367 /**
368 * Document me!
369 *
370 */
371 void removeList(in AString aListType);
373 /**
374 * Document me!
375 *
376 */
377 void indent(in AString aIndent);
379 /**
380 * Document me!
381 *
382 */
383 void align(in AString aAlign);
385 /**
386 * Return the input node or a parent matching the given aTagName,
387 * starting the search at the supplied node.
388 * An example of use is for testing if a node is in a table cell
389 * given a selection anchor node.
390 *
391 * @param aTagName The HTML tagname
392 * Special input values:
393 * Use "href" to get a link node
394 * (an "A" tag with the "href" attribute set)
395 * Use "anchor" or "namedanchor" to get a named anchor node
396 * (an "A" tag with the "name" attribute set)
397 * Use "list" to get an OL, UL, or DL list node
398 * Use "td" to get either a TD or TH cell node
399 *
400 * @param aNode The node in the document to start the search.
401 * If it is null, the anchor node of the current selection is used.
402 * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
403 * (passes NS_SUCCEEDED macro)
404 */
405 nsIDOMElement getElementOrParentByTagName(in AString aTagName,
406 in nsIDOMNode aNode);
408 /**
409 * Return an element only if it is the only node selected,
410 * such as an image, horizontal rule, etc.
411 * The exception is a link, which is more like a text attribute:
412 * The Anchor tag is returned if the selection is within the textnode(s)
413 * that are children of the "A" node.
414 * This could be a collapsed selection, i.e., a caret
415 * within the link text.
416 *
417 * @param aTagName The HTML tagname or and empty string
418 * to get any element (but only if it is the only element selected)
419 * Special input values for Links and Named anchors:
420 * Use "href" to get a link node
421 * (an "A" tag with the "href" attribute set)
422 * Use "anchor" or "namedanchor" to get a named anchor node
423 * (an "A" tag with the "name" attribute set)
424 * @return NS_EDITOR_ELEMENT_NOT_FOUND if an element is not found
425 * (passes NS_SUCCEEDED macro)
426 */
427 nsIDOMElement getSelectedElement(in AString aTagName);
429 /**
430 * Output the contents of the <HEAD> section as text/HTML format
431 */
432 AString getHeadContentsAsHTML();
434 /**
435 * Replace all children of <HEAD> with string of HTML source
436 */
437 void replaceHeadContentsWithHTML(in AString aSourceToInsert);
439 /**
440 * Return a new element with default attribute values
441 *
442 * This does not rely on the selection, and is not sensitive to context.
443 *
444 * Used primarily to supply new element for various insert element dialogs
445 * (Image, Link, NamedAnchor, Table, and HorizontalRule
446 * are the only returned elements as of 7/25/99)
447 *
448 * @param aTagName The HTML tagname
449 * Special input values for Links and Named anchors:
450 * Use "href" to get a link node
451 * (an "A" tag with the "href" attribute set)
452 * Use "anchor" or "namedanchor" to get a named anchor node
453 * (an "A" tag with the "name" attribute set)
454 * @return The new element created.
455 */
456 nsIDOMElement createElementWithDefaults(in AString aTagName);
458 /**
459 * Insert an link element as the parent of the current selection
460 *
461 * @param aElement An "A" element with a non-empty "href" attribute
462 */
463 void insertLinkAroundSelection(in nsIDOMElement aAnchorElement);
465 /**
466 * Set the value of the "bgcolor" attribute on the document's <body> element
467 *
468 * @param aColor The HTML color string, such as "#ffccff" or "yellow"
469 */
470 void setBackgroundColor(in AString aColor);
473 /**
474 * Set an attribute on the document's <body> element
475 * such as text, link, background colors
476 *
477 * 8/31/00 THIS ISN'T BEING USED? SHOULD WE DROP IT?
478 *
479 * @param aAttr The attribute to be set
480 * @param aValue The value of the attribute
481 */
482 void setBodyAttribute(in AString aAttr, in AString aValue);
484 /**
485 * Find all the nodes in the document which contain references
486 * to outside URIs (e.g. a href, img src, script src, etc.)
487 * The objects in the array will be type nsIURIRefObject.
488 *
489 * @return aNodeList the linked nodes found
490 */
491 nsISupportsArray getLinkedObjects();
493 /**
494 * A boolean which is true is the HTMLEditor has been instantiated
495 * with CSS knowledge and if the CSS pref is currently checked
496 *
497 * @return true if CSS handled and enabled
498 */
499 attribute boolean isCSSEnabled;
501 /**
502 * Add listener for insertion override
503 * @param inFilter function which callers want called during insertion
504 */
505 void addInsertionListener(in nsIContentFilter inFilter);
507 /**
508 * Remove listener for insertion override
509 * @param inFilter function which callers do not want called during insertion
510 */
511 void removeInsertionListener(in nsIContentFilter inFilter);
513 /**
514 * Returns an anonymous nsDOMElement of type aTag,
515 * child of aParentNode. If aIsCreatedHidden is true, the class
516 * "hidden" is added to the created element. If aAnonClass is not
517 * the empty string, it becomes the value of the attribute "_moz_anonclass"
518 * @return a DOM Element
519 * @param aTag [IN] a string representing the desired type of
520 * the element to create
521 * @param aParentNode [IN] the parent node of the created anonymous
522 * element
523 * @param aAnonClass [IN] contents of the _moz_anonclass attribute
524 * @param aIsCreatedHidden [IN] a boolean specifying if the class "hidden"
525 * is to be added to the created anonymous
526 * element
527 */
528 nsIDOMElement createAnonymousElement(in AString aTag, in nsIDOMNode aParentNode,
529 in AString aAnonClass, in boolean aIsCreatedHidden);
531 /**
532 * returns the deepest container of the selection
533 * @return a DOM Element
534 */
535 nsIDOMElement getSelectionContainer();
537 /**
538 * Checks if the anonymous nodes created by the HTML editor have to be
539 * refreshed or hidden depending on a possible new state of the selection
540 * @param aSelection [IN] a selection
541 */
542 void checkSelectionStateForAnonymousButtons(in nsISelection aSelection);
544 boolean isAnonymousElement(in nsIDOMElement aElement);
546 /**
547 * A boolean indicating if a return key pressed in a paragraph creates
548 * another paragraph or just inserts a <br> at the caret
549 *
550 * @return true if CR in a paragraph creates a new paragraph
551 */
552 attribute boolean returnInParagraphCreatesNewParagraph;
554 /**
555 * Checks whether a BR node is visible to the user.
556 */
557 boolean breakIsVisible(in nsIDOMNode aNode);
559 /**
560 * Get an active editor's editing host in DOM window. If this editor isn't
561 * active in the DOM window, this returns NULL.
562 */
563 [noscript, notxpcom] Element GetActiveEditingHost();
564 };
