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
69 void getInlineProperty
(in AString aProperty
,
70 in AString aAttribute
,
76 AString getInlinePropertyWithAttrValue
(in AString aProperty
,
77 in AString aAttribute
,
84 * removeInlineProperty() removes a property which changes inline style of
85 * text. E.g., bold, italic, super and sub.
87 * @param aProperty Tag name whcih represents the inline style you want to
88 * remove. E.g., "strong", "b", etc.
89 * If "href", <a> element which has href attribute will be
91 * If "name", <a> element which has non-empty name
92 * attribute will be removed.
93 * @param aAttribute If aProperty is "font", aAttribute should be "face",
94 * "size", "color" or "bgcolor".
97 void removeInlineProperty
(in AString aProperty
, in AString aAttribute
);
99 /* ------------ HTML content methods -------------- */
102 * Tests if a node is a BLOCK element according the the HTML 4.0 DTD.
103 * This does NOT consider CSS effect on display type
105 * @param aNode the node to test
107 boolean nodeIsBlock
(in Node node
);
110 * Insert some HTML source at the current location
112 * @param aInputString the string to be inserted
115 void insertHTML
(in AString aInputString
);
119 * Paste the text in the OS clipboard at the cursor position, replacing
120 * the selected text (if any), but strip out any HTML styles and formatting
123 void pasteNoFormatting
(in long aSelectionType
);
126 * Rebuild the entire document from source HTML
127 * Needed to be able to edit HEAD and other outside-of-BODY content
129 * @param aSourceString HTML source string of the entire new document
132 void rebuildDocumentFromSource
(in AString aSourceString
);
135 * Insert an element, which may have child nodes, at the selection
136 * Used primarily to insert a new element for various insert element dialogs,
137 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
138 * be useful for other elements.
140 * @param aElement The element to insert
141 * @param aDeleteSelection Delete the selection before inserting
142 * If aDeleteSelection is PR_FALSE, then the element is inserted
143 * after the end of the selection for all element except
144 * Named Anchors, which insert before the selection
147 void insertElementAtSelection
(in Element aElement
,
148 in boolean aDeleteSelection
);
151 * Set the BaseURL for the document to the current URL
152 * but only if the page doesn't have a <base> tag
153 * This should be done after the document URL has changed,
154 * such as after saving a file
155 * This is used as base for relativizing link and image urls
157 void updateBaseURL
();
160 /* ------------ Selection manipulation -------------- */
161 /* Should these be moved to Selection? */
164 * Set the selection at the suppled element
166 * @param aElement An element in the document
169 void selectElement
(in Element aElement
);
172 * Create a collapsed selection just after aElement
174 * XXX could we parameterize SelectElement(before/select/after>?
176 * The selection is set to parent-of-aElement with an
177 * offset 1 greater than aElement's offset
178 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should
179 * be useful for other elements.
181 * @param aElement An element in the document
183 void setCaretAfterElement
(in Element aElement
);
186 * getParagraphState returns what block tag paragraph format is in
188 * @param aMixed True if there is more than one format
189 * @return Name of block tag. "" is returned for none.
191 AString getParagraphState
(out boolean aMixed
);
194 * getFontFaceState returns what font face is in the selection.
195 * @param aMixed True if there is more than one font face
196 * @return Name of face. Note: "tt" is returned for
197 * tt tag. "" is returned for none.
199 AString getFontFaceState
(out boolean aMixed
);
202 * getHighlightColorState returns what the highlight color of the selection.
203 * @param aMixed True if there is more than one font color
204 * @return Color string. "" is returned for none.
206 AString getHighlightColorState
(out boolean aMixed
);
209 * getListState returns what list type is in the selection.
210 * @param aMixed True if there is more than one type of list, or
211 * if there is some list and non-list
212 * @param aOL The company that employs me. No, really, it's
213 * true if an "ol" list is selected.
214 * @param aUL true if an "ul" list is selected.
215 * @param aDL true if a "dl" list is selected.
217 void getListState
(out boolean aMixed
, out boolean aOL
, out boolean aUL
,
221 * getListItemState returns what list item type is in the selection.
222 * @param aMixed True if there is more than one type of list item, or
223 * if there is some list and non-list
224 * XXX This ignores `<li>` element selected state.
225 * For example, even if `<li>` and `<dt>` are selected,
226 * this is set to false.
227 * @param aLI true if "li" list items are selected.
228 * @param aDT true if "dt" list items are selected.
229 * @param aDD true if "dd" list items are selected.
231 void getListItemState
(out boolean aMixed
, out boolean aLI
,
232 out boolean aDT
, out boolean aDD
);
235 * getAlignment returns what alignment is in the selection.
236 * @param aMixed Always returns false.
237 * @param aAlign enum value for first encountered alignment
238 * (left/center/right)
240 void getAlignment
(out boolean aMixed
, out short aAlign
);
247 void makeOrChangeList
(in AString aListType
, in boolean entireList
,
248 in AString aBulletType
);
251 * removeList removes list items (<li>, <dd>, and <dt>) and list structures
252 * (<ul>, <ol>, and <dl>).
254 * @param aListType Unused.
257 void removeList
(in AString aListType
);
260 * GetElementOrParentByTagName() looks for an element node whose name matches
261 * aTagName from aNode or anchor node of Selection to <body> element.
263 * @param aTagName The tag name which you want to look for.
264 * Must not be empty string.
265 * If "list", the result may be <ul>, <ol> or <dl>
267 * If "td", the result may be <td> or <th>.
268 * If "href", the result may be <a> element
269 * which has "href" attribute with non-empty value.
270 * If "anchor", the result may be <a> which has
271 * "name" attribute with non-empty value.
272 * @param aNode If non-null, this starts to look for the result
273 * from it. Otherwise, i.e., null, starts from
274 * anchor node of Selection.
275 * @return If an element which matches aTagName, returns
276 * an Element. Otherwise, nullptr.
278 Element getElementOrParentByTagName
(in AString aTagName
,
282 * getSelectedElement() returns a "selected" element node. "selected" means:
283 * - there is only one selection range
284 * - the range starts from an element node or in an element
285 * - the range ends at immediately after same element
286 * - and the range does not include any other element nodes.
287 * Additionally, only when aTagName is "href", this thinks that an <a>
288 * element which has non-empty "href" attribute includes the range, the
289 * <a> element is selected.
291 * @param aTagName Case-insensitive element name.
292 * If empty string, this returns any element node or null.
293 * If "href", this returns an <a> element which has
294 * non-empty "href" attribute or null.
295 * If "anchor", this returns an <a> element which has
296 * non-empty "name" attribute or null.
297 * Otherwise, returns an element node whose name is
298 * same as aTagName or null.
299 * @return A "selected" element.
301 nsISupports getSelectedElement
(in AString aTagName
);
304 * Return a new element with default attribute values
306 * This does not rely on the selection, and is not sensitive to context.
308 * Used primarily to supply new element for various insert element dialogs
309 * (Image, Link, NamedAnchor, Table, and HorizontalRule
310 * are the only returned elements as of 7/25/99)
312 * @param aTagName The HTML tagname
313 * Special input values for Links and Named anchors:
314 * Use "href" to get a link node
315 * (an "A" tag with the "href" attribute set)
316 * Use "anchor" or "namedanchor" to get a named anchor node
317 * (an "A" tag with the "name" attribute set)
318 * @return The new element created.
321 Element createElementWithDefaults
(in AString aTagName
);
324 * Insert an link element as the parent of the current selection
326 * @param aElement An "A" element with a non-empty "href" attribute
329 void insertLinkAroundSelection
(in Element aAnchorElement
);
332 * Set the value of the "bgcolor" attribute on the document's <body> element
334 * @param aColor The HTML color string, such as "#ffccff" or "yellow"
337 void setBackgroundColor
(in AString aColor
);
340 * A boolean which is true is the HTMLEditor has been instantiated
341 * with CSS knowledge and if the CSS pref is currently checked
343 * @return true if CSS handled and enabled
345 attribute
boolean isCSSEnabled
;
348 * checkSelectionStateForAnonymousButtons() may refresh editing UI such as
349 * resizers, inline-table-editing UI, absolute positioning UI for current
350 * Selection and focus state. When this method shows or hides UI, the
351 * editor (and/or its document/window) could be broken by mutation observers.
352 * FYI: Current user in script is only BlueGriffon.
355 void checkSelectionStateForAnonymousButtons
();
357 boolean isAnonymousElement
(in Element aElement
);
360 * A boolean indicating if a return key pressed in a paragraph creates
361 * another paragraph or just inserts a <br> at the caret
363 * @return true if CR in a paragraph creates a new paragraph
365 attribute
boolean returnInParagraphCreatesNewParagraph
;