no bug - Import translations from android-l10n r=release a=l10n CLOSED TREE
[gecko.git] / editor / nsIHTMLEditor.idl
blob952d924c56410e8ddb17a2b6e270bceb97205d03
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 nsIContent;
11 webidl Document;
12 webidl Element;
13 webidl Node;
14 webidl Selection;
16 [scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)]
17 interface nsIHTMLEditor : nsISupports
19 %{C++
20 typedef short EAlignment;
23 // used by GetAlignment()
24 const short eLeft = 0;
25 const short eCenter = 1;
26 const short eRight = 2;
27 const short eJustify = 3;
30 /* ------------ Inline property methods -------------- */
32 /**
33 * SetInlineProperty() sets the aggregate properties on the current selection
35 * @param aProperty the property to set on the selection
36 * @param aAttribute the attribute of the property, if applicable.
37 * May be null.
38 * Example: aProperty="font", aAttribute="color"
39 * @param aValue if aAttribute is not null, the value of the attribute.
40 * May be null.
41 * Example: aProperty="font", aAttribute="color",
42 * aValue="0x00FFFF"
44 [can_run_script]
45 void setInlineProperty(in AString aProperty,
46 in AString aAttribute,
47 in AString aValue);
49 /**
50 * getInlinePropertyWithAttrValue() gets aggregate properties of the current
51 * selection. All object in the current selection are scanned and their
52 * attributes are represented in a list of Property object.
54 * @param aProperty the property to get on the selection
55 * @param aAttribute the attribute of the property, if applicable.
56 * May be null.
57 * Example: aProperty="font", aAttribute="color"
58 * @param aValue if aAttribute is not null, the value of the attribute.
59 * May be null.
60 * Example: aProperty="font", aAttribute="color",
61 * aValue="0x00FFFF"
62 * @param aFirst [OUT] PR_TRUE if the first text node in the
63 * selection has the property
64 * @param aAny [OUT] PR_TRUE if any of the text nodes in the
65 * selection have the property
66 * @param aAll [OUT] PR_TRUE if all of the text nodes in the
67 * selection have the property
69 [can_run_script]
70 AString getInlinePropertyWithAttrValue(in AString aProperty,
71 in AString aAttribute,
72 in AString aValue,
73 out boolean aFirst,
74 out boolean aAny,
75 out boolean aAll);
77 /**
78 * removeInlineProperty() removes a property which changes inline style of
79 * text. E.g., bold, italic, super and sub.
81 * @param aProperty Tag name whcih represents the inline style you want to
82 * remove. E.g., "strong", "b", etc.
83 * If "href", <a> element which has href attribute will be
84 * removed.
85 * If "name", <a> element which has non-empty name
86 * attribute will be removed.
87 * @param aAttribute If aProperty is "font", aAttribute should be "face",
88 * "size", "color" or "bgcolor".
90 [can_run_script]
91 void removeInlineProperty(in AString aProperty, in AString aAttribute);
93 /* ------------ HTML content methods -------------- */
95 /**
96 * Tests if a node is a BLOCK element. It's depend on
97 * `editor.block_inline_check.use_computed_style` pref whether this refers
98 * the computed style or the default style.
100 * @param aNode the node to test
102 [can_run_script]
103 boolean nodeIsBlock(in Node aNode);
106 * Insert some HTML source at the current location
108 * @param aInputString the string to be inserted
110 [can_run_script]
111 void insertHTML(in AString aInputString);
114 * Rebuild the entire document from source HTML
115 * Needed to be able to edit HEAD and other outside-of-BODY content
117 * @param aSourceString HTML source string of the entire new document
119 [can_run_script]
120 void rebuildDocumentFromSource(in AString aSourceString);
123 * Insert an element, which may have child nodes, at the selection
124 * Used primarily to insert a new element for various insert element dialogs,
125 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
126 * be useful for other elements.
128 * @param aElement The element to insert
129 * @param aDeleteSelection Delete the selection before inserting
130 * If aDeleteSelection is PR_FALSE, then the element is inserted
131 * after the end of the selection for all element except
132 * Named Anchors, which insert before the selection
134 [can_run_script]
135 void insertElementAtSelection(in Element aElement,
136 in boolean aDeleteSelection);
139 * Set the BaseURL for the document to the current URL
140 * but only if the page doesn't have a <base> tag
141 * This should be done after the document URL has changed,
142 * such as after saving a file
143 * This is used as base for relativizing link and image urls
145 void updateBaseURL();
148 /* ------------ Selection manipulation -------------- */
149 /* Should these be moved to Selection? */
152 * Set the selection at the suppled element
154 * @param aElement An element in the document
156 [can_run_script]
157 void selectElement(in Element aElement);
160 * getParagraphState returns what block tag paragraph format is in
161 * the selection.
162 * @param aMixed True if there is more than one format
163 * @return Name of block tag. "" is returned for none.
165 AString getParagraphState(out boolean aMixed);
168 * getFontFaceState returns what font face is in the selection.
169 * @param aMixed True if there is more than one font face
170 * @return Name of face. Note: "tt" is returned for
171 * tt tag. "" is returned for none.
173 [can_run_script]
174 AString getFontFaceState(out boolean aMixed);
177 * getHighlightColorState returns what the highlight color of the selection.
178 * @param aMixed True if there is more than one font color
179 * @return Color string. "" is returned for none.
181 [can_run_script]
182 AString getHighlightColorState(out boolean aMixed);
185 * getListState returns what list type is in the selection.
186 * @param aMixed True if there is more than one type of list, or
187 * if there is some list and non-list
188 * @param aOL The company that employs me. No, really, it's
189 * true if an "ol" list is selected.
190 * @param aUL true if an "ul" list is selected.
191 * @param aDL true if a "dl" list is selected.
193 void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
194 out boolean aDL);
197 * getListItemState returns what list item type is in the selection.
198 * @param aMixed True if there is more than one type of list item, or
199 * if there is some list and non-list
200 * XXX This ignores `<li>` element selected state.
201 * For example, even if `<li>` and `<dt>` are selected,
202 * this is set to false.
203 * @param aLI true if "li" list items are selected.
204 * @param aDT true if "dt" list items are selected.
205 * @param aDD true if "dd" list items are selected.
207 void getListItemState(out boolean aMixed, out boolean aLI,
208 out boolean aDT, out boolean aDD);
211 * getAlignment returns what alignment is in the selection.
212 * @param aMixed Always returns false.
213 * @param aAlign enum value for first encountered alignment
214 * (left/center/right)
216 [can_run_script]
217 void getAlignment(out boolean aMixed, out short aAlign);
220 * Document me!
223 [can_run_script]
224 void makeOrChangeList(in AString aListType, in boolean entireList,
225 in AString aBulletType);
228 * removeList removes list items (<li>, <dd>, and <dt>) and list structures
229 * (<ul>, <ol>, and <dl>).
231 * @param aListType Unused.
233 [can_run_script]
234 void removeList(in AString aListType);
237 * GetElementOrParentByTagName() returns an inclusive ancestor element whose
238 * name matches aTagName from aNode or anchor node of Selection to <body>
239 * element or null if there is no element matching with aTagName.
241 * @param aTagName The tag name which you want to look for.
242 * Must not be empty string.
243 * If "list", the result may be <ul>, <ol> or <dl>
244 * element.
245 * If "td", the result may be <td> or <th>.
246 * If "href", the result may be <a> element
247 * which has "href" attribute with non-empty value.
248 * If "anchor", the result may be <a> which has
249 * "name" attribute with non-empty value.
250 * @param aNode If non-null, this starts to look for the result
251 * from it. Otherwise, i.e., null, starts from
252 * anchor node of Selection.
253 * @return If an element which matches aTagName, returns
254 * an Element. Otherwise, nullptr.
256 Element getElementOrParentByTagName(in AString aTagName,
257 in Node aNode);
260 * getSelectedElement() returns a "selected" element node. "selected" means:
261 * - there is only one selection range
262 * - the range starts from an element node or in an element
263 * - the range ends at immediately after same element
264 * - and the range does not include any other element nodes.
265 * Additionally, only when aTagName is "href", this thinks that an <a>
266 * element which has non-empty "href" attribute includes the range, the
267 * <a> element is selected.
269 * @param aTagName Case-insensitive element name.
270 * If empty string, this returns any element node or null.
271 * If "href", this returns an <a> element which has
272 * non-empty "href" attribute or null.
273 * If "anchor", this returns an <a> element which has
274 * non-empty "name" attribute or null.
275 * Otherwise, returns an element node whose name is
276 * same as aTagName or null.
277 * @return A "selected" element.
279 nsISupports getSelectedElement(in AString aTagName);
282 * Return a new element with default attribute values
284 * This does not rely on the selection, and is not sensitive to context.
286 * Used primarily to supply new element for various insert element dialogs
287 * (Image, Link, NamedAnchor, Table, and HorizontalRule
288 * are the only returned elements as of 7/25/99)
290 * @param aTagName The HTML tagname
291 * Special input values for Links and Named anchors:
292 * Use "href" to get a link node
293 * (an "A" tag with the "href" attribute set)
294 * Use "anchor" or "namedanchor" to get a named anchor node
295 * (an "A" tag with the "name" attribute set)
296 * @return The new element created.
298 [can_run_script]
299 Element createElementWithDefaults(in AString aTagName);
302 * Insert an link element as the parent of the current selection
304 * @param aElement An "A" element with a non-empty "href" attribute
306 [can_run_script]
307 void insertLinkAroundSelection(in Element aAnchorElement);
310 * Set the value of the "bgcolor" attribute on the document's <body> element
312 * @param aColor The HTML color string, such as "#ffccff" or "yellow"
314 [can_run_script]
315 void setBackgroundColor(in AString aColor);
318 * A boolean which is true is the HTMLEditor has been instantiated
319 * with CSS knowledge and if the CSS pref is currently checked
321 * @return true if CSS handled and enabled
323 [setter_can_run_script] attribute boolean isCSSEnabled;
326 * checkSelectionStateForAnonymousButtons() may refresh editing UI such as
327 * resizers, inline-table-editing UI, absolute positioning UI for current
328 * Selection and focus state. When this method shows or hides UI, the
329 * editor (and/or its document/window) could be broken by mutation observers.
330 * FYI: Current user in script is only BlueGriffon.
332 [can_run_script]
333 void checkSelectionStateForAnonymousButtons();
335 boolean isAnonymousElement(in Element aElement);
338 * A boolean indicating if a return key pressed in a paragraph creates
339 * another paragraph or just inserts a <br> at the caret
341 * @return true if CR in a paragraph creates a new paragraph
343 attribute boolean returnInParagraphCreatesNewParagraph;