Source code

Revision control

Other Tools

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/. */
5
6
#include "nsISupports.idl"
7
#include "domstubs.idl"
8
9
interface nsIContent;
10
11
webidl Document;
12
webidl Element;
13
webidl Node;
14
webidl Selection;
15
16
[scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)]
17
interface nsIHTMLEditor : nsISupports
18
{
19
%{C++
20
typedef short EAlignment;
21
%}
22
23
// used by GetAlignment()
24
const short eLeft = 0;
25
const short eCenter = 1;
26
const short eRight = 2;
27
const short eJustify = 3;
28
29
30
/* ------------ Inline property methods -------------- */
31
32
/**
33
* SetInlineProperty() sets the aggregate properties on the current selection
34
*
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"
43
*/
44
[can_run_script]
45
void setInlineProperty(in AString aProperty,
46
in AString aAttribute,
47
in AString aValue);
48
49
/**
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.
53
*
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
68
*/
69
void getInlineProperty(in AString aProperty,
70
in AString aAttribute,
71
in AString aValue,
72
out boolean aFirst,
73
out boolean aAny,
74
out boolean aAll);
75
76
AString getInlinePropertyWithAttrValue(in AString aProperty,
77
in AString aAttribute,
78
in AString aValue,
79
out boolean aFirst,
80
out boolean aAny,
81
out boolean aAll);
82
83
/**
84
* removeInlineProperty() removes a property which changes inline style of
85
* text. E.g., bold, italic, super and sub.
86
*
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
90
* removed.
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".
95
*/
96
[can_run_script]
97
void removeInlineProperty(in AString aProperty, in AString aAttribute);
98
99
/* ------------ HTML content methods -------------- */
100
101
/**
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
104
*
105
* @param aNode the node to test
106
*/
107
boolean nodeIsBlock(in Node node);
108
109
/**
110
* Insert some HTML source at the current location
111
*
112
* @param aInputString the string to be inserted
113
*/
114
[can_run_script]
115
void insertHTML(in AString aInputString);
116
117
118
/**
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
121
*/
122
[can_run_script]
123
void pasteNoFormatting(in long aSelectionType);
124
125
/**
126
* Rebuild the entire document from source HTML
127
* Needed to be able to edit HEAD and other outside-of-BODY content
128
*
129
* @param aSourceString HTML source string of the entire new document
130
*/
131
[can_run_script]
132
void rebuildDocumentFromSource(in AString aSourceString);
133
134
/**
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.
139
*
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
145
*/
146
[can_run_script]
147
void insertElementAtSelection(in Element aElement,
148
in boolean aDeleteSelection);
149
150
/**
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
156
*/
157
void updateBaseURL();
158
159
160
/* ------------ Selection manipulation -------------- */
161
/* Should these be moved to Selection? */
162
163
/**
164
* Set the selection at the suppled element
165
*
166
* @param aElement An element in the document
167
*/
168
[can_run_script]
169
void selectElement(in Element aElement);
170
171
/**
172
* Create a collapsed selection just after aElement
173
*
174
* XXX could we parameterize SelectElement(before/select/after>?
175
*
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.
180
*
181
* @param aElement An element in the document
182
*/
183
void setCaretAfterElement(in Element aElement);
184
185
/**
186
* getParagraphState returns what block tag paragraph format is in
187
* the selection.
188
* @param aMixed True if there is more than one format
189
* @return Name of block tag. "" is returned for none.
190
*/
191
AString getParagraphState(out boolean aMixed);
192
193
/**
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.
198
*/
199
AString getFontFaceState(out boolean aMixed);
200
201
/**
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.
205
*/
206
AString getHighlightColorState(out boolean aMixed);
207
208
/**
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.
216
*/
217
void getListState(out boolean aMixed, out boolean aOL, out boolean aUL,
218
out boolean aDL);
219
220
/**
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.
230
*/
231
void getListItemState(out boolean aMixed, out boolean aLI,
232
out boolean aDT, out boolean aDD);
233
234
/**
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)
239
*/
240
void getAlignment(out boolean aMixed, out short aAlign);
241
242
/**
243
* Document me!
244
*
245
*/
246
[can_run_script]
247
void makeOrChangeList(in AString aListType, in boolean entireList,
248
in AString aBulletType);
249
250
/**
251
* removeList removes list items (<li>, <dd>, and <dt>) and list structures
252
* (<ul>, <ol>, and <dl>).
253
*
254
* @param aListType Unused.
255
*/
256
[can_run_script]
257
void removeList(in AString aListType);
258
259
/**
260
* GetElementOrParentByTagName() looks for an element node whose name matches
261
* aTagName from aNode or anchor node of Selection to <body> element.
262
*
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>
266
* element.
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.
277
*/
278
Element getElementOrParentByTagName(in AString aTagName,
279
in Node aNode);
280
281
/**
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.
290
*
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.
300
*/
301
nsISupports getSelectedElement(in AString aTagName);
302
303
/**
304
* Return a new element with default attribute values
305
*
306
* This does not rely on the selection, and is not sensitive to context.
307
*
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)
311
*
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.
319
*/
320
[can_run_script]
321
Element createElementWithDefaults(in AString aTagName);
322
323
/**
324
* Insert an link element as the parent of the current selection
325
*
326
* @param aElement An "A" element with a non-empty "href" attribute
327
*/
328
[can_run_script]
329
void insertLinkAroundSelection(in Element aAnchorElement);
330
331
/**
332
* Set the value of the "bgcolor" attribute on the document's <body> element
333
*
334
* @param aColor The HTML color string, such as "#ffccff" or "yellow"
335
*/
336
[can_run_script]
337
void setBackgroundColor(in AString aColor);
338
339
/**
340
* A boolean which is true is the HTMLEditor has been instantiated
341
* with CSS knowledge and if the CSS pref is currently checked
342
*
343
* @return true if CSS handled and enabled
344
*/
345
attribute boolean isCSSEnabled;
346
347
/**
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.
353
*/
354
[can_run_script]
355
void checkSelectionStateForAnonymousButtons();
356
357
boolean isAnonymousElement(in Element aElement);
358
359
/**
360
* A boolean indicating if a return key pressed in a paragraph creates
361
* another paragraph or just inserts a <br> at the caret
362
*
363
* @return true if CR in a paragraph creates a new paragraph
364
*/
365
attribute boolean returnInParagraphCreatesNewParagraph;
366
};
367