1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/content/base/public/nsIMutationObserver.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,446 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef nsIMutationObserver_h
1.10 +#define nsIMutationObserver_h
1.11 +
1.12 +#include "nsISupports.h"
1.13 +
1.14 +class nsIAtom;
1.15 +class nsIContent;
1.16 +class nsIDocument;
1.17 +class nsINode;
1.18 +
1.19 +namespace mozilla {
1.20 +namespace dom {
1.21 +class Element;
1.22 +} // namespace dom
1.23 +} // namespace mozilla
1.24 +
1.25 +#define NS_IMUTATION_OBSERVER_IID \
1.26 +{ 0x16fe5e3e, 0xeadc, 0x4312, \
1.27 + { 0x9d, 0x44, 0xb6, 0xbe, 0xdd, 0x6b, 0x54, 0x74 } }
1.28 +
1.29 +/**
1.30 + * Information details about a characterdata change. Basically, we
1.31 + * view all changes as replacements of a length of text at some offset
1.32 + * with some other text (of possibly some other length).
1.33 + */
1.34 +struct CharacterDataChangeInfo
1.35 +{
1.36 + /**
1.37 + * True if this character data change is just an append.
1.38 + */
1.39 + bool mAppend;
1.40 +
1.41 + /**
1.42 + * The offset in the text where the change occurred.
1.43 + */
1.44 + uint32_t mChangeStart;
1.45 +
1.46 + /**
1.47 + * The offset such that mChangeEnd - mChangeStart is equal to the length of
1.48 + * the text we removed. If this was a pure insert or append, this is equal to
1.49 + * mChangeStart.
1.50 + */
1.51 + uint32_t mChangeEnd;
1.52 +
1.53 + /**
1.54 + * The length of the text that was inserted in place of the removed text. If
1.55 + * this was a pure text removal, this is 0.
1.56 + */
1.57 + uint32_t mReplaceLength;
1.58 +
1.59 + /**
1.60 + * The net result is that mChangeStart characters at the beginning of the
1.61 + * text remained as they were. The next mChangeEnd - mChangeStart characters
1.62 + * were removed, and mReplaceLength characters were inserted in their place.
1.63 + * The text that used to begin at mChangeEnd now begins at
1.64 + * mChangeStart + mReplaceLength.
1.65 + */
1.66 +
1.67 + struct Details {
1.68 + enum {
1.69 + eMerge, // two text nodes are merged as a result of normalize()
1.70 + eSplit // a text node is split as a result of splitText()
1.71 + } mType;
1.72 + /**
1.73 + * For eMerge it's the text node that will be removed, for eSplit it's the
1.74 + * new text node.
1.75 + */
1.76 + nsIContent* mNextSibling;
1.77 + };
1.78 +
1.79 + /**
1.80 + * Used for splitText() and normalize(), otherwise null.
1.81 + */
1.82 + Details* mDetails;
1.83 +};
1.84 +
1.85 +/**
1.86 + * Mutation observer interface
1.87 + *
1.88 + * See nsINode::AddMutationObserver, nsINode::RemoveMutationObserver for how to
1.89 + * attach or remove your observers.
1.90 + *
1.91 + * WARNING: During these notifications, you are not allowed to perform
1.92 + * any mutations to the current or any other document, or start a
1.93 + * network load. If you need to perform such operations do that
1.94 + * during the _last_ nsIDocumentObserver::EndUpdate notification. The
1.95 + * expection for this is ParentChainChanged, where mutations should be
1.96 + * done from an async event, as the notification might not be
1.97 + * surrounded by BeginUpdate/EndUpdate calls.
1.98 + */
1.99 +class nsIMutationObserver : public nsISupports
1.100 +{
1.101 +public:
1.102 + NS_DECLARE_STATIC_IID_ACCESSOR(NS_IMUTATION_OBSERVER_IID)
1.103 +
1.104 + /**
1.105 + * Notification that the node value of a data node (text, cdata, pi, comment)
1.106 + * will be changed.
1.107 + *
1.108 + * This notification is not sent when a piece of content is
1.109 + * added/removed from the document (the other notifications are used
1.110 + * for that).
1.111 + *
1.112 + * @param aDocument The owner-document of aContent. Can be null.
1.113 + * @param aContent The piece of content that changed. Is never null.
1.114 + * @param aInfo The structure with information details about the change.
1.115 + *
1.116 + * @note Callers of this method might not hold a strong reference to the
1.117 + * observer. The observer is responsible for making sure it stays
1.118 + * alive for the duration of the call as needed. The observer may
1.119 + * assume that this call will happen when there are script blockers on
1.120 + * the stack.
1.121 + */
1.122 + virtual void CharacterDataWillChange(nsIDocument *aDocument,
1.123 + nsIContent* aContent,
1.124 + CharacterDataChangeInfo* aInfo) = 0;
1.125 +
1.126 + /**
1.127 + * Notification that the node value of a data node (text, cdata, pi, comment)
1.128 + * has changed.
1.129 + *
1.130 + * This notification is not sent when a piece of content is
1.131 + * added/removed from the document (the other notifications are used
1.132 + * for that).
1.133 + *
1.134 + * @param aDocument The owner-document of aContent. Can be null.
1.135 + * @param aContent The piece of content that changed. Is never null.
1.136 + * @param aInfo The structure with information details about the change.
1.137 + *
1.138 + * @note Callers of this method might not hold a strong reference to the
1.139 + * observer. The observer is responsible for making sure it stays
1.140 + * alive for the duration of the call as needed. The observer may
1.141 + * assume that this call will happen when there are script blockers on
1.142 + * the stack.
1.143 + */
1.144 + virtual void CharacterDataChanged(nsIDocument *aDocument,
1.145 + nsIContent* aContent,
1.146 + CharacterDataChangeInfo* aInfo) = 0;
1.147 +
1.148 + /**
1.149 + * Notification that an attribute of an element will change. This
1.150 + * can happen before the BeginUpdate for the change and may not
1.151 + * always be followed by an AttributeChanged (in particular, if the
1.152 + * attribute doesn't actually change there will be no corresponding
1.153 + * AttributeChanged).
1.154 + *
1.155 + * @param aDocument The owner-document of aContent. Can be null.
1.156 + * @param aContent The element whose attribute will change
1.157 + * @param aNameSpaceID The namespace id of the changing attribute
1.158 + * @param aAttribute The name of the changing attribute
1.159 + * @param aModType Whether or not the attribute will be added, changed, or
1.160 + * removed. The constants are defined in
1.161 + * nsIDOMMutationEvent.h.
1.162 + *
1.163 + * @note Callers of this method might not hold a strong reference to the
1.164 + * observer. The observer is responsible for making sure it stays
1.165 + * alive for the duration of the call as needed. The observer may
1.166 + * assume that this call will happen when there are script blockers on
1.167 + * the stack.
1.168 + */
1.169 + virtual void AttributeWillChange(nsIDocument* aDocument,
1.170 + mozilla::dom::Element* aElement,
1.171 + int32_t aNameSpaceID,
1.172 + nsIAtom* aAttribute,
1.173 + int32_t aModType) = 0;
1.174 +
1.175 + /**
1.176 + * Notification that an attribute of an element has changed.
1.177 + *
1.178 + * @param aDocument The owner-document of aContent. Can be null.
1.179 + * @param aElement The element whose attribute changed
1.180 + * @param aNameSpaceID The namespace id of the changed attribute
1.181 + * @param aAttribute The name of the changed attribute
1.182 + * @param aModType Whether or not the attribute was added, changed, or
1.183 + * removed. The constants are defined in
1.184 + * nsIDOMMutationEvent.h.
1.185 + *
1.186 + * @note Callers of this method might not hold a strong reference to the
1.187 + * observer. The observer is responsible for making sure it stays
1.188 + * alive for the duration of the call as needed. The observer may
1.189 + * assume that this call will happen when there are script blockers on
1.190 + * the stack.
1.191 + */
1.192 + virtual void AttributeChanged(nsIDocument* aDocument,
1.193 + mozilla::dom::Element* aElement,
1.194 + int32_t aNameSpaceID,
1.195 + nsIAtom* aAttribute,
1.196 + int32_t aModType) = 0;
1.197 +
1.198 + /**
1.199 + * Notification that an attribute of an element has been
1.200 + * set to the value it already had.
1.201 + *
1.202 + * @param aDocument The owner-document of aContent.
1.203 + * @param aElement The element whose attribute changed
1.204 + * @param aNameSpaceID The namespace id of the changed attribute
1.205 + * @param aAttribute The name of the changed attribute
1.206 + */
1.207 + virtual void AttributeSetToCurrentValue(nsIDocument* aDocument,
1.208 + mozilla::dom::Element* aElement,
1.209 + int32_t aNameSpaceID,
1.210 + nsIAtom* aAttribute) {}
1.211 +
1.212 + /**
1.213 + * Notification that one or more content nodes have been appended to the
1.214 + * child list of another node in the tree.
1.215 + *
1.216 + * @param aDocument The owner-document of aContent. Can be null.
1.217 + * @param aContainer The container that had new children appended. Is never
1.218 + * null.
1.219 + * @param aFirstNewContent the node at aIndexInContainer in aContainer.
1.220 + * @param aNewIndexInContainer the index in the container of the first
1.221 + * new child
1.222 + *
1.223 + * @note Callers of this method might not hold a strong reference to the
1.224 + * observer. The observer is responsible for making sure it stays
1.225 + * alive for the duration of the call as needed. The observer may
1.226 + * assume that this call will happen when there are script blockers on
1.227 + * the stack.
1.228 + */
1.229 + virtual void ContentAppended(nsIDocument *aDocument,
1.230 + nsIContent* aContainer,
1.231 + nsIContent* aFirstNewContent,
1.232 + int32_t aNewIndexInContainer) = 0;
1.233 +
1.234 + /**
1.235 + * Notification that a content node has been inserted as child to another
1.236 + * node in the tree.
1.237 + *
1.238 + * @param aDocument The owner-document of aContent, or, when aContainer
1.239 + * is null, the container that had the child inserted.
1.240 + * Can be null.
1.241 + * @param aContainer The container that had new a child inserted. Can be
1.242 + * null to indicate that the child was inserted into
1.243 + * aDocument
1.244 + * @param aChild The newly inserted child.
1.245 + * @param aIndexInContainer The index in the container of the new child.
1.246 + *
1.247 + * @note Callers of this method might not hold a strong reference to the
1.248 + * observer. The observer is responsible for making sure it stays
1.249 + * alive for the duration of the call as needed. The observer may
1.250 + * assume that this call will happen when there are script blockers on
1.251 + * the stack.
1.252 + */
1.253 + virtual void ContentInserted(nsIDocument *aDocument,
1.254 + nsIContent* aContainer,
1.255 + nsIContent* aChild,
1.256 + int32_t aIndexInContainer) = 0;
1.257 +
1.258 + /**
1.259 + * Notification that a content node has been removed from the child list of
1.260 + * another node in the tree.
1.261 + *
1.262 + * @param aDocument The owner-document of aContent, or, when aContainer
1.263 + * is null, the container that had the child removed.
1.264 + * Can be null.
1.265 + * @param aContainer The container that had new a child removed. Can be
1.266 + * null to indicate that the child was removed from
1.267 + * aDocument.
1.268 + * @param aChild The child that was removed.
1.269 + * @param aIndexInContainer The index in the container which the child used
1.270 + * to have.
1.271 + * @param aPreviousSibling The previous sibling to the child that was removed.
1.272 + * Can be null if there was no previous sibling.
1.273 + *
1.274 + * @note Callers of this method might not hold a strong reference to the
1.275 + * observer. The observer is responsible for making sure it stays
1.276 + * alive for the duration of the call as needed. The observer may
1.277 + * assume that this call will happen when there are script blockers on
1.278 + * the stack.
1.279 + */
1.280 + virtual void ContentRemoved(nsIDocument *aDocument,
1.281 + nsIContent* aContainer,
1.282 + nsIContent* aChild,
1.283 + int32_t aIndexInContainer,
1.284 + nsIContent* aPreviousSibling) = 0;
1.285 +
1.286 + /**
1.287 + * The node is in the process of being destroyed. Calling QI on the node is
1.288 + * not supported, however it is possible to get children and flags through
1.289 + * nsINode as well as calling IsNodeOfType(eCONTENT) and casting to
1.290 + * nsIContent to get attributes.
1.291 + *
1.292 + * NOTE: This notification is only called on observers registered directly
1.293 + * on the node. This is because when the node is destroyed it can not have
1.294 + * any ancestors. If you want to know when a descendant node is being
1.295 + * removed from the observed node, use the ContentRemoved notification.
1.296 + *
1.297 + * @param aNode The node being destroyed.
1.298 + *
1.299 + * @note Callers of this method might not hold a strong reference to
1.300 + * the observer. The observer is responsible for making sure it
1.301 + * stays alive for the duration of the call as needed.
1.302 + */
1.303 + virtual void NodeWillBeDestroyed(const nsINode *aNode) = 0;
1.304 +
1.305 + /**
1.306 + * Notification that the node's parent chain has changed. This
1.307 + * happens when either the node or one of its ancestors is inserted
1.308 + * or removed as a child of another node.
1.309 + *
1.310 + * Note that when a node is inserted this notification is sent to
1.311 + * all descendants of that node, since all such nodes have their
1.312 + * parent chain changed.
1.313 + *
1.314 + * @param aContent The piece of content that had its parent changed.
1.315 + *
1.316 + * @note Callers of this method might not hold a strong reference to
1.317 + * the observer. The observer is responsible for making sure it
1.318 + * stays alive for the duration of the call as needed.
1.319 + */
1.320 +
1.321 + virtual void ParentChainChanged(nsIContent *aContent) = 0;
1.322 +};
1.323 +
1.324 +NS_DEFINE_STATIC_IID_ACCESSOR(nsIMutationObserver, NS_IMUTATION_OBSERVER_IID)
1.325 +
1.326 +#define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE \
1.327 + virtual void CharacterDataWillChange(nsIDocument* aDocument, \
1.328 + nsIContent* aContent, \
1.329 + CharacterDataChangeInfo* aInfo);
1.330 +
1.331 +#define NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED \
1.332 + virtual void CharacterDataChanged(nsIDocument* aDocument, \
1.333 + nsIContent* aContent, \
1.334 + CharacterDataChangeInfo* aInfo);
1.335 +
1.336 +#define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE \
1.337 + virtual void AttributeWillChange(nsIDocument* aDocument, \
1.338 + mozilla::dom::Element* aElement, \
1.339 + int32_t aNameSpaceID, \
1.340 + nsIAtom* aAttribute, \
1.341 + int32_t aModType);
1.342 +
1.343 +#define NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED \
1.344 + virtual void AttributeChanged(nsIDocument* aDocument, \
1.345 + mozilla::dom::Element* aElement, \
1.346 + int32_t aNameSpaceID, \
1.347 + nsIAtom* aAttribute, \
1.348 + int32_t aModType);
1.349 +
1.350 +#define NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED \
1.351 + virtual void ContentAppended(nsIDocument* aDocument, \
1.352 + nsIContent* aContainer, \
1.353 + nsIContent* aFirstNewContent, \
1.354 + int32_t aNewIndexInContainer);
1.355 +
1.356 +#define NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED \
1.357 + virtual void ContentInserted(nsIDocument* aDocument, \
1.358 + nsIContent* aContainer, \
1.359 + nsIContent* aChild, \
1.360 + int32_t aIndexInContainer);
1.361 +
1.362 +#define NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED \
1.363 + virtual void ContentRemoved(nsIDocument* aDocument, \
1.364 + nsIContent* aContainer, \
1.365 + nsIContent* aChild, \
1.366 + int32_t aIndexInContainer, \
1.367 + nsIContent* aPreviousSibling);
1.368 +
1.369 +#define NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED \
1.370 + virtual void NodeWillBeDestroyed(const nsINode* aNode);
1.371 +
1.372 +#define NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED \
1.373 + virtual void ParentChainChanged(nsIContent *aContent);
1.374 +
1.375 +#define NS_DECL_NSIMUTATIONOBSERVER \
1.376 + NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATAWILLCHANGE \
1.377 + NS_DECL_NSIMUTATIONOBSERVER_CHARACTERDATACHANGED \
1.378 + NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTEWILLCHANGE \
1.379 + NS_DECL_NSIMUTATIONOBSERVER_ATTRIBUTECHANGED \
1.380 + NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED \
1.381 + NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED \
1.382 + NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED \
1.383 + NS_DECL_NSIMUTATIONOBSERVER_NODEWILLBEDESTROYED \
1.384 + NS_DECL_NSIMUTATIONOBSERVER_PARENTCHAINCHANGED
1.385 +
1.386 +#define NS_IMPL_NSIMUTATIONOBSERVER_CORE_STUB(_class) \
1.387 +void \
1.388 +_class::NodeWillBeDestroyed(const nsINode* aNode) \
1.389 +{ \
1.390 +}
1.391 +
1.392 +#define NS_IMPL_NSIMUTATIONOBSERVER_CONTENT(_class) \
1.393 +void \
1.394 +_class::CharacterDataWillChange(nsIDocument* aDocument, \
1.395 + nsIContent* aContent, \
1.396 + CharacterDataChangeInfo* aInfo) \
1.397 +{ \
1.398 +} \
1.399 +void \
1.400 +_class::CharacterDataChanged(nsIDocument* aDocument, \
1.401 + nsIContent* aContent, \
1.402 + CharacterDataChangeInfo* aInfo) \
1.403 +{ \
1.404 +} \
1.405 +void \
1.406 +_class::AttributeWillChange(nsIDocument* aDocument, \
1.407 + mozilla::dom::Element* aElement, \
1.408 + int32_t aNameSpaceID, \
1.409 + nsIAtom* aAttribute, \
1.410 + int32_t aModType) \
1.411 +{ \
1.412 +} \
1.413 +void \
1.414 +_class::AttributeChanged(nsIDocument* aDocument, \
1.415 + mozilla::dom::Element* aElement, \
1.416 + int32_t aNameSpaceID, \
1.417 + nsIAtom* aAttribute, \
1.418 + int32_t aModType) \
1.419 +{ \
1.420 +} \
1.421 +void \
1.422 +_class::ContentAppended(nsIDocument* aDocument, \
1.423 + nsIContent* aContainer, \
1.424 + nsIContent* aFirstNewContent, \
1.425 + int32_t aNewIndexInContainer) \
1.426 +{ \
1.427 +} \
1.428 +void \
1.429 +_class::ContentInserted(nsIDocument* aDocument, \
1.430 + nsIContent* aContainer, \
1.431 + nsIContent* aChild, \
1.432 + int32_t aIndexInContainer) \
1.433 +{ \
1.434 +} \
1.435 +void \
1.436 +_class::ContentRemoved(nsIDocument* aDocument, \
1.437 + nsIContent* aContainer, \
1.438 + nsIContent* aChild, \
1.439 + int32_t aIndexInContainer, \
1.440 + nsIContent* aPreviousSibling) \
1.441 +{ \
1.442 +} \
1.443 +void \
1.444 +_class::ParentChainChanged(nsIContent *aContent) \
1.445 +{ \
1.446 +}
1.447 +
1.448 +
1.449 +#endif /* nsIMutationObserver_h */
