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 {
 122         (void)obj;
 123         return true;
 124     }
 125
 126 private:
 127     SPObject *_owner;
 128     SPDocument *_owner_document;
 129     sigc::connection _connection;
 130     sigc::connection _release_connection;
 131     SPObject *_obj;
 132     URI *_uri;
 133
 134     sigc::signal<void, SPObject *, SPObject *> _changed_signal;
 135
 136     void _setObject(SPObject *object);
 137     void _release(SPObject *object);
 138
 139     void operator=(const URIReference &ref);
 140     /* Private and definition-less to prevent accidental use. */
 141 };
 142
 143 }
 144
 145 /**
 146  * Resolves an item referenced by a URI in CSS form contained in "url(...)"
 147  */
 148 SPObject* sp_css_uri_reference_resolve( SPDocument *document, const gchar *uri );
 149
 150 SPObject *sp_uri_reference_resolve (SPDocument *document, const gchar *uri);
 151
 152 #endif