summaryrefslogtreecommitdiff
path: root/editor/nsIEditor.idl
blob: bb9026d0eeb6d599d70ba7a025b16f2c56cf5f8e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "domstubs.idl"

interface nsIURI;
interface nsIAtom;
interface nsIContent;
interface nsISelection;
interface nsISelectionController;
interface nsIDocumentStateListener;
interface nsIOutputStream;
interface nsITransactionManager;
interface nsITransaction;
interface nsIEditorObserver;
interface nsIEditActionListener;
interface nsIInlineSpellChecker;
interface nsITransferable;

[scriptable, uuid(094be624-f0bf-400f-89e2-6a84baab9474)]
interface nsIEditor  : nsISupports
{
%{C++
  typedef short EDirection;
  typedef short EStripWrappers;
%}
  const short eNone = 0;
  const short eNext = 1;
  const short ePrevious = 2;
  const short eNextWord = 3;
  const short ePreviousWord = 4;
  const short eToBeginningOfLine = 5;
  const short eToEndOfLine = 6;

  const short eStrip = 0;
  const short eNoStrip = 1;

  readonly attribute nsISelection selection;

  /**
   * Finalizes selection and caret for the editor.
   */
  [noscript] void finalizeSelection();

  /**
   * Init is to tell the implementation of nsIEditor to begin its services
   * @param aDoc          The dom document interface being observed
   * @param aRoot         This is the root of the editable section of this
   *                      document. If it is null then we get root
   *                      from document body.
   * @param aSelCon       this should be used to get the selection location
   *                      (will be null for HTML editors)
   * @param aFlags        A bitmask of flags for specifying the behavior
   *                      of the editor.
   */
  [noscript] void init(in nsIDOMDocument doc,
                       in nsIContent aRoot,
                       in nsISelectionController aSelCon,
                       in unsigned long aFlags,
                       in AString initialValue);

  void setAttributeOrEquivalent(in nsIDOMElement element,
                                in AString sourceAttrName,
                                in AString sourceAttrValue,
                                in boolean aSuppressTransaction);
  void removeAttributeOrEquivalent(in nsIDOMElement element,
                                   in DOMString sourceAttrName,
                                   in boolean aSuppressTransaction);

  /**
   * postCreate should be called after Init, and is the time that the editor
   * tells its documentStateObservers that the document has been created.
   */
  void postCreate();

  /**
   * preDestroy is called before the editor goes away, and gives the editor a
   * chance to tell its documentStateObservers that the document is going away.
   * @param aDestroyingFrames set to true when the frames being edited
   * are being destroyed (so there is no need to modify any nsISelections,
   * nor is it safe to do so)
   */
  void preDestroy(in boolean aDestroyingFrames);

  /** edit flags for this editor.  May be set at any time. */
  attribute unsigned long flags;

  /**
   * the MimeType of the document
   */
  attribute string contentsMIMEType;

  /** Returns true if we have a document that is not marked read-only */
  readonly attribute boolean isDocumentEditable;

  /** Returns true if the current selection anchor is editable */
  readonly attribute boolean isSelectionEditable;

  /**
   * the DOM Document this editor is associated with, refcounted.
   */
  readonly attribute nsIDOMDocument document;

  /** the body element, i.e. the root of the editable document.
   */
  readonly attribute  nsIDOMElement rootElement;

  /**
   * the selection controller for the current presentation, refcounted.
   */
  readonly attribute nsISelectionController selectionController;


  /* ------------ Selected content removal -------------- */

  /**
   * DeleteSelection removes all nodes in the current selection.
   * @param aDir  if eNext, delete to the right (for example, the DEL key)
   *              if ePrevious, delete to the left (for example, the BACKSPACE key)
   * @param stripWrappers If eStrip, strip any empty inline elements left
   *                      behind after the deletion; if eNoStrip, don't.  If in
   *                      doubt, pass eStrip -- eNoStrip is only for if you're
   *                      about to insert text or similar right after.
   */
  void deleteSelection(in short action, in short stripWrappers);


  /* ------------ Document info and file methods -------------- */

  /** Returns true if the document has no *meaningful* content */
  readonly attribute boolean documentIsEmpty;

  /** Returns true if the document is modifed and needs saving */
  readonly attribute boolean documentModified;

  /** Sets the current 'Save' document character set */
  attribute ACString documentCharacterSet;

  /** to be used ONLY when we need to override the doc's modification
    * state (such as when it's saved).
    */
  void resetModificationCount();

  /** Gets the modification count of the document we are editing.
    * @return the modification count of the document being edited.
    *         Zero means unchanged.
    */
  long getModificationCount();

