1 /** @file
2 * @brief Interface for XML nodes
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_H
19 #define SEEN_INKSCAPE_XML_NODE_H
21 #include <glib/gtypes.h>
22 #include "gc-anchored.h"
23 #include "util/list.h"
24 #include "xml/xml-forward.h"
26 namespace Inkscape {
27 namespace XML {
29 /**
30 * @brief Enumeration containing all supported node types.
31 */
32 enum NodeType {
33 DOCUMENT_NODE, ///< Top-level document node. Do not confuse with the root node.
34 ELEMENT_NODE, ///< Regular element node, e.g. <group />.
35 TEXT_NODE, ///< Text node, e.g. "Some text" in <group>Some text</group> is represented by a text node.
36 COMMENT_NODE, ///< Comment node, e.g. <!-- some comment -->
37 PI_NODE ///< Processing instruction node, e.g. <?xml version="1.0" encoding="utf-8" standalone="no"?>
38 };
40 // careful; GC::Anchored should only appear once in the inheritance
41 // hierarchy; otherwise there will be leaks
43 /**
44 * @brief Interface for refcounted XML nodes
45 *
46 * This class is an abstract base type for all nodes in an XML document - this includes
47 * everything except attributes. An XML document is also a node itself. This is the main
48 * class used for interfacing with Inkscape's documents. Everything that has to be stored
49 * in the SVG has to go through this class at some point.
50 *
51 * Each node unconditionally has to belong to a document. There no "documentless" nodes,
52 * and it's not possible to move nodes between documents - they have to be duplicated.
53 * Each node can only refer to the nodes in the same document. Name of the node is immutable,
54 * it cannot be changed after its creation. Same goes for the type of the node. To simplify
55 * the use of this class, you can perform all operations on all nodes, but only some of them
56 * make any sense. For example, only element nodes can have attributes, only element and
57 * document nodes can have children, and all nodes except element and document nodes can
58 * have content. Although you can set content for element nodes, it won't make any difference
59 * in the XML output.
60 *
61 * To create new nodes, use the methods of the Inkscape::XML::Document class. You can obtain
62 * the nodes' document using the document() method. To destroy a node, just unparent it
63 * by calling sp_repr_unparent() or node->parent->removeChild() and release any references
64 * to it. The garbage collector will reclaim the memory in the next pass. There are additional
65 * convenience functions defined in @ref xml/repr.h
66 *
67 * In addition to regular DOM manipulations, you can register observer objects that will
68 * receive notifications about changes made to the node. See the NodeObserver class.
69 *
70 * @see Inkscape::XML::Document
71 * @see Inkscape::XML::NodeObserver
72 */
73 class Node : public Inkscape::GC::Anchored {
74 public:
75 Node() {}
76 virtual ~Node() {}
78 /**
79 * @name Retrieve information about the node
80 * @{
81 */
83 /**
84 * @brief Get the type of the node
85 * @return NodeType enumeration member corresponding to the type of the node.
86 */
87 virtual NodeType type() const=0;
89 /**
90 * @brief Get the name of the element node
91 *
92 * This method only makes sense for element nodes. Names are stored as
93 * GQuarks to accelerate conversions.
94 *
95 * @return Name for element nodes, NULL for others
96 */
97 virtual gchar const *name() const=0;
98 /**
99 * @brief Get the integer code corresponding to the node's name
100 * @return GQuark code corresponding to the name
101 */
102 virtual int code() const=0;
104 /**
105 * @brief Get the index of this node in parent's child order
106 *
107 * If this method is used on a node that doesn't have a parent, the method will return 0,
108 * and a warning will be printed on the console.
109 *
110 * @return The node's index, or 0 if the node does not have a parent
111 */
112 virtual unsigned position() const=0;
114 /**
115 * @brief Get the number of children of this node
116 * @return The number of children
117 */
118 virtual unsigned childCount() const=0;
120 /**
121 * @brief Get the content of a text or comment node
122 *
123 * This method makes no sense for element nodes. To retrieve the element node's name,
124 * use the name() method.
125 *
126 * @return The node's content
127 */
128 virtual gchar const *content() const=0;
130 /**
131 * @brief Get the string representation of a node's attribute
132 *
133 * If there is no attribute with the given name, the method will return NULL.
134 * All strings returned by this method are owned by the node and may not be freed.
135 * The returned pointer will become invalid when the attribute changes. If you need
136 * to store the return value, use g_strdup(). To parse the string, use methods
137 * in repr.h
138 *
139 * @param key The name of the node's attribute
140 */
141 virtual gchar const *attribute(gchar const *key) const=0;
143 /**
144 * @brief Get a list of the node's attributes
145 *
146 * The returned list is a functional programming style list rather than a standard one.
147 *
148 * @return A list of AttributeRecord structures describing the attributes
149 * @todo This method should return std::map<Glib::Quark const, gchar const *>
150 * or something similar with a custom allocator
151 */
152 virtual Inkscape::Util::List<AttributeRecord const> attributeList() const=0;
154 /**
155 * @brief Check whether this node has any attribute that matches a string
156 *
157 * This method checks whether this node has any attributes whose names
158 * have @c partial_name as their substrings. The check is done using
159 * the strstr() function of the C library. I don't know what would require that
160 * functionality, because matchAttributeName("id") matches both "identity" and "hidden".
161 *
162 * @param partial_name The string to match against all attributes
163 * @return true if there is such an attribute, false otherwise
164 */
165 virtual bool matchAttributeName(gchar const *partial_name) const=0;
167 /*@}*/
169 /**
170 * @name Modify the node
171 * @{
172 */
174 /**
175 * @brief Set the position of this node in parent's child order
176 *
177 * To move the node to the end of the parent's child order, pass a negative argument.
178 *
179 * @param pos The new position in parent's child order
180 */
181 virtual void setPosition(int pos)=0;
183 /**
184 * @brief Set the content of a text or comment node
185 *
186 * This method doesn't make sense for element nodes.
187 *
188 * @param value The node's new content
189 */
190 virtual void setContent(gchar const *value)=0;
192 /**
193 * @brief Change an attribute of this node
194 *
195 * The strings passed to this method are copied, so you can free them after use.
196 *
197 * @param key Name of the attribute to change
198 * @param value The new value of the attribute
199 * @param is_interactive Ignored
200 */
201 virtual void setAttribute(gchar const *key, gchar const *value, bool is_interactive=false)=0;
203 /**
204 * @brief Directly set the integer GQuark code for the name of the node
205 *
206 * This function is a hack to easily move elements with no namespace to the SVG namespace.
207 * Do not use this function unless you really have a good reason.
208 *
209 * @param code The integer value corresponding to the string to be set as the name of this node
210 */
211 virtual void setCodeUnsafe(int code)=0;
213 /*@}*/
216 /**
217 * @name Traverse the XML tree
218 * @{
219 */
221 //@{
222 /**
223 * @brief Get the node's associated document
224 * @return The document to which the node belongs. Never NULL.
225 */
226 virtual Document *document()=0;
227 virtual Document const *document() const=0;
228 //@}
230 //@{
231 /**
232 * @brief Get the root node of this node's document
233 *
234 * This method works on any node that is part of an XML document, and returns
235 * the root node of the document in which it resides. For detached node hierarchies
236 * (i.e. nodes that are not descendants of a document node) this method
237 * returns the highest-level element node. For detached non-element nodes this method
238 * returns NULL.
239 *
240 * @return A pointer to the root element node, or NULL if the node is detached
241 */
242 virtual Node *root()=0;
243 virtual Node const *root() const=0;
244 //@}
246 //@{
247 /**
248 * @brief Get the parent of this node
249 *
250 * This method will return NULL for detached nodes.
251 *
252 * @return Pointer to the parent, or NULL
253 */
254 virtual Node *parent()=0;
255 virtual Node const *parent() const=0;
256 //@}
258 //@{
259 /**
260 * @brief Get the next sibling of this node
261 *
262 * This method will return NULL if the node is the last sibling element of the parent.
263 * The nodes form a singly-linked list, so there is no "prev()" method. Use the provided
264 * external function for that.
265 *
266 * @return Pointer to the next sibling, or NULL
267 * @see Inkscape::XML::previous_node()
268 */
269 virtual Node *next()=0;
270 virtual Node const *next() const=0;
271 //@}
273 //@{
274 /**
275 * @brief Get the first child of this node
276 *
277 * For nodes without any children, this method returns NULL.
278 *
279 * @return Pointer to the first child, or NULL
280 */
281 virtual Node *firstChild()=0;
282 virtual Node const *firstChild() const=0;
283 //@}
285 //@{
286 /**
287 * @brief Get the last child of this node
288 *
289 * For nodes without any children, this method returns NULL.
290 *
291 * @return Pointer to the last child, or NULL
292 */
293 virtual Node *lastChild()=0;
294 virtual Node const *lastChild() const=0;
295 //@}
297 //@{
298 /**
299 * @brief Get the child of this node with a given index
300 *
301 * If there is no child with the specified index number, this method will return NULL.
302 *
303 * @param index The zero-based index of the child to retrieve
304 * @return Pointer to the appropriate child, or NULL
305 */
306 virtual Node *nthChild(unsigned index)=0;
307 virtual Node const *nthChild(unsigned index) const=0;
308 //@}
310 /*@}*/
312 /**
313 * @name Manipulate the XML tree
314 * @{
315 */
317 /**
318 * @brief Create a duplicate of this node
319 *
320 * The newly created node has no parent, and a refcount equal 1.
321 * You need to manually insert it into the document, using e.g. appendChild().
322 * Afterwards, call Inkscape::GC::release on it, so that it will be
323 * automatically collected when the parent is collected.
324 *
325 * @param doc The document in which the duplicate should be created
326 * @return A pointer to the duplicated node
327 */
328 virtual Node *duplicate(Document *doc) const=0;
330 /**
331 * @brief Insert another node as a child of this node
332 *
333 * When @c after is NULL, the inserted node will be placed as the first child
334 * of this node. @c after must be a child of this node.
335 *
336 * @param child The node to insert
337 * @param after The node after which the inserted node should be placed, or NULL
338 */
339 virtual void addChild(Node *child, Node *after)=0;
341 /**
342 * @brief Append a node as the last child of this node
343 * @param child The node to append
344 */
345 virtual void appendChild(Node *child)=0;
347 /**
348 * @brief Remove a child of this node
349 *
350 * Once the pointer to the removed node disappears from the stack, the removed node
351 * will be collected in the next GC pass, but only as long as its refcount is zero.
352 * You should keep a refcount of zero for all nodes in the document except for
353 * the document node itself, because they will be held in memory by the parent.
354 *
355 * @param child The child to remove
356 */
357 virtual void removeChild(Node *child)=0;
359 /**
360 * @brief Move a given node in this node's child order
361 *
362 * Both @c child and @c after must be children of this node for the method to work.
363 *
364 * @param child The node to move in the order
365 * @param after The sibling node after which the moved node should be placed
366 */
367 virtual void changeOrder(Node *child, Node *after)=0;
369 /**
370 * @brief Merge all children of another node with the current
371 *
372 * This method merges two node hierarchies, where @c src takes precedence.
373 * @c key is the name of the attribute that determines whether two nodes are
374 * corresponding (it must be the same for both, and all of their ancestors). If there is
375 * a corresponding node in @c src hierarchy, their attributes and content override the ones
376 * already present in this node's hierarchy. If there is no corresponding node,
377 * it is copied from @c src to this node. This method is used when merging the user's
378 * preferences file with the defaults, and has little use beyond that.
379 *
380 * @param src The node to merge into this node
381 * @param key The attribute to use as the identity attribute
382 */
383 virtual void mergeFrom(Node const *src, gchar const *key)=0;
385 /*@}*/
388 /**
389 * @name Notify observers about operations on the node
390 * @{
391 */
393 /**
394 * @brief Add an object that will be notified of the changes to this node
395 *
396 * @c observer must be an object deriving from the NodeObserver class.
397 * The virtual methods of this object will be called when a corresponding change
398 * happens to this node. You can also notify the observer of the node's current state
399 * using synthesizeEvents(NodeObserver &).
400 *
401 * @param observer The observer object
402 */
403 virtual void addObserver(NodeObserver &observer)=0;
404 /**
405 * @brief Remove an object from the list of observers
406 * @param observer The object to be removed
407 */
408 virtual void removeObserver(NodeObserver &observer)=0;
409 /**
410 * @brief Generate a sequence of events corresponding to the state of this node
411 *
412 * This function notifies the specified observer of all the events that would
413 * recreate the current state of this node; e.g. the observer is notified of
414 * all the attributes, children and content like they were just created.
415 * This function can greatly simplify observer logic.
416 *
417 * @param observer The node observer to notify of the events
418 */
419 virtual void synthesizeEvents(NodeObserver &observer)=0;
421 /**
422 * @brief Add an object that will be notified of the changes to this node and its descendants
423 *
424 * The difference between adding a regular observer and a subtree observer is that
425 * the subtree observer will also be notified if a change occurs to any of the node's
426 * descendants, while a regular observer will only be notified of changes to the node
427 * it was assigned to.
428 *
429 * @param observer The observer object
430 */
431 virtual void addSubtreeObserver(NodeObserver &observer)=0;
433 /**
434 * @brief Remove an object from the subtree observers list
435 * @param observer The object to be removed
436 */
437 virtual void removeSubtreeObserver(NodeObserver &observer)=0;
439 /**
440 * @brief Add a set node change callbacks with an associated data
441 * @deprecated Use addObserver(NodeObserver &) instead
442 */
443 virtual void addListener(NodeEventVector const *vector, void *data)=0;
444 /**
445 * @brief Remove a set of node change callbacks by their associated data
446 * @deprecated Use removeObserver(NodeObserver &) instead
447 */
448 virtual void removeListenerByData(void *data)=0;
449 /**
450 * @brief Generate a sequence of events corresponding to the state of this node
451 * @deprecated Use synthesizeEvents(NodeObserver &) instead
452 */
453 virtual void synthesizeEvents(NodeEventVector const *vector, void *data)=0;
455 /*@}*/
457 protected:
458 Node(Node const &) : Anchored() {}
459 };
461 }
462 }
464 #endif
465 /*
466 Local Variables:
467 mode:c++
468 c-file-style:"stroustrup"
469 c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
470 indent-tabs-mode:nil
471 fill-column:99
472 End:
473 */
474 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :