1 #ifndef __SP_URI_REFERENCES_H__
2 #define __SP_URI_REFERENCES_H__
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 */
17 #include <sigc++/connection.h>
18 #include <sigc++/trackable.h>
20 #include "bad-uri-exception.h"
21 #include "forward.h"
22 #include "sp-object.h"
24 namespace Inkscape {
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);
48 /**
49 * Destructor. Calls shutdown() if the reference has not been
50 * shut down yet.
51 */
52 virtual ~URIReference();
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);
65 /**
66 * Detaches from the currently attached URI target, if any;
67 * the current referrent is signaled as NULL.
68 */
69 void detach();
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; }
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; }
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 }
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 }
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 }
119 SPDocument *getOwnerDocument() { return _owner_document; }
120 SPObject *getOwnerObject() { return _owner; }
122 protected:
123 virtual bool _acceptObject(SPObject *obj) const {
124 (void)obj;
125 return true;
126 }
128 private:
129 SPObject *_owner;
130 SPDocument *_owner_document;
131 sigc::connection _connection;
132 sigc::connection _release_connection;
133 SPObject *_obj;
134 URI *_uri;
136 sigc::signal<void, SPObject *, SPObject *> _changed_signal;
138 void _setObject(SPObject *object);
139 void _release(SPObject *object);
141 void operator=(const URIReference &ref);
142 /* Private and definition-less to prevent accidental use. */
143 };
145 }
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 );
152 SPObject *sp_uri_reference_resolve (SPDocument *document, const gchar *uri);
154 #endif