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"
16 [scriptable
, builtinclass
, uuid(87ee993e
-985f
-4a43
-a974
-0d9512da2fb0
)]
17 interface nsIHTMLEditor
: nsISupports
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 -------------- */
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.
38 * Example: aProperty="font", aAttribute="color"
39 * @param aValue if aAttribute is not null, the value of the attribute.
41 * Example: aProperty="font", aAttribute="color",
45 void setInlineProperty
(in AString aProperty
,
46 in AString aAttribute
,
50 * getInlineProperty() gets aggregate properties of the current selection.
51 * All object in the current selection are scanned and their attributes are
52 * 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.
57 * Example: aProperty="font", aAttribute="color"
58 * @param aValue if aAttribute is not null, the value of the attribute.
60 * Example: aProperty="font", aAttribute="color",
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
70 void getInlineProperty
(in AString aProperty
,
71 in AString aAttribute
,
78 AString getInlinePropertyWithAttrValue
(in AString aProperty
,
79 in AString aAttribute
,
86 * removeInlineProperty() removes a property which changes inline style of
87 * text. E.g., bold, italic, super and sub.
89 * @param aProperty Tag name whcih represents the inline style you want to
90 * remove. E.g., "strong", "b", etc.
91 * If "href", <a> element which has href attribute will be
93 * If "name", <a> element which has non-empty name
94 * attribute will be removed.
95 * @param aAttribute If aProperty is "font", aAttribute should be "face",
96 * "size", "color" or "bgcolor".
99 void removeInlineProperty
(in AString aProperty
, in AString aAttribute
);
101 /* ------------ HTML content methods -------------- */
104 * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
105 * This does NOT consider CSS effect on display type
107 * @param aNode the node to test
109 boolean nodeIsBlock
(in Node node
);
112 * Insert some HTML source at the current location
114 * @param aInputString the string to be inserted
117 void insertHTML
(in AString aInputString
);
121 * Paste the text in the OS clipboard at the cursor position, replacing
122 * the selected text (if any), but strip out any HTML styles and formatting
125 void pasteNoFormatting
(in long aSelectionType
);
128 * Rebuild the entire document from source HTML
129 * Needed to be able to edit HEAD and other outside-of-BODY content
131 * @param aSourceString HTML source string of the entire new document
134 void rebuildDocumentFromSource
(in AString aSourceString
);
137 * Insert an element, which may have child nodes, at the selection
138 * Used primarily to insert a new element for various insert element dialogs,
139 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
140 * be useful for other elements.
142 * @param aElement The element to insert
143 * @param aDeleteSelection Delete the selection before inserting
144 * If aDeleteSelection is PR_FALSE, then the element is inserted
145 * after the end of the selection for all element except
146 * Named Anchors, which insert before the selection
149 void insertElementAtSelection
(in Element aElement
,
150 in boolean aDeleteSelection
);
153 * Set the BaseURL for the document to the current URL
154 * but only if the page doesn't have a <base> tag
155 * This should be done after the document URL has changed,
156 * such as after saving a file
157 * This is used as base for relativizing link and image urls
159 void updateBaseURL
();
162 /* ------------ Selection manipulation -------------- */
163 /* Should these be moved to Selection? */
166 * Set the selection at the suppled element
168 * @param aElement An element in the document
171 void selectElement
(in Element aElement
);
174 * Create a collapsed selection just after aElement
176 * XXX could we parameterize SelectElement(before/select/after>?
178 * The selection is set to parent-of-aElement with an
179 * offset 1 greater than aElement's offset
180 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
181 * be useful for other elements.
183 * @param aElement An element in the document
185 void setCaretAfterElement
(in Element aElement
);
188 * getParagraphState returns what block tag paragraph format is in
190 * @param aMixed True if there is more than one format
191 * @return Name of block tag. "" is returned for none.
193 AString getParagraphState
(out boolean aMixed
);
196 * getFontFaceState returns what font face is in the selection.
197 * @param aMixed True if there is more than one font face
198 * @return Name of face. Note: "tt" is returned for
199 * tt tag. "" is returned for none.
202 AString getFontFaceState
(out boolean aMixed
);
205 * getHighlightColorState returns what the highlight color of the selection.
206 * @param aMixed True if there is more than one font color
207 * @return Color string. "" is returned for none.
210 AString getHighlightColorState
(out boolean aMixed
);
213 * getListState returns what list type is in the selection.
214 * @param aMixed True if there is more than one type of list, or
215 * if there is some list and non-list
216 * @param aOL The company that employs me. No, really, it's
217 * true if an "ol" list is selected.
218 * @param aUL true if an "ul" list is selected.
219 * @param aDL true if a "dl" list is selected.
221 void getListState
(out boolean aMixed
, out boolean aOL
, out boolean aUL
,
225 * getListItemState returns what list item type is in the selection.
226 * @param aMixed True if there is more than one type of list item, or
227 * if there is some list and non-list
228 * XXX This ignores `<li>` element selected state.
229 * For example, even if `<li>` and `<dt>` are selected,
230 * this is set to false.
231 * @param aLI true if "li" list items are selected.
232 * @param aDT true if "dt" list items are selected.
233 * @param aDD true if "dd" list items are selected.
235 void getListItemState
(out boolean aMixed
, out boolean aLI
,
236 out boolean aDT
, out boolean aDD
);
239 * getAlignment returns what alignment is in the selection.
240 * @param aMixed Always returns false.
241 * @param aAlign enum value for first encountered alignment
242 * (left/center/right)
245 void getAlignment
(out boolean aMixed
, out short aAlign
);
252 void makeOrChangeList
(in AString aListType
, in boolean entireList
,
253 in AString aBulletType
);
256 * removeList removes list items (<li>, <dd>, and <dt>) and list structures
257 * (<ul>, <ol>, and <dl>).
259 * @param aListType Unused.
262 void removeList
(in AString aListType
);
265 * GetElementOrParentByTagName() returns an inclusive ancestor element whose
266 * name matches aTagName from aNode or anchor node of Selection to <body>
267 * element or null if there is no element matching with aTagName.
269 * @param aTagName The tag name which you want to look for.
270 * Must not be empty string.
271 * If "list", the result may be <ul>, <ol> or <dl>
273 * If "td", the result may be <td> or <th>.
274 * If "href", the result may be <a> element
275 * which has "href" attribute with non-empty value.
276 * If "anchor", the result may be <a> which has
277 * "name" attribute with non-empty value.
278 * @param aNode If non-null, this starts to look for the result
279 * from it. Otherwise, i.e., null, starts from
280 * anchor node of Selection.
281 * @return If an element which matches aTagName, returns
282 * an Element. Otherwise, nullptr.
284 Element getElementOrParentByTagName
(in AString aTagName
,
288 * getSelectedElement() returns a "selected" element node. "selected" means:
289 * - there is only one selection range
290 * - the range starts from an element node or in an element
291 * - the range ends at immediately after same element
292 * - and the range does not include any other element nodes.
293 * Additionally, only when aTagName is "href", this thinks that an <a>
294 * element which has non-empty "href" attribute includes the range, the
295 * <a> element is selected.
297 * @param aTagName Case-insensitive element name.
298 * If empty string, this returns any element node or null.
299 * If "href", this returns an <a> element which has
300 * non-empty "href" attribute or null.
301 * If "anchor", this returns an <a> element which has
302 * non-empty "name" attribute or null.
303 * Otherwise, returns an element node whose name is
304 * same as aTagName or null.
305 * @return A "selected" element.
307 nsISupports getSelectedElement
(in AString aTagName
);
310 * Return a new element with default attribute values
312 * This does not rely on the selection, and is not sensitive to context.
314 * Used primarily to supply new element for various insert element dialogs
315 * (Image, Link, NamedAnchor, Table, and HorizontalRule
316 * are the only returned elements as of 7/25/99)
318 * @param aTagName The HTML tagname
319 * Special input values for Links and Named anchors:
320 * Use "href" to get a link node
321 * (an "A" tag with the "href" attribute set)
322 * Use "anchor" or "namedanchor" to get a named anchor node
323 * (an "A" tag with the "name" attribute set)
324 * @return The new element created.
327 Element createElementWithDefaults
(in AString aTagName
);
330 * Insert an link element as the parent of the current selection
332 * @param aElement An "A" element with a non-empty "href" attribute
335 void insertLinkAroundSelection
(in Element aAnchorElement
);
338 * Set the value of the "bgcolor" attribute on the document's <body> element
340 * @param aColor The HTML color string, such as "#ffccff" or "yellow"
343 void setBackgroundColor
(in AString aColor
);
346 * A boolean which is true is the HTMLEditor has been instantiated
347 * with CSS knowledge and if the CSS pref is currently checked
349 * @return true if CSS handled and enabled
351 attribute
boolean isCSSEnabled
;
354 * checkSelectionStateForAnonymousButtons() may refresh editing UI such as
355 * resizers, inline-table-editing UI, absolute positioning UI for current
356 * Selection and focus state. When this method shows or hides UI, the
357 * editor (and/or its document/window) could be broken by mutation observers.
358 * FYI: Current user in script is only BlueGriffon.
361 void checkSelectionStateForAnonymousButtons
();
363 boolean isAnonymousElement
(in Element aElement
);
366 * A boolean indicating if a return key pressed in a paragraph creates
367 * another paragraph or just inserts a <br> at the caret
369 * @return true if CR in a paragraph creates a new paragraph
371 attribute
boolean returnInParagraphCreatesNewParagraph
;