  /** called each time we modify the document.
    * Increments the modification count of the document.
    * @param  aModCount  the number of modifications by which
    *                    to increase or decrease the count
    */
  void incrementModificationCount(in long aModCount);

  /* ------------ Transaction methods -------------- */

  /** transactionManager Get the transaction manager the editor is using.
    */
  attribute nsITransactionManager transactionManager;

  /** doTransaction() fires a transaction.
    * It is provided here so clients can create their own transactions.
    * If a transaction manager is present, it is used.
    * Otherwise, the transaction is just executed directly.
    *
    * @param aTxn the transaction to execute
    */
  void doTransaction(in nsITransaction txn);


  /** turn the undo system on or off
    * @param aEnable  if PR_TRUE, the undo system is turned on if available
    *                 if PR_FALSE the undo system is turned off if it
    *                 was previously on
    * @return         if aEnable is PR_TRUE, returns NS_OK if
    *                 the undo system could be initialized properly
    *                 if aEnable is PR_FALSE, returns NS_OK.
    */
  void enableUndo(in boolean enable);

  /**
   * The number of items on the undo stack.
   */
  readonly attribute long numberOfUndoItems;

  /**
   * The number of items on the redo stack.
   */
  readonly attribute long numberOfRedoItems;

  /** undo reverses the effects of the last Do operation,
    * if Undo is enabled in the editor.
    * It is provided here so clients need no knowledge of whether
    * the editor has a transaction manager or not.
    * If a transaction manager is present, it is told to undo,
    * and the result of that undo is returned.
    * Otherwise, the Undo request is ignored and an
    * error NS_ERROR_NOT_AVAILABLE is returned.
    *
    */
  void undo(in unsigned long count);

  /** returns state information about the undo system.
    * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
    * @param aCanUndo   [OUT] PR_TRUE if at least one transaction is
    *                         currently ready to be undone.
    */
  void canUndo(out boolean isEnabled, out boolean canUndo);

  /** redo reverses the effects of the last Undo operation
    * It is provided here so clients need no knowledge of whether
    * the editor has a transaction manager or not.
    * If a transaction manager is present, it is told to redo and the
    * result of the previously undone transaction is reapplied to the document.
    * If no transaction is available for Redo, or if the document
    * has no transaction manager, the Redo request is ignored and an
    * error NS_ERROR_NOT_AVAILABLE is returned.
    *
    */
  void redo(in unsigned long count);

  /** returns state information about the redo system.
    * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
    * @param aCanRedo   [OUT] PR_TRUE if at least one transaction is
                              currently ready to be redone.
    */
  void canRedo(out boolean isEnabled, out boolean canRedo);

  /** beginTransaction is a signal from the caller to the editor that
    * the caller will execute multiple updates to the content tree
    * that should be treated as a single logical operation,
    * in the most efficient way possible.<br>
    * All transactions executed between a call to beginTransaction and
    * endTransaction will be undoable as an atomic action.<br>
    * endTransaction must be called after beginTransaction.<br>
    * Calls to beginTransaction can be nested, as long as endTransaction
    * is called once per beginUpdate.
    */
  void beginTransaction();

  /** endTransaction is a signal to the editor that the caller is
    * finished updating the content model.<br>
    * beginUpdate must be called before endTransaction is called.<br>
    * Calls to beginTransaction can be nested, as long as endTransaction
    * is called once per beginTransaction.
    */
  void endTransaction();

  void beginPlaceHolderTransaction(in nsIAtom name);
  void endPlaceHolderTransaction();
  boolean shouldTxnSetSelection();

  /** Set the flag that prevents insertElementTxn from changing the selection
    * @param   should  Set false to suppress changing the selection;
    *                  i.e., before using InsertElement() to insert
    *                  under <head> element
    * WARNING: You must be very careful to reset back to PR_TRUE after
    *          setting PR_FALSE, else selection/caret is trashed
    *          for further editing.
    */
  void setShouldTxnSetSelection(in boolean should);

  /* ------------ Inline Spell Checking methods -------------- */

