src/uri-references.h

   1 #ifndef __SP_URI_REFERENCES_H__
   2 #define __SP_URI_REFERENCES_H__
   3
   4 /*
   5  * Helper methods for resolving URI References
   6  *
   7  * Authors:
   8  *   Lauris Kaplinski <lauris@kaplinski.com>
   9  *
  10  * Copyright (C) 2001-2002 Lauris Kaplinski
  11  * Copyright (C) 2001 Ximian, Inc.
  12  *
  13  * Released under GNU GPL, read the file 'COPYING' for more information
  14  */
  15
  16 #include <sigc++/connection.h>
  17 #include <sigc++/trackable.h>
  18
  19 #include "bad-uri-exception.h"
  20 #include "forward.h"
  21
  22 namespace Inkscape {
  23
  24 /**
  25  * A class encapsulating a reference to a particular URI; observers can
  26  * be notified when the URI comes to reference a different SPObject.
  27  *
  28  * The URIReference increments and decrements the SPObject's hrefcount
  29  * automatically.
  30  *
  31  * @see SPObject
  32  * @see sp_object_href
  33  * @see sp_object_hunref
  34  */
  35 class URIReference : public sigc::trackable {
  36 public:
  37         /**
  38          * Constructor.
  39          *
  40          * @param owner The object on whose behalf this URIReference
  41          *              is holding a reference to the target object.
  42          */
  43         URIReference(SPObject *owner);
  44         URIReference(SPDocument *owner_document);
  45
  46         /**
  47          * Destructor.  Calls shutdown() if the reference has not been
  48          * shut down yet.
  49          */
  50         virtual ~URIReference();
  51
  52         /**
  53          * Attaches to a URI, relative to the specified document.
  54          *
  55          * Throws a BadURIException if the URI is unsupported,
  56          * or the fragment identifier is xpointer and malformed.
  57          *
  58          * @param rel_document document for relative URIs
  59          * @param uri the URI to watch
  60          */
  61         void attach(const URI &uri) throw(BadURIException);
  62
  63         /**
  64          * Detaches from the currently attached URI target, if any;
  65          * the current referrent is signaled as NULL.
  66          */
  67         void detach();
  68
  69         /**
  70          * @brief Returns a pointer to the current referrent of the
  71          * attached URI, or NULL.
  72          *
  73          * @return a pointer to the referenced SPObject or NULL
  74          */
  75         SPObject *getObject() const { return _obj; }
  76
  77         /**
  78          * @brief Returns a pointer to the URIReference's owner
  79          *
  80          * @return a pointer to the URIReference's owner
  81          */
  82         SPObject *getOwner() const { return _owner; }
  83
  84         /**
  85          * Accessor for the referrent change notification signal;
  86          * this signal is emitted whenever the URIReference's
  87          * referrent changes.
  88          *
  89          * Signal handlers take two parameters: the old and new
  90          * referrents.
  91          *
  92          * @returns a signal
  93          */
  94         sigc::signal<void, SPObject *, SPObject *> changedSignal() {
  95                 return _changed_signal;
  96         }
  97
  98         /**
  99          * Returns a pointer to a URI containing the currently attached
 100          * URI, or NULL if no URI is currently attached.
 101          *
 102          * @returns the currently attached URI, or NULL
 103          */
 104         const URI *getURI() const {
 105                 return _uri;
 106         }
 107
 108         /**
 109          * Returns true if there is currently an attached URI
 110          *
 111          * @returns true if there is an attached URI
 112          */
 113         bool isAttached() const {
 114                 return (bool)_uri;
 115         }
 116
 117   SPDocument *getOwnerDocument() {return _owner_document;}
 118   SPObject *getOwnerObject() {return _owner;}
 119
 120 protected:
 121         virtual bool _acceptObject(SPObject *obj) const { return true; }
 122
 123 private:
 124         SPObject *_owner;
 125         SPDocument *_owner_document;
 126         sigc::connection _connection;
 127         sigc::connection _release_connection;
 128         SPObject *_obj;
 129         URI *_uri;
 130
 131         sigc::signal<void, SPObject *, SPObject *> _changed_signal;
 132
 133         void _setObject(SPObject *object);
 134         void _release(SPObject *object);
 135
 136         void operator=(const URIReference &ref);
 137         /* Private and definition-less to prevent accidental use. */
 138 };
 139
 140 }
 141
 142 SPObject *sp_uri_reference_resolve (SPDocument *document, const gchar *uri);
 143
 144 #endif