2b9ea5cc3c8ebd12648af2d8cdbfbd51ff1747c7
1 /** @file
2 * @brief Interface for XML documents
3 */
4 /* Copyright 2005 MenTaLguY <mental@rydia.net>
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public License
8 * as published by the Free Software Foundation; either version 2
9 * of the License, or (at your option) any later version.
10 *
11 * See the file COPYING for details.
12 *
13 */
15 #ifndef SEEN_INKSCAPE_XML_SP_REPR_DOC_H
16 #define SEEN_INKSCAPE_XML_SP_REPR_DOC_H
18 #include "xml/xml-forward.h"
19 #include "xml/node.h"
21 namespace Inkscape {
22 namespace XML {
24 /**
25 * @brief Interface for XML documents
26 *
27 * This class represents a complete document tree. You have to go through this class
28 * to create new nodes. It also contains transaction support, which forms the base
29 * of the undo system.
30 *
31 * The document is also a node. It usually contains only two child nodes - a processing
32 * instruction node (PINode) containing the XML prolog, and the root node. You can get
33 * the root node of the document by calling the root() method.
34 *
35 * The name "transaction" can be misleading, because they are not atomic. Their main feature
36 * is that they provide rollback. After starting a transaction,
37 * all changes made to the document are stored in an internal event log. At any time
38 * after starting the transaction, you can call the rollback() method, which restores
39 * the document to the state it was before starting the transaction. Calling the commit()
40 * method causes the internal event log to be discarded, and you can estabilish a new
41 * "restore point" by calling beginTransaction() again. There can be only one active
42 * transaction at a time for a given document.
43 */
44 struct Document : virtual public Node {
45 public:
46 /**
47 * @name Document transactions
48 * @{
49 */
50 /**
51 * @brief Checks whether there is an active transaction for this document
52 * @return true if there's an established transaction for this document, false otherwise
53 */
54 virtual bool inTransaction()=0;
55 /**
56 * @brief Begin a transaction and start recording changes
57 *
58 * By calling this method you effectively establish a resotre point.
59 * You can undo all changes made to the document after this call using rollback().
60 */
61 virtual void beginTransaction()=0;
62 /**
63 * @brief Restore the state of the document prior to the transaction
64 *
65 * This method applies the inverses of all recorded changes in reverse order,
66 * restoring the document state from before the transaction. For some implementations,
67 * this function may do nothing.
68 */
69 virtual void rollback()=0;
70 /**
71 * @brief Commit a transaction and discard change data
72 *
73 * This method finishes the active transaction and discards the recorded changes.
74 */
75 virtual void commit()=0;
76 /**
77 * @brief Commit a transaction and store the events for later use
78 *
79 * This method finishes a transaction and returns an event chain
80 * that describes the changes made to the document. This method may return NULL,
81 * which means that the document implementation doesn't support event logging,
82 * or that no changes were made.
83 *
84 * @return Event chain describing the changes, or NULL
85 */
86 virtual Event *commitUndoable()=0;
87 /*@}*/
89 /**
90 * @name Create new nodes
91 * @{
92 */
93 virtual Node *createElement(char const *name)=0;
94 virtual Node *createTextNode(char const *content)=0;
95 virtual Node *createComment(char const *content)=0;
96 virtual Node *createPI(char const *target, char const *content)=0;
97 /*@}*/
99 /**
100 * @brief Get the event logger for this document
101 *
102 * This is an implementation detail that should not be used outside of node implementations.
103 * It should be made non-public in the future.
104 */
105 virtual NodeObserver *logger()=0;
106 };
108 }
109 }
111 #endif
112 /*
113 Local Variables:
114 mode:c++
115 c-file-style:"stroustrup"
116 c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
117 indent-tabs-mode:nil
118 fill-column:99
119 End:
120 */
121 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :