1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 *
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
10 *
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
14 * License.
15 *
16 * The Original Code is the Mozilla browser.
17 *
18 * The Initial Developer of the Original Code is
19 * Netscape Communications, Inc.
20 * Portions created by the Initial Developer are Copyright (C) 1999
21 * the Initial Developer. All Rights Reserved.
22 *
23 * Contributor(s):
24 * Daniel Glazman <glazman@netscape.com>
25 * Akkana Peck <akkana@netscape.com>
26 *
27 * Alternatively, the contents of this file may be used under the terms of
28 * either of the GNU General Public License Version 2 or later (the "GPL"),
29 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
30 * in which case the provisions of the GPL or the LGPL are applicable instead
31 * of those above. If you wish to allow use of your version of this file only
32 * under the terms of either the GPL or the LGPL, and not to allow others to
33 * use your version of this file under the terms of the MPL, indicate your
34 * decision by deleting the provisions above and replace them with the notice
35 * and other provisions required by the GPL or the LGPL. If you do not delete
36 * the provisions above, a recipient may use your version of this file under
37 * the terms of any one of the MPL, the GPL or the LGPL.
38 *
39 * ***** END LICENSE BLOCK ***** */
40
41 #include "nsISupports.idl"
42 #include "domstubs.idl"
43
44 interface nsIURI;
45 interface nsIAtom;
46 interface nsIContent;
47 interface nsISelection;
48 interface nsISelectionController;
49 interface nsIDocumentStateListener;
50 interface nsIOutputStream;
51 interface nsITransactionManager;
52 interface nsITransaction;
53 interface nsIEditorObserver;
54 interface nsIEditActionListener;
55 interface nsIInlineSpellChecker;
56
57 %{C++
58 class nsIPresShell;
59 typedef short EDirection;
60 %}
61
62 [ptr] native nsIPresShellPtr(nsIPresShell);
63
64 [scriptable, uuid(2f76d0bb-d90d-4454-905e-9b0cc39a701c)]
65
66 interface nsIEditor : nsISupports
67 {
68 %{C++
69 typedef short EDirection;
70 %}
71 const short eNone = 0;
72 const short eNext = 1;
73 const short ePrevious = 2;
74 const short eNextWord = 3;
75 const short ePreviousWord = 4;
76 const short eToBeginningOfLine = 5;
77 const short eToEndOfLine = 6;
78
79 readonly attribute nsISelection selection;
80
81 /**
82 * Init is to tell the implementation of nsIEditor to begin its services
83 * @param aDoc The dom document interface being observed
84 * @param aPresShell TEMP: The presentation shell displaying the document.
85 * Once events can tell us from what pres shell
86 * they originated, this will no longer be
87 * necessary, and the editor will no longer be
88 * linked to a single pres shell.
89 * @param aRoot This is the root of the editable section of this
90 * document. If it is null then we get root
91 * from document body.
92 * @param aSelCon this should be used to get the selection location
93 * @param aFlags A bitmask of flags for specifying the behavior
94 * of the editor.
95 */
96 [noscript] void init(in nsIDOMDocument doc, in nsIPresShellPtr shell,
97 in nsIContent aRoot,
98 in nsISelectionController aSelCon,
99 in unsigned long aFlags);
100
101 void setAttributeOrEquivalent(in nsIDOMElement element,
102 in AString sourceAttrName,
103 in AString sourceAttrValue,
104 in boolean aSuppressTransaction);
105 void removeAttributeOrEquivalent(in nsIDOMElement element,
106 in DOMString sourceAttrName,
107 in boolean aSuppressTransaction);
108
109 /**
110 * postCreate should be called after Init, and is the time that the editor
111 * tells its documentStateObservers that the document has been created.
112 */
113 void postCreate();
114
115 /**
116 * preDestroy is called before the editor goes away, and gives the editor a
117 * chance to tell its documentStateObservers that the document is going away.
118 */
119 void preDestroy();
120
121 /** edit flags for this editor. May be set at any time. */
122 attribute unsigned long flags;
123
124 /**
125 * the MimeType of the document
126 */
127 attribute string contentsMIMEType;
128
129 /** Returns true if we have a document that is not marked read-only */
130 readonly attribute boolean isDocumentEditable;
131
132 /**
133 * the DOM Document this editor is associated with, refcounted.
134 */
135 readonly attribute nsIDOMDocument document;
136
137 /** the body element, i.e. the root of the editable document.
138 */
139 readonly attribute nsIDOMElement rootElement;
140
141 /**
142 * the selection controller for the current presentation, refcounted.
143 */
144 readonly attribute nsISelectionController selectionController;
145
146
147 /* ------------ Selected content removal -------------- */
148
149 /**
150 * DeleteSelection removes all nodes in the current selection.
151 * @param aDir if eNext, delete to the right (for example, the DEL key)
152 * if ePrevious, delete to the left (for example, the BACKSPACE key)
153 */
154 void deleteSelection(in short action);
155
156
157 /* ------------ Document info and file methods -------------- */
158
159 /** Returns true if the document has no *meaningful* content */
160 readonly attribute boolean documentIsEmpty;
161
162 /** Returns true if the document is modifed and needs saving */
163 readonly attribute boolean documentModified;
164
165 /** Sets the current 'Save' document character set */
166 attribute ACString documentCharacterSet;
167
168 /** to be used ONLY when we need to override the doc's modification
169 * state (such as when it's saved).
170 */
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 void incrementModificationCount(in long aModCount);
185
186 /* ------------ Transaction methods -------------- */
187
188 /** transactionManager Get the transaction manager the editor is using.
189 */
190 attribute nsITransactionManager transactionManager;
191
192 /** doTransaction() fires a transaction.
193 * It is provided here so clients can create their own transactions.
194 * If a transaction manager is present, it is used.
195 * Otherwise, the transaction is just executed directly.
196 *
197 * @param aTxn the transaction to execute
198 */
199 void doTransaction(in nsITransaction txn);
200
201
202 /** turn the undo system on or off
203 * @param aEnable if PR_TRUE, the undo system is turned on if available
204 * if PR_FALSE the undo system is turned off if it
205 * was previously on
206 * @return if aEnable is PR_TRUE, returns NS_OK if
207 * the undo system could be initialized properly
208 * if aEnable is PR_FALSE, returns NS_OK.
209 */
210 void enableUndo(in boolean enable);
211
212 /** undo reverses the effects of the last Do operation,
213 * if Undo is enabled in the editor.
214 * It is provided here so clients need no knowledge of whether
215 * the editor has a transaction manager or not.
216 * If a transaction manager is present, it is told to undo,
217 * and the result of that undo is returned.
218 * Otherwise, the Undo request is ignored and an
219 * error NS_ERROR_NOT_AVAILABLE is returned.
220 *
221 */
222 void undo(in unsigned long count);
223
224 /** returns state information about the undo system.
225 * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
226 * @param aCanUndo [OUT] PR_TRUE if at least one transaction is
227 * currently ready to be undone.
228 */
229 void canUndo(out boolean isEnabled, out boolean canUndo);
230
231 /** redo reverses the effects of the last Undo operation
232 * It is provided here so clients need no knowledge of whether
233 * the editor has a transaction manager or not.
234 * If a transaction manager is present, it is told to redo and the
235 * result of the previously undone transaction is reapplied to the document.
236 * If no transaction is available for Redo, or if the document
237 * has no transaction manager, the Redo request is ignored and an
238 * error NS_ERROR_NOT_AVAILABLE is returned.
239 *
240 */
241 void redo(in unsigned long count);
242
243 /** returns state information about the redo system.
244 * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
245 * @param aCanRedo [OUT] PR_TRUE if at least one transaction is
246 currently ready to be redone.
247 */
248 void canRedo(out boolean isEnabled, out boolean canRedo);
249
250 /** beginTransaction is a signal from the caller to the editor that
251 * the caller will execute multiple updates to the content tree
252 * that should be treated as a single logical operation,
253 * in the most efficient way possible.<br>
254 * All transactions executed between a call to beginTransaction and
255 * endTransaction will be undoable as an atomic action.<br>
256 * endTransaction must be called after beginTransaction.<br>
257 * Calls to beginTransaction can be nested, as long as endTransaction
258 * is called once per beginUpdate.
259 */
260 void beginTransaction();
261
262 /** endTransaction is a signal to the editor that the caller is
263 * finished updating the content model.<br>
264 * beginUpdate must be called before endTransaction is called.<br>
265 * Calls to beginTransaction can be nested, as long as endTransaction
266 * is called once per beginTransaction.
267 */
268 void endTransaction();
269
270 void beginPlaceHolderTransaction(in nsIAtom name);
271 void endPlaceHolderTransaction();
272 boolean shouldTxnSetSelection();
273
274 /** Set the flag that prevents insertElementTxn from changing the selection
275 * @param should Set false to suppress changing the selection;
276 * i.e., before using InsertElement() to insert
277 * under <head> element
278 * WARNING: You must be very careful to reset back to PR_TRUE after
279 * setting PR_FALSE, else selection/caret is trashed
280 * for further editing.
281 */
282 void setShouldTxnSetSelection(in boolean should);
283
284 /* ------------ Inline Spell Checking methods -------------- */
285
286 /** Returns the inline spell checker associated with this object. The spell
287 * checker is lazily created, so this function may create the object for
288 * you during this call.
289 * @param autoCreate If true, this will create a spell checker object
290 * if one does not exist yet for this editor. If false
291 * and the object has not been created, this function
292 * WILL RETURN NULL.
293 */
294 nsIInlineSpellChecker getInlineSpellChecker(in boolean autoCreate);
295
296 /** Resyncs spellchecking state (enabled/disabled). This should be called
297 * when anything that affects spellchecking state changes, such as the
298 * spellcheck attribute value.
299 */
300 void syncRealTimeSpell();
301
302 /** Called when the user manually overrides the spellchecking state for this
303 * editor.
304 * @param enable The new state of spellchecking in this editor, as
305 * requested by the user.
306 */
307 void setSpellcheckUserOverride(in boolean enable);
308
309 /* ------------ Clipboard methods -------------- */
310
311 /** cut the currently selected text, putting it into the OS clipboard
312 * What if no text is selected?
313 * What about mixed selections?
314 * What are the clipboard formats?
315 */
316 void cut();
317
318 /** Can we cut? True if the doc is modifiable, and we have a non-
319 * collapsed selection.
320 */
321 boolean canCut();
322
323 /** copy the currently selected text, putting it into the OS clipboard
324 * What if no text is selected?
325 * What about mixed selections?
326 * What are the clipboard formats?
327 */
328 void copy();
329
330 /** Can we copy? True if we have a non-collapsed selection.
331 */
332 boolean canCopy();
333
334 /** paste the text in the OS clipboard at the cursor position, replacing
335 * the selected text (if any)
336 */
337 void paste(in long aSelectionType);
338
339 /** Can we paste? True if the doc is modifiable, and we have
340 * pasteable data in the clipboard.
341 */
342 boolean canPaste(in long aSelectionType);
343
344 /* ------------ Selection methods -------------- */
345
346 /** sets the document selection to the entire contents of the document */
347 void selectAll();
348
349 /** sets the document selection to the beginning of the document */
350 void beginningOfDocument();
351
352 /** sets the document selection to the end of the document */
353 void endOfDocument();
354
355 /* ------------ Drag/Drop methods -------------- */
356
357 /**
358 * canDrag decides if a drag should be started
359 * (for example, based on the current selection and mousepoint).
360 */
361 boolean canDrag(in nsIDOMEvent aEvent);
362
363 /**
364 * doDrag transfers the relevant data (as appropriate)
365 * to a transferable so it can later be dropped.
366 */
367 void doDrag(in nsIDOMEvent aEvent);
368
369 /**
370 * insertFromDrop looks for a dragsession and inserts the
371 * relevant data in response to a drop.
372 */
373 void insertFromDrop(in nsIDOMEvent aEvent);
374
375 /* ------------ Node manipulation methods -------------- */
376
377 /**
378 * setAttribute() sets the attribute of aElement.
379 * No checking is done to see if aAttribute is a legal attribute of the node,
380 * or if aValue is a legal value of aAttribute.
381 *
382 * @param aElement the content element to operate on
383 * @param aAttribute the string representation of the attribute to set
384 * @param aValue the value to set aAttribute to
385 */
386 void setAttribute(in nsIDOMElement aElement, in AString attributestr,
387 in AString attvalue);
388
389 /**
390 * getAttributeValue() retrieves the attribute's value for aElement.
391 *
392 * @param aElement the content element to operate on
393 * @param aAttribute the string representation of the attribute to get
394 * @param aResultValue [OUT] the value of aAttribute.
395 * Only valid if aResultIsSet is PR_TRUE
396 * @return PR_TRUE if aAttribute is set on the current node,
397 * PR_FALSE if it is not.
398 */
399 boolean getAttributeValue(in nsIDOMElement aElement,
400 in AString attributestr,
401 out AString resultValue);
402
403 /**
404 * removeAttribute() deletes aAttribute from the attribute list of aElement.
405 * If aAttribute is not an attribute of aElement, nothing is done.
406 *
407 * @param aElement the content element to operate on
408 * @param aAttribute the string representation of the attribute to get
409 */
410 void removeAttribute(in nsIDOMElement aElement,
411 in AString aAttribute);
412
413 /**
414 * cloneAttribute() copies the attribute from the source node to
415 * the destination node and delete those not in the source.
416 *
417 * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
418 * @param aAttribute the name of the attribute to copy
419 * @param aDestNode the destination element to operate on
420 * @param aSourceNode the source element to copy attributes from
421 * @exception NS_ERROR_NULL_POINTER at least one of the nodes is null
422 * @exception NS_ERROR_NO_INTERFACE at least one of the nodes is not an
423 * element
424 */
425 void cloneAttribute(in AString aAttribute,
426 in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode);
427
428 /**
429 * cloneAttributes() is similar to nsIDOMNode::cloneNode(),
430 * it assures the attribute nodes of the destination are identical
431 * with the source node by copying all existing attributes from the
432 * source and deleting those not in the source.
433 * This is used when the destination node (element) already exists
434 *
435 * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
436 * @param aDestNode the destination element to operate on
437 * @param aSourceNode the source element to copy attributes from
438 */
439 void cloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode);
440
441 /**
442 * createNode instantiates a new element of type aTag and inserts it
443 * into aParent at aPosition.
444 * @param aTag The type of object to create
445 * @param aParent The node to insert the new object into
446 * @param aPosition The place in aParent to insert the new node
447 * @return The node created. Caller must release aNewNode.
448 */
449 nsIDOMNode createNode(in AString tag,
450 in nsIDOMNode parent,
451 in long position);
452
453 /**
454 * insertNode inserts aNode into aParent at aPosition.
455 * No checking is done to verify the legality of the insertion.
456 * That is the responsibility of the caller.
457 * @param aNode The DOM Node to insert.
458 * @param aParent The node to insert the new object into
459 * @param aPosition The place in aParent to insert the new node
460 * 0=first child, 1=second child, etc.
461 * any number > number of current children = last child
462 */
463 void insertNode(in nsIDOMNode node,
464 in nsIDOMNode parent,
465 in long aPosition);
466
467
468 /**
469 * splitNode() creates a new node identical to an existing node,
470 * and split the contents between the two nodes
471 * @param aExistingRightNode the node to split.
472 * It will become the new node's next sibling.
473 * @param aOffset the offset of aExistingRightNode's
474 * content|children to do the split at
475 * @param aNewLeftNode [OUT] the new node resulting from the split,
476 * becomes aExistingRightNode's previous sibling.
477 */
478 void splitNode(in nsIDOMNode existingRightNode,
479 in long offset,
480 out nsIDOMNode newLeftNode);
481
482 /**
483 * joinNodes() takes 2 nodes and merge their content|children.
484 * @param aLeftNode The left node. It will be deleted.
485 * @param aRightNode The right node. It will remain after the join.
486 * @param aParent The parent of aExistingRightNode
487 *
488 * There is no requirement that the two nodes be
489 * of the same type. However, a text node can be
490 * merged only with another text node.
491 */
492 void joinNodes(in nsIDOMNode leftNode,
493 in nsIDOMNode rightNode,
494 in nsIDOMNode parent);
495
496 /**
497 * deleteNode removes aChild from aParent.
498 * @param aChild The node to delete
499 */
500 void deleteNode(in nsIDOMNode child);
501
502 /**
503 * markNodeDirty() sets a special dirty attribute on the node.
504 * Usually this will be called immediately after creating a new node.
505 * @param aNode The node for which to insert formatting.
506 */
507 void markNodeDirty(in nsIDOMNode node);
508
509 /* ---------- direction controller ---------- */
510
511 /**
512 * Switches the editor element direction; from "Left-to-Right" to
513 * "Right-to-Left", and vice versa.
514 */
515 void switchTextDirection();
516
517 /* ------------ Output methods -------------- */
518
519 /**
520 * Output methods:
521 * aFormatType is a mime type, like text/plain.
522 */
523 AString outputToString(in AString formatType,
524 in unsigned long flags);
525 void outputToStream(in nsIOutputStream aStream,
526 in AString formatType,
527 in ACString charsetOverride,
528 in unsigned long flags);
529
530
531 /* ------------ Various listeners methods --------------
532 * nsIEditor holds strong references to the editor observers, action listeners
533 * and document state listeners.
534 */
535
536 /** add an EditorObserver to the editors list of observers. */
537 void addEditorObserver(in nsIEditorObserver observer);
538
539 /** Remove an EditorObserver from the editor's list of observers. */
540 void removeEditorObserver(in nsIEditorObserver observer);
541
542 /** add an EditActionListener to the editors list of listeners. */
543 void addEditActionListener(in nsIEditActionListener listener);
544
545 /** Remove an EditActionListener from the editor's list of listeners. */
546 void removeEditActionListener(in nsIEditActionListener listener);
547
548 /** Add a DocumentStateListener to the editors list of doc state listeners. */
549 void addDocumentStateListener(in nsIDocumentStateListener listener);
550
551 /** Remove a DocumentStateListener to the editors list of doc state listeners. */
552 void removeDocumentStateListener(in nsIDocumentStateListener listener);
553
554
555 /* ------------ Debug methods -------------- */
556
557 /**
558 * And a debug method -- show us what the tree looks like right now
559 */
560 void dumpContentTree();
561
562 /** Dumps a text representation of the content tree to standard out */
563 void debugDumpContent() ;
564
565 /* Run unit tests. Noop in optimized builds */
566 void debugUnitTests(out long outNumTests, out long outNumTestsFailed);
567
568 /* checks if a node is read-only or not */
569 [notxpcom] boolean isModifiableNode(in nsIDOMNode aNode);
570 };