Source code

Revision control

Other Tools

1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2
*
3
* This Source Code Form is subject to the terms of the Mozilla Public
4
* License, v. 2.0. If a copy of the MPL was not distributed with this
5
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7
#include "nsISupports.idl"
8
#include "domstubs.idl"
9
10
interface nsIURI;
11
interface nsIContent;
12
interface nsISelectionController;
13
interface nsIDocumentStateListener;
14
interface nsIOutputStream;
15
interface nsITransactionManager;
16
interface nsITransaction;
17
interface nsIEditorObserver;
18
interface nsIEditActionListener;
19
interface nsIInlineSpellChecker;
20
interface nsITransferable;
21
22
webidl Document;
23
webidl Element;
24
webidl Node;
25
webidl Selection;
26
27
%{C++
28
namespace mozilla {
29
class EditorBase;
30
class HTMLEditor;
31
class TextEditor;
32
} // namespace mozilla
33
%}
34
35
[scriptable, builtinclass, uuid(094be624-f0bf-400f-89e2-6a84baab9474)]
36
interface nsIEditor : nsISupports
37
{
38
%{C++
39
typedef short EDirection;
40
typedef short EStripWrappers;
41
%}
42
const short eNone = 0;
43
const short eNext = 1;
44
const short ePrevious = 2;
45
const short eNextWord = 3;
46
const short ePreviousWord = 4;
47
const short eToBeginningOfLine = 5;
48
const short eToEndOfLine = 6;
49
50
const short eStrip = 0;
51
const short eNoStrip = 1;
52
53
// only plain text entry is allowed via events
54
const long eEditorPlaintextMask = 0x0001;
55
// enter key and CR-LF handled specially
56
const long eEditorSingleLineMask = 0x0002;
57
// text is not entered into content, only a representative character
58
const long eEditorPasswordMask = 0x0004;
59
// editing events are disabled. Editor may still accept focus.
60
const long eEditorReadonlyMask = 0x0008;
61
// text input is limited to certain character types, use mFilter
62
const long eEditorFilterInputMask = 0x0010;
63
// use mail-compose editing rules
64
const long eEditorMailMask = 0x0020;
65
// allow the editor to set font: monospace on the root node
66
const long eEditorEnableWrapHackMask = 0x0040;
67
// bit for widgets (form elements)
68
const long eEditorWidgetMask = 0x0080;
69
// this HTML editor should not create css styles
70
const long eEditorNoCSSMask = 0x0100;
71
// whether HTML document specific actions are executed or not.
72
// e.g., if this flag is set, the editor doesn't handle Tab key.
73
// besides, anchors of HTML are not clickable.
74
const long eEditorAllowInteraction = 0x0200;
75
// when this is set, the characters in password editor are always masked.
76
// see bug 530367 for the detail.
77
const long eEditorDontEchoPassword = 0x0400;
78
// when this flag is set, the internal direction of the editor is RTL.
79
// if neither of the direction flags are set, the direction is determined
80
// from the text control's content node.
81
const long eEditorRightToLeft = 0x0800;
82
// when this flag is set, the internal direction of the editor is LTR.
83
const long eEditorLeftToRight = 0x1000;
84
// when this flag is set, the editor's text content is not spell checked.
85
const long eEditorSkipSpellCheck = 0x2000;
86
87
/*
88
* The valid values for newlines handling.
89
* Can't change the values unless we remove
90
* use of the pref.
91
*/
92
const long eNewlinesPasteIntact = 0;
93
const long eNewlinesPasteToFirst = 1;
94
const long eNewlinesReplaceWithSpaces = 2;
95
const long eNewlinesStrip = 3;
96
const long eNewlinesReplaceWithCommas = 4;
97
const long eNewlinesStripSurroundingWhitespace = 5;
98
99
readonly attribute Selection selection;
100
101
[can_run_script]
102
void setAttributeOrEquivalent(in Element element,
103
in AString sourceAttrName,
104
in AString sourceAttrValue,
105
in boolean aSuppressTransaction);
106
[can_run_script]
107
void removeAttributeOrEquivalent(in Element element,
108
in AString sourceAttrName,
109
in boolean aSuppressTransaction);
110
111
/** edit flags for this editor. May be set at any time. */
112
attribute unsigned long flags;
113
114
/**
115
* the MimeType of the document
116
*/
117
attribute string contentsMIMEType;
118
119
/** Returns true if we have a document that is not marked read-only */
120
readonly attribute boolean isDocumentEditable;
121
122
/** Returns true if the current selection anchor is editable */
123
readonly attribute boolean isSelectionEditable;
124
125
/**
126
* the DOM Document this editor is associated with, refcounted.
127
*/
128
readonly attribute Document document;
129
130
/** the body element, i.e. the root of the editable document.
131
*/
132
readonly attribute Element rootElement;
133
134
/**
135
* the selection controller for the current presentation, refcounted.
136
*/
137
readonly attribute nsISelectionController selectionController;
138
139
140
/* ------------ Selected content removal -------------- */
141
142
/**
143
* DeleteSelection removes all nodes in the current selection.
144
* @param aDir if eNext, delete to the right (for example, the DEL key)
145
* if ePrevious, delete to the left (for example, the BACKSPACE key)
146
* @param stripWrappers If eStrip, strip any empty inline elements left
147
* behind after the deletion; if eNoStrip, don't. If in
148
* doubt, pass eStrip -- eNoStrip is only for if you're
149
* about to insert text or similar right after.
150
*/
151
[can_run_script]
152
void deleteSelection(in short action, in short stripWrappers);
153
154
155
/* ------------ Document info and file methods -------------- */
156
157
/** Returns true if the document has no *meaningful* content */
158
readonly attribute boolean documentIsEmpty;
159
160
/** Returns true if the document is modifed and needs saving */
161
readonly attribute boolean documentModified;
162
163
/** Sets the current 'Save' document character set */
164
[can_run_script] // setter only
165
attribute ACString documentCharacterSet;
166
167
/** to be used ONLY when we need to override the doc's modification
168
* state (such as when it's saved).
169
*/
170
[can_run_script]
171
void resetModificationCount();
172
173
/** Gets the modification count of the document we are editing.
174
* @return the modification count of the document being edited.
175
* Zero means unchanged.
176
*/
177
long getModificationCount();
178
179
/** called each time we modify the document.
180
* Increments the modification count of the document.
181
* @param aModCount the number of modifications by which
182
* to increase or decrease the count
183
*/
184
[can_run_script]
185
void incrementModificationCount(in long aModCount);
186
187
/* ------------ Transaction methods -------------- */
188
189
/** transactionManager Get the transaction manager the editor is using.
190
*/
191
readonly attribute nsITransactionManager transactionManager;
192
193
/** doTransaction() fires a transaction.
194
* It is provided here so clients can create their own transactions.
195
* If a transaction manager is present, it is used.
196
* Otherwise, the transaction is just executed directly.
197
*
198
* @param aTxn the transaction to execute
199
*/
200
[can_run_script]
201
void doTransaction(in nsITransaction txn);
202
203
204
/** turn the undo system on or off
205
* @param aEnable if PR_TRUE, the undo system is turned on if available
206
* if PR_FALSE the undo system is turned off if it
207
* was previously on
208
* @return if aEnable is PR_TRUE, returns NS_OK if
209
* the undo system could be initialized properly
210
* if aEnable is PR_FALSE, returns NS_OK.
211
*/
212
void enableUndo(in boolean enable);
213
214
/** undo reverses the effects of the last Do operation,
215
* if Undo is enabled in the editor.
216
* It is provided here so clients need no knowledge of whether
217
* the editor has a transaction manager or not.
218
* If a transaction manager is present, it is told to undo,
219
* and the result of that undo is returned.
220
* Otherwise, the Undo request is ignored and an
221
* error NS_ERROR_NOT_AVAILABLE is returned.
222
*
223
*/
224
[can_run_script]
225
void undo(in unsigned long count);
226
227
/** returns state information about the undo system.
228
* @param aIsEnabled [OUT] PR_TRUE if undo is enabled
229
* @param aCanUndo [OUT] PR_TRUE if at least one transaction is
230
* currently ready to be undone.
231
*/
232
void canUndo(out boolean isEnabled, out boolean canUndo);
233
234
/** redo reverses the effects of the last Undo operation
235
* It is provided here so clients need no knowledge of whether
236
* the editor has a transaction manager or not.
237
* If a transaction manager is present, it is told to redo and the
238
* result of the previously undone transaction is reapplied to the document.
239
* If no transaction is available for Redo, or if the document
240
* has no transaction manager, the Redo request is ignored and an
241
* error NS_ERROR_NOT_AVAILABLE is returned.
242
*
243
*/
244
[can_run_script]
245
void redo(in unsigned long count);
246
247
/** returns state information about the redo system.
248
* @param aIsEnabled [OUT] PR_TRUE if redo is enabled
249
* @param aCanRedo [OUT] PR_TRUE if at least one transaction is
250
currently ready to be redone.
251
*/
252
void canRedo(out boolean isEnabled, out boolean canRedo);
253
254
/** beginTransaction is a signal from the caller to the editor that
255
* the caller will execute multiple updates to the content tree
256
* that should be treated as a single logical operation,
257
* in the most efficient way possible.<br>
258
* All transactions executed between a call to beginTransaction and
259
* endTransaction will be undoable as an atomic action.<br>
260
* endTransaction must be called after beginTransaction.<br>
261
* Calls to beginTransaction can be nested, as long as endTransaction
262
* is called once per beginUpdate.
263
*/
264
[can_run_script]
265
void beginTransaction();
266
267
/** endTransaction is a signal to the editor that the caller is
268
* finished updating the content model.<br>
269
* beginUpdate must be called before endTransaction is called.<br>
270
* Calls to beginTransaction can be nested, as long as endTransaction
271
* is called once per beginTransaction.
272
*/
273
[can_run_script]
274
void endTransaction();
275
276
/**
277
* While setting the flag with this method to false, CreateElementTransaction,
278
* DeleteRangeTransaction, DeleteTextTransaction, InsertNodeTransaction,
279
* InsertTextTransaction and SplitNodeTransaction won't change Selection
280
* after modifying the DOM tree.
281
* Note that calling this with false does not guarantee that Selection won't
282
* be changed because other transaction may ignore this flag, editor itself
283
* may change selection, and current selection may become invalid after
284
* changing the DOM tree, etc.
285
* After calling this method with true, the caller should guarantee that
286
* Selection should be positioned where user expects.
287
*
288
* @param should false if you don't want above transactions to modify
289
* Selection automatically after modifying the DOM tree.
290
* Note that calling this with false does not guarantee
291
* that Selection is never changed.
292
*/
293
void setShouldTxnSetSelection(in boolean should);
294
295
/* ------------ Inline Spell Checking methods -------------- */
296
297
/** Returns the inline spell checker associated with this object. The spell
298
* checker is lazily created, so this function may create the object for
299
* you during this call.
300
* @param autoCreate If true, this will create a spell checker object
301
* if one does not exist yet for this editor. If false
302
* and the object has not been created, this function
303
* WILL RETURN NULL.
304
*/
305
nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);
306
307
/** Called when the user manually overrides the spellchecking state for this
308
* editor.
309
* @param enable The new state of spellchecking in this editor, as
310
* requested by the user.
311
*/
312
void setSpellcheckUserOverride(in boolean enable);
313
314
/* ------------ Clipboard methods -------------- */
315
316
/** cut the currently selected text, putting it into the OS clipboard
317
* What if no text is selected?
318
* What about mixed selections?
319
* What are the clipboard formats?
320
*/
321
[can_run_script]
322
void cut();
323
324
/**
325
* canCut() returns true if selected content is allowed to be copied to the
326
* clipboard and to be removed.
327
* Note that this always returns true if the editor is in a non-chrome
328
* HTML/XHTML document.
329
* FYI: Current user in script is only BlueGriffon.
330
*/
331
boolean canCut();
332
333
/** copy the currently selected text, putting it into the OS clipboard
334
* What if no text is selected?
335
* What about mixed selections?
336
* What are the clipboard formats?
337
*/
338
void copy();
339
340
/**
341
* canCopy() returns true if selected content is allowed to be copied to
342
* the clipboard.
343
* Note that this always returns true if the editor is in a non-chrome
344
* HTML/XHTML document.
345
* FYI: Current user in script is only BlueGriffon.
346
*/
347
boolean canCopy();
348
349
/** paste the text in the OS clipboard at the cursor position, replacing
350
* the selected text (if any)
351
*/
352
[can_run_script]
353
void paste(in long aClipboardType);
354
355
/** Paste the text in |aTransferable| at the cursor position, replacing the
356
* selected text (if any).
357
*/
358
[can_run_script]
359
void pasteTransferable(in nsITransferable aTransferable);
360
361
/** Can we paste? True if the doc is modifiable, and we have
362
* pasteable data in the clipboard.
363
*/
364
boolean canPaste(in long aClipboardType);
365
366
/* ------------ Selection methods -------------- */
367
368
/** sets the document selection to the entire contents of the document */
369
[can_run_script]
370
void selectAll();
371
372
/**
373
* Collapses selection at start of the document. If it's an HTML editor,
374
* collapses selection at start of current editing host (<body> element if
375
* it's in designMode) instead. If there is a non-editable node before any
376
* editable text nodes or inline elements which can have text nodes as their
377
* children, collapses selection at start of the editing host. If there is
378
* an editable text node which is not collapsed, collapses selection at
379
* start of the text node. If there is an editable inline element which
380
* cannot have text nodes as its child, collapses selection at before the
381
* element node. Otherwise, collapses selection at start of the editing
382
* host.
383
*/
384
void beginningOfDocument();
385
386
/** sets the document selection to the end of the document */
387
void endOfDocument();
388
389
/* ------------ Node manipulation methods -------------- */
390
391
/**
392
* setAttribute() sets the attribute of aElement.
393
* No checking is done to see if aAttribute is a legal attribute of the node,
394
* or if aValue is a legal value of aAttribute.
395
*
396
* @param aElement the content element to operate on
397
* @param aAttribute the string representation of the attribute to set
398
* @param aValue the value to set aAttribute to
399
*/
400
[can_run_script]
401
void setAttribute(in Element aElement, in AString attributestr,
402
in AString attvalue);
403
404
/**
405
* removeAttribute() deletes aAttribute from the attribute list of aElement.
406
* If aAttribute is not an attribute of aElement, nothing is done.
407
*
408
* @param aElement the content element to operate on
409
* @param aAttribute the string representation of the attribute to get
410
*/
411
[can_run_script]
412
void removeAttribute(in Element aElement,
413
in AString aAttribute);
414
415
/**
416
* cloneAttributes() is similar to Node::cloneNode(),
417
* it assures the attribute nodes of the destination are identical
418
* with the source node by copying all existing attributes from the
419
* source and deleting those not in the source.
420
* This is used when the destination element already exists
421
*
422
* @param aDestNode the destination element to operate on
423
* @param aSourceNode the source element to copy attributes from
424
*/
425
[can_run_script]
426
void cloneAttributes(in Element aDestElement, in Element aSourceElement);
427
428
/**
429
* insertNode inserts aNode into aParent at aPosition.
430
* No checking is done to verify the legality of the insertion.
431
* That is the responsibility of the caller.
432
* @param aNode The DOM Node to insert.
433
* @param aParent The node to insert the new object into
434
* @param aPosition The place in aParent to insert the new node
435
* 0=first child, 1=second child, etc.
436
* any number > number of current children = last child
437
*/
438
[can_run_script]
439
void insertNode(in Node node,
440
in Node parent,
441
in long aPosition);
442
443
444
/**
445
* deleteNode removes aChild from aParent.
446
* @param aChild The node to delete
447
*/
448
[can_run_script]
449
void deleteNode(in Node child);
450
451
/* ------------ Output methods -------------- */
452
453
/**
454
* Output methods:
455
* aFormatType is a mime type, like text/plain.
456
*/
457
AString outputToString(in AString formatType,
458
in unsigned long flags);
459
460
/* ------------ Various listeners methods --------------
461
* nsIEditor holds strong references to the editor observers, action listeners
462
* and document state listeners.
463
*/
464
465
/** add an EditorObserver to the editors list of observers. */
466
void addEditorObserver(in nsIEditorObserver observer);
467
468
/** add an EditActionListener to the editors list of listeners. */
469
void addEditActionListener(in nsIEditActionListener listener);
470
471
/** Remove an EditActionListener from the editor's list of listeners. */
472
void removeEditActionListener(in nsIEditActionListener listener);
473
474
/** Add a DocumentStateListener to the editors list of doc state listeners. */
475
void addDocumentStateListener(in nsIDocumentStateListener listener);
476
477
/** Remove a DocumentStateListener to the editors list of doc state listeners. */
478
void removeDocumentStateListener(in nsIDocumentStateListener listener);
479
480
/**
481
* forceCompositionEnd() force the composition end
482
*/
483
void forceCompositionEnd();
484
485
/**
486
* whether this editor has active IME transaction
487
*/
488
readonly attribute boolean composing;
489
490
/**
491
* unmask() is available only when the editor is a passwrod field. This
492
* unmasks characters in specified by aStart and aEnd. If there have
493
* already unmasked characters, they are masked when this is called.
494
* Note that if you calls this without non-zero `aTimeout`, you bear
495
* responsibility for masking password with calling `mask()`. I.e.,
496
* user inputting password won't be masked automacitally. If user types
497
* a new character and echo is enabled, unmasked range is expanded to
498
* including it.
499
*
500
* @param aStart Optional, first index to show the character. If you
501
* specify middle of a surrogate pair, this expands the
502
* range to include the prceding high surrogate
503
* automatically.
504
* If omitted, it means that all characters of the
505
* password becomes unmasked.
506
* @param aEnd Optional, next index of last unmasked character. If
507
* you specify middle of a surrogate pair, the expands
508
* the range to include the following low surrogate.
509
* If omitted or negative value, it means unmasking all
510
* characters after aStart. Specifying same index
511
* throws an exception.
512
* @param aTimeout Optional, specify milliseconds to hide the unmasked
513
* characters if you want to show them temporarily.
514
* If omitted or 0, it means this won't mask the characters
515
* automatically.
516
*/
517
[can_run_script, optional_argc] void unmask(
518
[optional] in unsigned long aStart,
519
[optional] in long long aEnd,
520
[optional] in unsigned long aTimeout);
521
522
/**
523
* mask() is available only when the editor is a password field. This masks
524
* all unmasked characters immediately.
525
*/
526
[can_run_script] void mask();
527
528
/**
529
* These attributes are available only when the editor is a password field.
530
* unmaskedStart is first unmasked character index, or 0 if there is no
531
* unmasked characters.
532
* unmaskedEnd is next index of the last unmasked character. 0 means there
533
* is no unmasked characters.
534
*/
535
readonly attribute unsigned long unmaskedStart;
536
readonly attribute unsigned long unmaskedEnd;
537
538
/**
539
* autoMaskingEnabled is true if unmasked range and newly inputted characters
540
* are masked automatically. That's the default state. If false, until
541
* `mask()` is called, unmasked range and newly inputted characters are
542
* unmasked.
543
*/
544
readonly attribute boolean autoMaskingEnabled;
545
546
/**
547
* passwordMask attribute is a mask character which is used to mask password.
548
*/
549
readonly attribute AString passwordMask;
550
551
/**
552
* The length of the contents in characters.
553
* XXX change this type to 'unsigned long'
554
*/
555
readonly attribute long textLength;
556
557
/** Get and set the body wrap width.
558
*
559
* Special values:
560
* 0 = wrap to window width
561
* -1 = no wrap at all
562
*/
563
attribute long wrapWidth;
564
565
/** Get and set newline handling.
566
*
567
* Values are the constants defined above.
568
*/
569
attribute long newlineHandling;
570
571
/**
572
* Inserts a string at the current location,
573
* given by the selection.
574
* If the selection is not collapsed, the selection is deleted
575
* and the insertion takes place at the resulting collapsed selection.
576
*
577
* @param aString the string to be inserted
578
*/
579
[can_run_script]
580
void insertText(in AString aStringToInsert);
581
582
/**
583
* Insert a line break into the content model.
584
* The interpretation of a break is up to the implementation:
585
* it may enter a character, split a node in the tree, etc.
586
* This may be more efficient than calling InsertText with a newline.
587
*/
588
[can_run_script]
589
void insertLineBreak();
590
591
%{C++
592
/**
593
* AsEditorBase() returns a pointer to EditorBase class.
594
*
595
* In order to avoid circular dependency issues, this method is defined
596
* in mozilla/EditorBase.h. Consumers need to #include that header.
597
*/
598
inline mozilla::EditorBase* AsEditorBase();
599
inline const mozilla::EditorBase* AsEditorBase() const;
600
601
/**
602
* AsTextEditor() returns a pointer to TextEditor class.
603
*
604
* In order to avoid circular dependency issues, this method is defined
605
* in mozilla/TextEditor.h. Consumers need to #include that header.
606
*/
607
inline mozilla::TextEditor* AsTextEditor();
608
inline const mozilla::TextEditor* AsTextEditor() const;
609
610
/**
611
* AsHTMLEditor() returns a pointer to HTMLEditor class.
612
*
613
* In order to avoid circular dependency issues, this method is defined
614
* in mozilla/HTMLEditor.h. Consumers need to #include that header.
615
*/
616
inline mozilla::HTMLEditor* AsHTMLEditor();
617
inline const mozilla::HTMLEditor* AsHTMLEditor() const;
618
%}
619
};