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