src/xml/document.h

   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  */
  14
  15 #ifndef SEEN_INKSCAPE_XML_SP_REPR_DOC_H
  16 #define SEEN_INKSCAPE_XML_SP_REPR_DOC_H
  17
  18 #include "xml/xml-forward.h"
  19 #include "xml/node.h"
  20
  21 namespace Inkscape {
  22 namespace XML {
  23
  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     /*@}*/
  88
  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     /*@}*/
  98
  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 };
 107
 108 }
 109 }
 110
 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:fileencoding=utf-8:textwidth=99 :