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 *
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 */
16 #include <sigc++/connection.h>
17 #include <sigc++/trackable.h>
19 #include "bad-uri-exception.h"
20 #include "forward.h"
22 namespace Inkscape {
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);
45 /**
46 * Destructor. Calls shutdown() if the reference has not been
47 * shut down yet.
48 */
49 virtual ~URIReference();
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);
62 /**
63 * Detaches from the currently attached URI target, if any;
64 * the current referrent is signaled as NULL.
65 */
66 void detach();
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; }
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; }
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 }
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 }
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 }
116 protected:
117 virtual bool _acceptObject(SPObject *obj) const { return true; }
119 private:
120 SPObject *_owner;
121 sigc::connection _connection;
122 SPObject *_obj;
123 URI *_uri;
125 sigc::signal<void, SPObject *, SPObject *> _changed_signal;
127 void _setObject(SPObject *object);
128 static void _release(SPObject *object, URIReference *reference);
130 void operator=(const URIReference &ref);
131 /* Private and definition-less to prevent accidental use. */
132 };
134 }
136 SPObject *sp_uri_reference_resolve (SPDocument *document, const gchar *uri);
138 #endif