1 /** @file
2 * @brief Interface for XML node observers
3 */
4 /* Authors:
5 * MenTaLguY <mental@rydia.net>
6 * Krzysztof KosiĆski <tweenk.pl@gmail.com> (documentation)
7 *
8 * Copyright 2005-2008 Authors
9 *
10 * This program is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU General Public License
12 * as published by the Free Software Foundation; either version 2
13 * of the License, or (at your option) any later version.
14 *
15 * See the file COPYING for details.
16 */
18 #ifndef SEEN_INKSCAPE_XML_NODE_OBSERVER_H
19 #define SEEN_INKSCAPE_XML_NODE_OBSERVER_H
21 #include <glib/gquark.h>
22 #include "util/share.h"
23 #include "xml/xml-forward.h"
26 namespace Inkscape {
27 namespace XML {
29 /**
30 * @brief Interface for XML node observers
31 *
32 * This class defines an interface for objects that can receive
33 * XML node state change notifications. The observer has to be registered using
34 * the Node::addObserver() method to be notified of changes of this node only,
35 * or using Node::addSubtreeObserver() to also receive notifications about its
36 * descendants. All observer methods are called when the operations in question have
37 * been completed, just before returning from the modifying methods.
38 *
39 * Be careful when e.g. changing an attribute of @c node in notifyAttributeChanged().
40 * The method will be called again due to the XML modification performed in it. If you
41 * don't take special precautions to ignore the second call, it will result in infinite
42 * recursion.
43 *
44 * The virtual methods of this class do nothing by default, so you don't need to provide
45 * stubs for things you don't use. A good idea is to make the observer register itself
46 * on construction and unregister itself on destruction. This will ensure there are
47 * no dangling references.
48 */
49 class NodeObserver {
50 public:
51 NodeObserver() {}
52 virtual ~NodeObserver() {}
54 /**
55 * @brief Child addition callback
56 *
57 * This method is called whenever a child is added to the observed node. The @c prev
58 * parameter is NULL when the newly added child is first in the sibling order.
59 *
60 * @param node The changed XML node
61 * @param child The newly added child node
62 * @param prev The node after which the new child was inserted into the sibling order, or NULL
63 */
64 virtual void notifyChildAdded(Node &node, Node &child, Node *prev) {}
66 /**
67 * @brief Child removal callback
68 *
69 * This method is called whenever a child is removed from the observed node. The @c prev
70 * parameter is NULL when the removed child was first in the sibling order.
71 *
72 * @param node The changed XML node
73 * @param child The removed child node
74 * @param prev The node that was before the removed node in sibling order, or NULL
75 */
76 virtual void notifyChildRemoved(Node &node, Node &child, Node *prev) {}
78 /**
79 * @brief Child order change callback
80 *
81 * This method is called whenever the order of a node's children is changed using
82 * Node::changeOrder(). The @c old_prev parameter is NULL if the relocated node
83 * was first in the sibling order before the order change, and @c new_prev is NULL
84 * if it was moved to the first position by this operation.
85 *
86 * @param node The changed XML node
87 * @param child The child node that was relocated in the sibling order
88 * @param old_prev The node that was before @c child prior to the order change
89 * @param new_prev The node that is before @c child after the order change
90 */
91 virtual void notifyChildOrderChanged(Node &node, Node &child,
92 Node *old_prev, Node *new_prev) {}
94 /**
95 * @brief Content change callback
96 *
97 * This method is called whenever a node's content is changed using Node::setContent(),
98 * e.g. for text or comment nodes.
99 *
100 * @param node The changed XML node
101 * @param old_content Old content of @c node
102 * @param new_content New content of @c node
103 */
104 virtual void notifyContentChanged(Node &node,
105 Util::ptr_shared<char> old_content,
106 Util::ptr_shared<char> new_content) {}
108 /**
109 * @brief Attribute change callback
110 *
111 * This method is called whenever one of a node's attributes is changed.
112 *
113 * @param node The changed XML node
114 * @param name GQuark corresponding to the attribute's name
115 * @param old_value Old value of the modified attribute
116 * @param new_value New value of the modified attribute
117 */
118 virtual void notifyAttributeChanged(Node &node, GQuark name,
119 Util::ptr_shared<char> old_value,
120 Util::ptr_shared<char> new_value) {}
121 };
123 } // namespace XML
124 } // namespace Inkscape
126 #endif
127 /*
128 Local Variables:
129 mode:c++
130 c-file-style:"stroustrup"
131 c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
132 indent-tabs-mode:nil
133 fill-column:99
134 End:
135 */
136 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :