1 : /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* ***** BEGIN LICENSE BLOCK *****
3 : * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 : *
5 : * The contents of this file are subject to the Mozilla Public License Version
6 : * 1.1 (the "License"); you may not use this file except in compliance with
7 : * the License. You may obtain a copy of the License at
8 : * http://www.mozilla.org/MPL/
9 : *
10 : * Software distributed under the License is distributed on an "AS IS" basis,
11 : * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 : * for the specific language governing rights and limitations under the
13 : * License.
14 : *
15 : * The Original Code is mozilla.org code.
16 : *
17 : * The Initial Developer of the Original Code is
18 : * Netscape Communications Corporation.
19 : * Portions created by the Initial Developer are Copyright (C) 1998
20 : * the Initial Developer. All Rights Reserved.
21 : *
22 : * Contributor(s):
23 : * Ms2ger <ms2ger@gmail.com>
24 : *
25 : * Alternatively, the contents of this file may be used under the terms of
26 : * either of the GNU General Public License Version 2 or later (the "GPL"),
27 : * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
28 : * in which case the provisions of the GPL or the LGPL are applicable instead
29 : * of those above. If you wish to allow use of your version of this file only
30 : * under the terms of either the GPL or the LGPL, and not to allow others to
31 : * use your version of this file under the terms of the MPL, indicate your
32 : * decision by deleting the provisions above and replace them with the notice
33 : * and other provisions required by the GPL or the LGPL. If you do not delete
34 : * the provisions above, a recipient may use your version of this file under
35 : * the terms of any one of the MPL, the GPL or the LGPL.
36 : *
37 : * ***** END LICENSE BLOCK ***** */
38 :
39 : #ifndef nsIMutationObserver_h
40 : #define nsIMutationObserver_h
41 :
42 : #include "nsISupports.h"
43 :
44 : class nsIAtom;
45 : class nsIContent;
46 : class nsIDocument;
47 : class nsINode;
48 :
49 : namespace mozilla {
50 : namespace dom {
51 : class Element;
52 : } // namespace dom
53 : } // namespace mozilla
54 :
55 : #define NS_IMUTATION_OBSERVER_IID \
56 : { 0x85eea794, 0xed8e, 0x4e1b, \
57 : { 0xa1, 0x28, 0xd0, 0x93, 0x00, 0xae, 0x51, 0xaa } }
58 :
59 : /**
60 : * Information details about a characterdata change. Basically, we
61 : * view all changes as replacements of a length of text at some offset
62 : * with some other text (of possibly some other length).
63 : */
64 : struct CharacterDataChangeInfo
65 : {
66 : /**
67 : * True if this character data change is just an append.
68 : */
69 : bool mAppend;
70 :
71 : /**
72 : * The offset in the text where the change occurred.
73 : */
74 : PRUint32 mChangeStart;
75 :
76 : /**
77 : * The offset such that mChangeEnd - mChangeStart is equal to the length of
78 : * the text we removed. If this was a pure insert or append, this is equal to
79 : * mChangeStart.
80 : */
81 : PRUint32 mChangeEnd;
82 :
83 : /**
84 : * The length of the text that was inserted in place of the removed text. If
85 : * this was a pure text removal, this is 0.
86 : */
87 : PRUint32 mReplaceLength;
88 :
89 : /**
90 : * The net result is that mChangeStart characters at the beginning of the
91 : * text remained as they were. The next mChangeEnd - mChangeStart characters
92 : * were removed, and mReplaceLength characters were inserted in their place.
93 : * The text that used to begin at mChangeEnd now begins at
94 : * mChangeStart + mReplaceLength.
95 : */
96 :
97 : struct Details {
98 : enum {
99 : eMerge, // two text nodes are merged as a result of normalize()
100 : eSplit // a text node is split as a result of splitText()
101 : } mType;
102 : /**
103 : * For eMerge it's the text node that will be removed, for eSplit it's the
104 : * new text node.
105 : */
106 : nsIContent* mNextSibling;
107 : };
108 :
109 : /**
110 : * Used for splitText() and normalize(), otherwise null.
111 : */
112 : Details* mDetails;
113 : };
114 :
115 : /**
116 : * Mutation observer interface
117 : *
118 : * See nsINode::AddMutationObserver, nsINode::RemoveMutationObserver for how to
119 : * attach or remove your observers.
120 : *
121 : * WARNING: During these notifications, you are not allowed to perform
122 : * any mutations to the current or any other document, or start a
123 : * network load. If you need to perform such operations do that
124 : * during the _last_ nsIDocumentObserver::EndUpdate notification. The
125 : * expection for this is ParentChainChanged, where mutations should be
126 : * done from an async event, as the notification might not be
127 : * surrounded by BeginUpdate/EndUpdate calls.
128 : */
129 : class nsIMutationObserver : public nsISupports
130 9432 : {
131 : public:
132 : NS_DECLARE_STATIC_IID_ACCESSOR(NS_IMUTATION_OBSERVER_IID)
133 :
134 : /**
135 : * Notification that the node value of a data node (text, cdata, pi, comment)
136 : * will be changed.
137 : *
138 : * This notification is not sent when a piece of content is
139 : * added/removed from the document (the other notifications are used
140 : * for that).
141 : *
142 : * @param aDocument The owner-document of aContent. Can be null.
143 : * @param aContent The piece of content that changed. Is never null.
144 : * @param aInfo The structure with information details about the change.
145 : *
146 : * @note Callers of this method might not hold a strong reference to the
147 : * observer. The observer is responsible for making sure it stays
148 : * alive for the duration of the call as needed. The observer may
149 : * assume that this call will happen when there are script blockers on
150 : * the stack.
151 : */
152 : virtual void CharacterDataWillChange(nsIDocument *aDocument,
153 : nsIContent* aContent,
154 : CharacterDataChangeInfo* aInfo) = 0;
155 :
156 : /**
157 : * Notification that the node value of a data node (text, cdata, pi, comment)
158 : * has changed.
159 : *
160 : * This notification is not sent when a piece of content is
161 : * added/removed from the document (the other notifications are used
162 : * for that).
163 : *
164 : * @param aDocument The owner-document of aContent. Can be null.
165 : * @param aContent The piece of content that changed. Is never null.
166 : * @param aInfo The structure with information details about the change.
167 : *
168 : * @note Callers of this method might not hold a strong reference to the
169 : * observer. The observer is responsible for making sure it stays
170 : * alive for the duration of the call as needed. The observer may
171 : * assume that this call will happen when there are script blockers on
172 : * the stack.
173 : */
174 : virtual void CharacterDataChanged(nsIDocument *aDocument,
175 : nsIContent* aContent,
176 : CharacterDataChangeInfo* aInfo) = 0;
177 :
178 : /**
179 : * Notification that an attribute of an element will change. This
180 : * can happen before the BeginUpdate for the change and may not
181 : * always be followed by an AttributeChanged (in particular, if the
182 : * attribute doesn't actually change there will be no corresponding
183 : * AttributeChanged).
184 : *
185 : * @param aDocument The owner-document of aContent. Can be null.
186 : * @param aContent The element whose attribute will change
187 : * @param aNameSpaceID The namespace id of the changing attribute
188 : * @param aAttribute The name of the changing attribute
189 : * @param aModType Whether or not the attribute will be added, changed, or
190 : * removed. The constants are defined in
191 : * nsIDOMMutationEvent.h.
192 : *
193 : * @note Callers of this method might not hold a strong reference to the
194 : * observer. The observer is responsible for making sure it stays
195 : * alive for the duration of the call as needed. The observer may
196 : * assume that this call will happen when there are script blockers on
197 : * the stack.
198 : */
199 : virtual void AttributeWillChange(nsIDocument* aDocument,
200 : mozilla::dom::Element* aElement,
201 : PRInt32 aNameSpaceID,
202 : nsIAtom* aAttribute,
203 : PRInt32 aModType) = 0;
204 :
205 : /**
206 : * Notification that an attribute of an element has changed.
207 : *
208 : * @param aDocument The owner-document of aContent. Can be null.
209 : * @param aElement The element whose attribute changed
210 : * @param aNameSpaceID The namespace id of the changed attribute
211 : * @param aAttribute The name of the changed attribute
212 : * @param aModType Whether or not the attribute was added, changed, or
213 : * removed. The constants are defined in
214 : * nsIDOMMutationEvent.h.
215 : *
216 : * @note Callers of this method might not hold a strong reference to the
217 : * observer. The observer is responsible for making sure it stays
218 : * alive for the duration of the call as needed. The observer may
219 : * assume that this call will happen when there are script blockers on
220 : * the stack.
221 : */
222 : virtual void AttributeChanged(nsIDocument* aDocument,
223 : mozilla::dom::Element* aElement,
224 : PRInt32 aNameSpaceID,
225 : nsIAtom* aAttribute,
226 : PRInt32 aModType) = 0;
227 :
228 : /**
229 : * Notification that one or more content nodes have been appended to the
230 : * child list of another node in the tree.
231 : *
232 : * @param aDocument The owner-document of aContent. Can be null.
233 : * @param aContainer The container that had new children appended. Is never
234 : * null.
235 : * @param aFirstNewContent the node at aIndexInContainer in aContainer.
236 : * @param aNewIndexInContainer the index in the container of the first
237 : * new child
238 : *
239 : * @note Callers of this method might not hold a strong reference to the
240 : * observer. The observer is responsible for making sure it stays
241 : * alive for the duration of the call as needed. The observer may
242 : * assume that this call will happen when there are script blockers on
243 : * the stack.
244 : */
245 : virtual void ContentAppended(nsIDocument *aDocument,
246 : nsIContent* aContainer,
247 : nsIContent* aFirstNewContent,
248 : PRInt32 aNewIndexInContainer) = 0;
249 :
250 : /**
251 : * Notification that a content node has been inserted as child to another
252 : * node in the tree.
253 : *
254 : * @param aDocument The owner-document of aContent, or, when aContainer
255 : * is null, the container that had the child inserted.
256 : * Can be null.
257 : * @param aContainer The container that had new a child inserted. Can be
258 : * null to indicate that the child was inserted into
259 : * aDocument
260 : * @param aChild The newly inserted child.
261 : * @param aIndexInContainer The index in the container of the new child.
262 : *
263 : * @note Callers of this method might not hold a strong reference to the
264 : * observer. The observer is responsible for making sure it stays
265 : * alive for the duration of the call as needed. The observer may
266 : * assume that this call will happen when there are script blockers on
267 : * the stack.
268 : */
269 : virtual void ContentInserted(nsIDocument *aDocument,
270 : nsIContent* aContainer,
271 : nsIContent* aChild,
272 : PRInt32 aIndexInContainer) = 0;
273 :
274 : /**
275 : * Notification that a content node has been removed from the child list of
276 : * another node in the tree.
277 : *
278 : * @param aDocument The owner-document of aContent, or, when aContainer
279 : * is null, the container that had the child removed.
280 : * Can be null.
281 : * @param aContainer The container that had new a child removed. Can be
282 : * null to indicate that the child was removed from
283 : * aDocument.
284 : * @param aChild The child that was removed.
285 : * @param aIndexInContainer The index in the container which the child used
286 : * to have.
287 : * @param aPreviousSibling The previous sibling to the child that was removed.
288 : * Can be null if there was no previous sibling.
289 : *
290 : * @note Callers of this method might not hold a strong reference to the
291 : * observer. The observer is responsible for making sure it stays
292 : * alive for the duration of the call as needed. The observer may
293 : * assume that this call will happen when there are script blockers on
294 : * the stack.
295 : */
296 : virtual void ContentRemoved(nsIDocument *aDocument,
297 : nsIContent* aContainer,
298 : nsIContent* aChild,
299 : PRInt32 aIndexInContainer,
300 : nsIContent* aPreviousSibling) = 0;
301 :
302 : /**
303 : * The node is in the process of being destroyed. Calling QI on the node is
304 : * not supported, however it is possible to get children and flags through
305 : * nsINode as well as calling IsNodeOfType(eCONTENT) and casting to
306 : * nsIContent to get attributes.
307 : *
308 : * NOTE: This notification is only called on observers registered directly
309 : * on the node. This is because when the node is destroyed it can not have
310 : * any ancestors. If you want to know when a descendant node is being
311 : * removed from the observed node, use the ContentRemoved notification.
312 : *
313 : * @param aNode The node being destroyed.
314 : *
315 : * @note Callers of this method might not hold a strong reference to
316 : * the observer. The observer is responsible for making sure it
317 : * stays alive for the duration of the call as needed.
318 : */
319 : virtual void NodeWillBeDestroyed(const nsINode *aNode) = 0;
320 :
321 : /**
322 : * Notification that the node's parent chain has changed. This
323 : * happens when either the node or one of its ancestors is inserted
324 : * or removed as a child of another node.
325 : *
326 : * Note that when a node is inserted this notification is sent to
327 : * all descendants of that node, since all such nodes have their
328 : * parent chain changed.
329 : *
330 : * @param aContent The piece of content that had its parent changed.
331 : *
332 : * @note Callers of this method might not hold a strong reference to
333 : * the observer. The observer is responsible for making sure it
334 : * stays alive for the duration of the call as needed.
335 : */
336 :
337 : virtual void ParentChainChanged(nsIContent *aContent) = 0;
338 : };
339 :
340 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIMutationObserver, NS_IMUTATION_OBSERVER_IID)
341 :
342 : #define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE \
343 : virtual void CharacterDataWillChange(nsIDocument* aDocument, \
344 : nsIContent* aContent, \
345 : CharacterDataChangeInfo* aInfo);
346 :
347 : #define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED \
348 : virtual void CharacterDataChanged(nsIDocument* aDocument, \
349 : nsIContent* aContent, \
350 : CharacterDataChangeInfo* aInfo);
351 :
352 : #define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE \
353 : virtual void AttributeWillChange(nsIDocument* aDocument, \
354 : mozilla::dom::Element* aElement, \
355 : PRInt32 aNameSpaceID, \
356 : nsIAtom* aAttribute, \
357 : PRInt32 aModType);
358 :
359 : #define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED \
360 : virtual void AttributeChanged(nsIDocument* aDocument, \
361 : mozilla::dom::Element* aElement, \
362 : PRInt32 aNameSpaceID, \
363 : nsIAtom* aAttribute, \
364 : PRInt32 aModType);
365 :
366 : #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED \
367 : virtual void ContentAppended(nsIDocument* aDocument, \
368 : nsIContent* aContainer, \
369 : nsIContent* aFirstNewContent, \
370 : PRInt32 aNewIndexInContainer);
371 :
372 : #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED \
373 : virtual void ContentInserted(nsIDocument* aDocument, \
374 : nsIContent* aContainer, \
375 : nsIContent* aChild, \
376 : PRInt32 aIndexInContainer);
377 :
378 : #define NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED \
379 : virtual void ContentRemoved(nsIDocument* aDocument, \
380 : nsIContent* aContainer, \
381 : nsIContent* aChild, \
382 : PRInt32 aIndexInContainer, \
383 : nsIContent* aPreviousSibling);
384 :
385 : #define NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED \
386 : virtual void NodeWillBeDestroyed(const nsINode* aNode);
387 :
388 : #define NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED \
389 : virtual void ParentChainChanged(nsIContent *aContent);
390 :
391 : #define NS_DECL_NSIMUTATIONOBSERVER \
392 : NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE \
393 : NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED \
394 : NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE \
395 : NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED \
396 : NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED \
397 : NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED \
398 : NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED \
399 : NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED \
400 : NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED
401 :
402 : #define NS_IMPL_NSIMUTATIONOBSERVER_CORE_STUB(_class) \
403 : void \
404 : _class::NodeWillBeDestroyed(const nsINode* aNode) \
405 : { \
406 : }
407 :
408 : #define NS_IMPL_NSIMUTATIONOBSERVER_CONTENT(_class) \
409 : void \
410 : _class::CharacterDataWillChange(nsIDocument* aDocument, \
411 : nsIContent* aContent, \
412 : CharacterDataChangeInfo* aInfo) \
413 : { \
414 : } \
415 : void \
416 : _class::CharacterDataChanged(nsIDocument* aDocument, \
417 : nsIContent* aContent, \
418 : CharacterDataChangeInfo* aInfo) \
419 : { \
420 : } \
421 : void \
422 : _class::AttributeWillChange(nsIDocument* aDocument, \
423 : mozilla::dom::Element* aElement, \
424 : PRInt32 aNameSpaceID, \
425 : nsIAtom* aAttribute, \
426 : PRInt32 aModType) \
427 : { \
428 : } \
429 : void \
430 : _class::AttributeChanged(nsIDocument* aDocument, \
431 : mozilla::dom::Element* aElement, \
432 : PRInt32 aNameSpaceID, \
433 : nsIAtom* aAttribute, \
434 : PRInt32 aModType) \
435 : { \
436 : } \
437 : void \
438 : _class::ContentAppended(nsIDocument* aDocument, \
439 : nsIContent* aContainer, \
440 : nsIContent* aFirstNewContent, \
441 : PRInt32 aNewIndexInContainer) \
442 : { \
443 : } \
444 : void \
445 : _class::ContentInserted(nsIDocument* aDocument, \
446 : nsIContent* aContainer, \
447 : nsIContent* aChild, \
448 : PRInt32 aIndexInContainer) \
449 : { \
450 : } \
451 : void \
452 : _class::ContentRemoved(nsIDocument* aDocument, \
453 : nsIContent* aContainer, \
454 : nsIContent* aChild, \
455 : PRInt32 aIndexInContainer, \
456 : nsIContent* aPreviousSibling) \
457 : { \
458 : } \
459 : void \
460 : _class::ParentChainChanged(nsIContent *aContent) \
461 : { \
462 : }
463 :
464 :
465 : #endif /* nsIMutationObserver_h */
|