  /** Returns the inline spell checker associated with this object. The spell
    * checker is lazily created, so this function may create the object for
    * you during this call.
    * @param  autoCreate  If true, this will create a spell checker object
    *                     if one does not exist yet for this editor. If false
    *                     and the object has not been created, this function
    *                     WILL RETURN NULL.
    */
  nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);

  /** Resyncs spellchecking state (enabled/disabled).  This should be called
    * when anything that affects spellchecking state changes, such as the
    * spellcheck attribute value.
    */
  void syncRealTimeSpell();

  /** Called when the user manually overrides the spellchecking state for this
    * editor.
    * @param  enable  The new state of spellchecking in this editor, as
    *                 requested by the user.
    */
  void setSpellcheckUserOverride(in boolean enable);

  /* ------------ Clipboard methods -------------- */

  /** cut the currently selected text, putting it into the OS clipboard
    * What if no text is selected?
    * What about mixed selections?
    * What are the clipboard formats?
    */
  void cut();

  /** Can we cut? True if the doc is modifiable, and we have a non-
    * collapsed selection.
    */
  boolean canCut();

  /** copy the currently selected text, putting it into the OS clipboard
    * What if no text is selected?
    * What about mixed selections?
    * What are the clipboard formats?
    */
  void copy();

  /** Can we copy? True if we have a non-collapsed selection.
    */
  boolean canCopy();

  /** Can we delete? True if we have a non-collapsed selection.
    */
  boolean canDelete();

  /** paste the text in the OS clipboard at the cursor position, replacing
    * the selected text (if any)
    */
  void paste(in long aSelectionType);

  /** Paste the text in |aTransferable| at the cursor position, replacing the
    * selected text (if any).
    */
  void pasteTransferable(in nsITransferable aTransferable);

  /** Can we paste? True if the doc is modifiable, and we have
    * pasteable data in the clipboard.
    */
  boolean canPaste(in long aSelectionType);

  /** Can we paste |aTransferable| or, if |aTransferable| is null, will a call
    * to pasteTransferable later possibly succeed if given an instance of
    * nsITransferable then? True if the doc is modifiable, and, if
    * |aTransfeable| is non-null, we have pasteable data in |aTransfeable|.
    */
  boolean canPasteTransferable([optional] in nsITransferable aTransferable);

  /* ------------ Selection methods -------------- */

  /** sets the document selection to the entire contents of the document */
  void selectAll();

  /** sets the document selection to the beginning of the document */
  void beginningOfDocument();

  /** sets the document selection to the end of the document */
  void endOfDocument();

  /* ------------ Node manipulation methods -------------- */

  /**
   * setAttribute() sets the attribute of aElement.
   * No checking is done to see if aAttribute is a legal attribute of the node,
   * or if aValue is a legal value of aAttribute.
   *
   * @param aElement    the content element to operate on
   * @param aAttribute  the string representation of the attribute to set
   * @param aValue      the value to set aAttribute to
   */
  void setAttribute(in nsIDOMElement aElement, in AString attributestr,
                    in AString attvalue);

  /**
   * getAttributeValue() retrieves the attribute's value for aElement.
   *
   * @param aElement      the content element to operate on
   * @param aAttribute    the string representation of the attribute to get
   * @param aResultValue  [OUT] the value of aAttribute.
   *                      Only valid if aResultIsSet is PR_TRUE
   * @return              PR_TRUE if aAttribute is set on the current node,
   *                      PR_FALSE if it is not.
   */
  boolean getAttributeValue(in nsIDOMElement aElement,
                            in AString attributestr,
                            out AString resultValue);

  /**
   * removeAttribute() deletes aAttribute from the attribute list of aElement.
   * If aAttribute is not an attribute of aElement, nothing is done.
   *
   * @param aElement      the content element to operate on
   * @param aAttribute    the string representation of the attribute to get
   */
  void removeAttribute(in nsIDOMElement aElement,
                       in AString aAttribute);

  /**
   * cloneAttribute() copies the attribute from the source node to
   * the destination node and delete those not in the source.
   *
   * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
   * @param aAttribute    the name of the attribute to copy
   * @param aDestNode     the destination element to operate on
   * @param aSourceNode   the source element to copy attributes from
   * @exception NS_ERROR_NULL_POINTER at least one of the nodes is null
   * @exception NS_ERROR_NO_INTERFACE at least one of the nodes is not an
   *                                  element
   */
  void cloneAttribute(in AString aAttribute,
                      in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode);

  /**
   * cloneAttributes() is similar to nsIDOMNode::cloneNode(),
   *   it assures the attribute nodes of the destination are identical
   *   with the source node by copying all existing attributes from the
   *   source and deleting those not in the source.
   *   This is used when the destination node (element) already exists
   *
   * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
   * @param aDestNode     the destination element to operate on
   * @param aSourceNode   the source element to copy attributes from
   */
  void cloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode);

  /**
   * createNode instantiates a new element of type aTag and inserts it
   * into aParent at aPosition.
   * @param aTag      The type of object to create
   * @param aParent   The node to insert the new object into
   * @param aPosition The place in aParent to insert the new node
   * @return          The node created.  Caller must release aNewNode.
   */
  nsIDOMNode createNode(in AString tag,
                        in nsIDOMNode parent,
                        in long position);

  /**
   * insertNode inserts aNode into aParent at aPosition.
   * No checking is done to verify the legality of the insertion.
   * That is the responsibility of the caller.
   * @param aNode     The DOM Node to insert.
   * @param aParent   The node to insert the new object into
   * @param aPosition The place in aParent to insert the new node
   *                  0=first child, 1=second child, etc.
   *                  any number > number of current children = last child
   */
  void insertNode(in nsIDOMNode node,
                  in nsIDOMNode parent,
                  in long       aPosition);


  /**
   * splitNode() creates a new node identical to an existing node,
   * and split the contents between the two nodes
   * @param aExistingRightNode   the node to split.
   *                             It will become the new node's next sibling.
   * @param aOffset              the offset of aExistingRightNode's
   *                             content|children to do the split at
   * @param aNewLeftNode         [OUT] the new node resulting from the split,
   *                             becomes aExistingRightNode's previous sibling.
   */
  void splitNode(in nsIDOMNode existingRightNode,
                 in long      offset,
                 out nsIDOMNode newLeftNode);

  /**
   * joinNodes() takes 2 nodes and merge their content|children.
   * @param aLeftNode     The left node.  It will be deleted.
   * @param aRightNode    The right node. It will remain after the join.
   * @param aParent       The parent of aExistingRightNode
   *
   *                      There is no requirement that the two nodes be
   *                      of the same type.  However, a text node can be
   *                      merged only with another text node.
   */
  void joinNodes(in nsIDOMNode leftNode,
                 in nsIDOMNode rightNode,
                 in nsIDOMNode parent);

  /**
   * deleteNode removes aChild from aParent.
   * @param aChild    The node to delete
   */
  void deleteNode(in nsIDOMNode child);

  /**
   * Returns true if markNodeDirty() has any effect.  Returns false if
   * markNodeDirty() is a no-op.
   */
  [notxpcom] boolean outputsMozDirty();

  /**
   * markNodeDirty() sets a special dirty attribute on the node.
   * Usually this will be called immediately after creating a new node.
   * @param aNode      The node for which to insert formatting.
   */
  void markNodeDirty(in nsIDOMNode node);

