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