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
  45         /**
  46          * Destructor.  Calls shutdown() if the reference has not been
  47          * shut down yet.
  48          */
  49         virtual ~URIReference();
  50
  51         /**
  52          * Attaches to a URI, relative to the specified document.
  53          *
  54          * Throws a BadURIException if the URI is unsupported,
  55          * or the fragment identifier is xpointer and malformed.
  56          *
  57          * @param rel_document document for relative URIs
  58          * @param uri the URI to watch
  59          */
  60         void attach(const URI &uri) throw(BadURIException);
  61
  62         /**
  63          * Detaches from the currently attached URI target, if any;
  64          * the current referrent is signaled as NULL.
  65          */
  66         void detach();
  67
  68         /**
  69          * @brief Returns a pointer to the current referrent of the
  70          * attached URI, or NULL.
  71          *
  72          * @return a pointer to the referenced SPObject or NULL
  73          */
  74         SPObject *getObject() const { return _obj; }
  75
  76         /**
  77          * @brief Returns a pointer to the URIReference's owner
  78          *
  79          * @return a pointer to the URIReference's owner
  80          */
  81         SPObject *getOwner() const { return _owner; }
  82
  83         /**
  84          * Accessor for the referrent change notification signal;
  85          * this signal is emitted whenever the URIReference's
  86          * referrent changes.
  87          *
  88          * Signal handlers take two parameters: the old and new
  89          * referrents.
  90          *
  91          * @returns a signal
  92          */
  93         sigc::signal<void, SPObject *, SPObject *> changedSignal() {
  94                 return _changed_signal;
  95         }
  96
  97         /**
  98          * Returns a pointer to a URI containing the currently attached
  99          * URI, or NULL if no URI is currently attached.
 100          *
 101          * @returns the currently attached URI, or NULL
 102          */
 103         const URI *getURI() const {
 104                 return _uri;
 105         }
 106
 107         /**
 108          * Returns true if there is currently an attached URI
 109          *
 110          * @returns true if there is an attached URI
 111          */
 112         bool isAttached() const {
 113                 return (bool)_uri;
 114         }
 115
 116 protected:
 117         virtual bool _acceptObject(SPObject *obj) const { return true; }
 118
 119 private:
 120         SPObject *_owner;
 121         sigc::connection _connection;
 122         SPObject *_obj;
 123         URI *_uri;
 124
 125         sigc::signal<void, SPObject *, SPObject *> _changed_signal;
 126
 127         void _setObject(SPObject *object);
 128         static void _release(SPObject *object, URIReference *reference);
 129
 130         void operator=(const URIReference &ref);
 131         /* Private and definition-less to prevent accidental use. */
 132 };
 133
 134 }
 135
 136 SPObject *sp_uri_reference_resolve (SPDocument *document, const gchar *uri);
 137
 138 #endif