/* ---------- direction controller ---------- */

  /**
   * Switches the editor element direction; from "Left-to-Right" to
   * "Right-to-Left", and vice versa.
   */
  void switchTextDirection();

/* ------------ Output methods -------------- */

  /**
   * Output methods:
   * aFormatType is a mime type, like text/plain.
   */
  AString outputToString(in AString formatType,
                         in unsigned long flags);
  void outputToStream(in nsIOutputStream aStream,
                      in AString formatType,
                      in ACString charsetOverride,
                      in unsigned long flags);


  /* ------------ Various listeners methods --------------
   * nsIEditor holds strong references to the editor observers, action listeners
   * and document state listeners.
   */

  /** add an EditorObserver to the editors list of observers. */
  void addEditorObserver(in nsIEditorObserver observer);

  /** Remove an EditorObserver from the editor's list of observers. */
  void removeEditorObserver(in nsIEditorObserver observer);

  /** add an EditActionListener to the editors list of listeners. */
  void addEditActionListener(in nsIEditActionListener listener);

  /** Remove an EditActionListener from the editor's list of listeners. */
  void removeEditActionListener(in nsIEditActionListener listener);

  /** Add a DocumentStateListener to the editors list of doc state listeners. */
  void addDocumentStateListener(in nsIDocumentStateListener listener);

  /** Remove a DocumentStateListener to the editors list of doc state listeners. */
  void removeDocumentStateListener(in nsIDocumentStateListener listener);


  /* ------------ Debug methods -------------- */

  /**
   * And a debug method -- show us what the tree looks like right now
   */
  void dumpContentTree();

  /** Dumps a text representation of the content tree to standard out */
  void debugDumpContent() ;

  /* Run unit tests. Noop in optimized builds */
  void debugUnitTests(out long outNumTests, out long  outNumTestsFailed);

  /* checks if a node is read-only or not */
  [notxpcom] boolean isModifiableNode(in nsIDOMNode aNode);

  /* Set true if you want to suppress dispatching input event. */
  attribute boolean suppressDispatchingInputEvent;

  /**
   * True if an edit action is being handled (in other words, between calls of
   * nsIEditorObserver::BeforeEditAction() and nsIEditorObserver::EditAction()
   * or nsIEditorObserver::CancelEditAction().  Otherwise, false.
   */
  [noscript] readonly attribute boolean isInEditAction;
};