• file
• revisions
• annotate
• diff
• comparison
• raw

content/base/public/nsIMutationObserver.h@a63d609f5ebe (annotated)

content/base/public/nsIMutationObserver.h

Thu, 15 Jan 2015 15:55:04 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 15 Jan 2015 15:55:04 +0100

branch

TOR_BUG_9701

changeset 9

a63d609f5ebe

permissions

-rw-r--r--

Back out 97036ab72558 which inappropriately compared turds to third parties.

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