1 #ifndef __SP_OBJECT_H__
2 #define __SP_OBJECT_H__
4 /** \file
5 * Abstract base class for all nodes
6 *
7 * Authors:
8 * Lauris Kaplinski <lauris@kaplinski.com>
9 *
10 * Copyright (C) 1999-2002 authors
11 * Copyright (C) 2001-2002 Ximian, Inc.
12 *
13 * Released under GNU GPL, read the file 'COPYING' for more information
14 */
16 /* SPObject flags */
18 /* Async modification flags */
19 #define SP_OBJECT_MODIFIED_FLAG (1 << 0)
20 #define SP_OBJECT_CHILD_MODIFIED_FLAG (1 << 1)
21 #define SP_OBJECT_PARENT_MODIFIED_FLAG (1 << 2)
22 #define SP_OBJECT_STYLE_MODIFIED_FLAG (1 << 3)
23 #define SP_OBJECT_VIEWPORT_MODIFIED_FLAG (1 << 4)
24 #define SP_OBJECT_USER_MODIFIED_FLAG_A (1 << 5)
25 #define SP_OBJECT_USER_MODIFIED_FLAG_B (1 << 6)
26 #define SP_OBJECT_USER_MODIFIED_FLAG_C (1 << 7)
28 /* Conveneience */
29 #define SP_OBJECT_FLAGS_ALL 0xff
31 /* Flags that mark object as modified */
32 /* Object, Child, Style, Viewport, User */
33 #define SP_OBJECT_MODIFIED_STATE (SP_OBJECT_FLAGS_ALL & ~(SP_OBJECT_PARENT_MODIFIED_FLAG))
35 /* Flags that will propagate downstreams */
36 /* Parent, Style, Viewport, User */
37 #define SP_OBJECT_MODIFIED_CASCADE (SP_OBJECT_FLAGS_ALL & ~(SP_OBJECT_MODIFIED_FLAG | SP_OBJECT_CHILD_MODIFIED_FLAG))
39 /* Generic */
40 #define SP_OBJECT_IS_CLONED(o) (((SPObject *) (o))->cloned)
42 /* Write flags */
43 #define SP_OBJECT_WRITE_BUILD (1 << 0)
44 #define SP_OBJECT_WRITE_EXT (1 << 1)
45 #define SP_OBJECT_WRITE_ALL (1 << 2)
47 /* Convenience stuff */
48 #define SP_OBJECT_ID(o) (((SPObject *) (o))->id)
49 #define SP_OBJECT_REPR(o) (((SPObject *) (o))->repr)
50 #define SP_OBJECT_DOCUMENT(o) (((SPObject *) (o))->document)
51 #define SP_OBJECT_PARENT(o) (((SPObject *) (o))->parent)
52 #define SP_OBJECT_NEXT(o) (((SPObject *) (o))->next)
53 #define SP_OBJECT_PREV(o) (sp_object_prev((SPObject *) (o)))
54 #define SP_OBJECT_HREFCOUNT(o) (((SPObject *) (o))->hrefcount)
55 #define SP_OBJECT_STYLE(o) (((SPObject *) (o))->style)
56 #define SP_OBJECT_TITLE(o) sp_object_title_get((SPObject *) (o))
57 #define SP_OBJECT_DESCRIPTION(o) sp_object_description_get((SPObject *) (o))
60 #include <glib-object.h>
61 #include <sigc++/connection.h>
62 #include <sigc++/functors/slot.h>
63 #include <sigc++/signal.h>
65 #include "forward.h"
66 #include "version.h"
67 #include "util/forward-pointer-iterator.h"
69 namespace Inkscape {
70 namespace XML {
71 class Node;
72 }
73 }
76 typedef enum {
77 SP_NO_EXCEPTION,
78 SP_INDEX_SIZE_ERR,
79 SP_DOMSTRING_SIZE_ERR,
80 SP_HIERARCHY_REQUEST_ERR,
81 SP_WRONG_DOCUMENT_ERR,
82 SP_INVALID_CHARACTER_ERR,
83 SP_NO_DATA_ALLOWED_ERR,
84 SP_NO_MODIFICATION_ALLOWED_ERR,
85 SP_NOT_FOUND_ERR,
86 SP_NOT_SUPPORTED_ERR,
87 SP_INUSE_ATTRIBUTE_ERR,
88 SP_INVALID_STATE_ERR,
89 SP_SYNTAX_ERR,
90 SP_INVALID_MODIFICATION_ERR,
91 SP_NAMESPACE_ERR,
92 SP_INVALID_ACCESS_ERR
93 } SPExceptionType;
95 class SPException;
97 /// An attempt to implement exceptions, unused?
98 struct SPException {
99 SPExceptionType code;
100 };
102 #define SP_EXCEPTION_INIT(ex) {(ex)->code = SP_NO_EXCEPTION;}
103 #define SP_EXCEPTION_IS_OK(ex) (!(ex) || ((ex)->code == SP_NO_EXCEPTION))
105 class SPCtx;
107 /// Unused
108 struct SPCtx {
109 unsigned int flags;
110 };
112 enum {
113 SP_XML_SPACE_DEFAULT,
114 SP_XML_SPACE_PRESERVE
115 };
117 class SPIXmlSpace;
119 /// Internal class consisting of two bits.
120 struct SPIXmlSpace {
121 guint set : 1;
122 guint value : 1;
123 };
125 class SPObject;
127 /*
128 * Refcounting
129 *
130 * Owner is here for debug reasons, you can set it to NULL safely
131 * Ref should return object, NULL is error, unref return always NULL
132 */
134 SPObject *sp_object_ref(SPObject *object, SPObject *owner=NULL);
135 SPObject *sp_object_unref(SPObject *object, SPObject *owner=NULL);
137 SPObject *sp_object_href(SPObject *object, gpointer owner);
138 SPObject *sp_object_hunref(SPObject *object, gpointer owner);
140 /// A refcounting tree node object.
141 struct SPObject : public GObject {
142 enum CollectionPolicy {
143 COLLECT_WITH_PARENT,
144 ALWAYS_COLLECT
145 };
147 unsigned int cloned : 1;
148 unsigned int uflags : 8;
149 unsigned int mflags : 8;
150 SPIXmlSpace xml_space;
151 unsigned int hrefcount; /* number of xlink:href references */
152 unsigned int _total_hrefcount; /* our hrefcount + total descendants */
153 SPDocument *document; /* Document we are part of */
154 SPObject *parent; /* Our parent (only one allowed) */
155 SPObject *children; /* Our children */
156 SPObject *_last_child; /* Remembered last child */
157 SPObject *next; /* Next object in linked list */
158 Inkscape::XML::Node *repr; /* Our xml representation */
159 gchar *id; /* Our very own unique id */
161 /**
162 * Represents the style properties, whether from presentation attributes, the <tt>style</tt>
163 * attribute, or inherited.
164 *
165 * sp_object_private_set doesn't handle SP_ATTR_STYLE or any presentation attributes at the
166 * time of writing, so this is probably NULL for all SPObject's that aren't an SPItem.
167 *
168 * However, this gives rise to the bugs mentioned in sp_object_get_style_property.
169 * Note that some non-SPItem SPObject's, such as SPStop, do need styling information,
170 * and need to inherit properties even through other non-SPItem parents like \<defs\>.
171 */
172 SPStyle *style;
174 /// Switch containing next() method.
175 struct ParentIteratorStrategy {
176 static SPObject const *next(SPObject const *object) {
177 return object->parent;
178 }
179 };
180 /// Switch containing next() method.
181 struct SiblingIteratorStrategy {
182 static SPObject const *next(SPObject const *object) {
183 return object->next;
184 }
185 };
187 typedef Inkscape::Util::ForwardPointerIterator<SPObject, ParentIteratorStrategy> ParentIterator;
188 typedef Inkscape::Util::ForwardPointerIterator<SPObject const, ParentIteratorStrategy> ConstParentIterator;
189 typedef Inkscape::Util::ForwardPointerIterator<SPObject, SiblingIteratorStrategy> SiblingIterator;
190 typedef Inkscape::Util::ForwardPointerIterator<SPObject const, SiblingIteratorStrategy> ConstSiblingIterator;
192 bool isSiblingOf(SPObject const *object) const {
193 g_return_val_if_fail(object != NULL, false);
194 return this->parent && this->parent == object->parent;
195 }
196 bool isAncestorOf(SPObject const *object) const;
198 SPObject const *nearestCommonAncestor(SPObject const *object) const;
199 /* A non-const version can be similarly constructed if you want one.
200 * (Don't just cast away the constness, which would be ill-formed.) */
202 bool hasChildren() const { return ( children != NULL ); }
204 SPObject *firstChild() { return children; }
205 SPObject const *firstChild() const { return children; }
206 SPObject *lastChild() { return _last_child; }
207 SPObject const *lastChild() const { return _last_child; }
209 SPObject *appendChildRepr(Inkscape::XML::Node *repr);
211 /** @brief Gets the author-visible label for this object. */
212 gchar const *label() const;
213 /** @brief Returns a default label for this object. */
214 gchar const *defaultLabel() const;
215 /** @brief Sets the author-visible label for this object.
216 *
217 * Sets the author-visible label for the object.
218 *
219 * @param label the new label
220 */
221 void setLabel(gchar const *label);
223 /** Retrieves the title of this object */
224 gchar const *title() const { return NULL; /* TODO */ }
225 /** Sets the title of this object */
226 void setTitle(gchar const *title) { /* TODO */ }
228 /** Retrieves the description of this object */
229 gchar const *desc() const { return NULL; /* TODO */ }
230 /** Sets the description of this object */
231 void setDesc(gchar const *desc) { /* TODO */ }
233 /** @brief Set the policy under which this object will be
234 * orphan-collected.
235 *
236 * Orphan-collection is the process of deleting all objects which no longer have
237 * hyper-references pointing to them. The policy determines when this happens. Many objects
238 * should not be deleted simply because they are no longer referred to; other objects (like
239 * "intermediate" gradients) are more or less throw-away and should always be collected when no
240 * longer in use.
241 *
242 * Along these lines, there are currently two orphan-collection policies:
243 *
244 * COLLECT_WITH_PARENT - don't worry about the object's hrefcount;
245 * if its parent is collected, this object
246 * will be too
247 *
248 * COLLECT_ALWAYS - always collect the object as soon as its
249 * hrefcount reaches zero
250 *
251 * @returns the current collection policy in effect for this object
252 */
253 CollectionPolicy collectionPolicy() const { return _collection_policy; }
255 /** @brief Sets the orphan-collection policy in effect for this object.
256 *
257 * @see SPObject::collectionPolicy
258 *
259 * @param policy the new policy to adopt
260 */
261 void setCollectionPolicy(CollectionPolicy policy) {
262 _collection_policy = policy;
263 }
265 /** @brief Requests a later automatic call to collectOrphan().
266 *
267 * This method requests that collectOrphan() be called during the document update cycle,
268 * deleting the object if it is no longer used.
269 *
270 * If the current collection policy is COLLECT_WITH_PARENT, this function has no effect.
271 *
272 * @see SPObject::collectOrphan
273 */
274 void requestOrphanCollection();
276 /** @brief Unconditionally delete the object if it is not referenced.
277 *
278 * Unconditionally delete the object if there are no outstanding hyper-references to it.
279 * Observers are not notified of the object's deletion (at the SPObject level; XML tree
280 * notifications still fire).
281 *
282 * @see SPObject::deleteObject
283 */
284 void collectOrphan() {
285 if ( _total_hrefcount == 0 ) {
286 deleteObject(false);
287 }
288 }
290 /** @brief Check if object is referenced by any other object.
291 */
292 bool isReferenced() { return ( _total_hrefcount > 0 ); }
294 /** @brief Deletes an object.
295 *
296 * Detaches the object's repr, and optionally sends notification that the object has been
297 * deleted.
298 *
299 * @param propagate notify observers that the object has been deleted?
300 *
301 * @param propagate_descendants notify observers of children that they have been deleted?
302 */
303 void deleteObject(bool propagate, bool propagate_descendants);
305 /** @brief Deletes on object.
306 *
307 * @param propagate Notify observers of this object and its children that they have been
308 * deleted?
309 */
310 void deleteObject(bool propagate=true) {
311 deleteObject(propagate, propagate);
312 }
314 /** @brief Connects a slot to be called when an object is deleted.
315 *
316 * This connects a slot to an object's internal delete signal, which is invoked when the object
317 * is deleted
318 *
319 * The signal is mainly useful for e.g. knowing when to break hrefs or dissociate clones.
320 *
321 * @param slot the slot to connect
322 *
323 * @see SPObject::deleteObject
324 */
325 sigc::connection connectDelete(sigc::slot<void, SPObject *> slot) {
326 return _delete_signal.connect(slot);
327 }
329 sigc::connection connectPositionChanged(sigc::slot<void, SPObject *> slot) {
330 return _position_changed_signal.connect(slot);
331 }
333 /** @brief Returns the object which supercedes this one (if any).
334 *
335 * This is mainly useful for ensuring we can correctly perform a series of moves or deletes,
336 * even if the objects in question have been replaced in the middle of the sequence.
337 */
338 SPObject *successor() { return _successor; }
340 /** @brief Indicates that another object supercedes this one. */
341 void setSuccessor(SPObject *successor) {
342 g_assert(successor != NULL);
343 g_assert(_successor == NULL);
344 g_assert(successor->_successor == NULL);
345 sp_object_ref(successor, NULL);
346 _successor = successor;
347 }
349 /* modifications; all three sets of methods should probably ultimately be protected, as they
350 * are not really part of its public interface. However, other parts of the code to
351 * occasionally use them at present. */
353 /* the no-argument version of updateRepr() is intended to be a bit more public, however -- it
354 * essentially just flushes any changes back to the backing store (the repr layer); maybe it
355 * should be called something else and made public at that point. */
357 /** @brief Updates the object's repr based on the object's state.
358 *
359 * This method updates the the repr attached to the object to reflect the object's current
360 * state; see the two-argument version for details.
361 *
362 * @param flags object write flags that apply to this update
363 *
364 * @return the updated repr
365 */
366 Inkscape::XML::Node *updateRepr(unsigned int flags=SP_OBJECT_WRITE_EXT);
368 /** @brief Updates the given repr based on the object's state.
369 *
370 * This method updates the given repr to reflect the object's current state. There are
371 * several flags that affect this:
372 *
373 * SP_OBJECT_WRITE_BUILD - create new reprs
374 *
375 * SP_OBJECT_WRITE_EXT - write elements and attributes
376 * which are not part of pure SVG
377 * (i.e. the Inkscape and Sodipodi
378 * namespaces)
379 *
380 * SP_OBJECT_WRITE_ALL - create all nodes and attributes,
381 * even those which might be redundant
382 *
383 * @param repr the repr to update
384 * @param flags object write flags that apply to this update
385 *
386 * @return the updated repr
387 */
388 Inkscape::XML::Node *updateRepr(Inkscape::XML::Node *repr, unsigned int flags);
390 /** @brief Queues an deferred update of this object's display.
391 *
392 * This method sets flags to indicate updates to be performed later, during the idle loop.
393 *
394 * There are several flags permitted here:
395 *
396 * SP_OBJECT_MODIFIED_FLAG - the object has been modified
397 *
398 * SP_OBJECT_CHILD_MODIFIED_FLAG - a child of the object has been
399 * modified
400 *
401 * SP_OBJECT_STYLE_MODIFIED_FLAG - the object's style has been
402 * modified
403 *
404 * There are also some subclass-specific modified flags which are hardly ever used.
405 *
406 * One of either MODIFIED or CHILD_MODIFIED is required.
407 *
408 * @param flags flags indicating what to update
409 */
410 void requestDisplayUpdate(unsigned int flags);
412 /** @brief Updates the object's display immediately
413 *
414 * This method is called during the idle loop by SPDocument in order to update the object's
415 * display.
416 *
417 * One additional flag is legal here:
418 *
419 * SP_OBJECT_PARENT_MODIFIED_FLAG - the parent has been
420 * modified
421 *
422 * @param ctx an SPCtx which accumulates various state
423 * during the recursive update -- beware! some
424 * subclasses try to cast this to an SPItemCtx *
425 *
426 * @param flags flags indicating what to update (in addition
427 * to any already set flags)
428 */
429 void updateDisplay(SPCtx *ctx, unsigned int flags);
431 /** @brief Requests that a modification notification signal
432 * be emitted later (e.g. during the idle loop)
433 *
434 * @param flags flags indicating what has been modified
435 */
436 void requestModified(unsigned int flags);
438 /** @brief Emits a modification notification signal
439 *
440 * @param flags indicating what has been modified
441 */
442 void emitModified(unsigned int flags);
444 void _sendDeleteSignalRecursive();
445 void _updateTotalHRefCount(int increment);
447 void _requireSVGVersion(unsigned major, unsigned minor) {
448 _requireSVGVersion(Inkscape::Version(major, minor));
449 }
450 void _requireSVGVersion(Inkscape::Version version);
452 sigc::signal<void, SPObject *> _delete_signal;
453 sigc::signal<void, SPObject *> _position_changed_signal;
454 SPObject *_successor;
455 CollectionPolicy _collection_policy;
456 gchar *_label;
457 mutable gchar *_default_label;
458 };
460 /// The SPObject vtable.
461 struct SPObjectClass {
462 GObjectClass parent_class;
464 void (* build) (SPObject *object, SPDocument *doc, Inkscape::XML::Node *repr);
465 void (* release) (SPObject *object);
467 /* Virtual handlers of repr signals */
468 void (* child_added) (SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *ref);
469 void (* remove_child) (SPObject *object, Inkscape::XML::Node *child);
471 void (* order_changed) (SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *old, Inkscape::XML::Node *new_repr);
473 void (* set) (SPObject *object, unsigned int key, gchar const *value);
475 void (* read_content) (SPObject *object);
477 /* Update handler */
478 void (* update) (SPObject *object, SPCtx *ctx, unsigned int flags);
479 /* Modification handler */
480 void (* modified) (SPObject *object, unsigned int flags);
482 Inkscape::XML::Node * (* write) (SPObject *object, Inkscape::XML::Node *repr, unsigned int flags);
483 };
486 /*
487 * Attaching/detaching
488 */
490 void sp_object_attach(SPObject *parent, SPObject *object, SPObject *prev);
491 void sp_object_reorder(SPObject *object, SPObject *prev);
492 void sp_object_detach(SPObject *parent, SPObject *object);
494 inline SPObject *sp_object_first_child(SPObject *parent) {
495 return parent->firstChild();
496 }
497 SPObject *sp_object_get_child_by_repr(SPObject *object, Inkscape::XML::Node *repr);
499 void sp_object_invoke_build(SPObject *object, SPDocument *document, Inkscape::XML::Node *repr, unsigned int cloned);
500 void sp_object_invoke_release(SPObject *object);
502 void sp_object_set(SPObject *object, unsigned int key, gchar const *value);
504 void sp_object_read_attr(SPObject *object, gchar const *key);
506 /*
507 * Get and set descriptive parameters.
508 *
509 * These are inefficent, so they are not intended to be used interactively.
510 */
512 gchar const *sp_object_title_get(SPObject *object);
513 gchar const *sp_object_description_get(SPObject *object);
514 unsigned int sp_object_title_set(SPObject *object, gchar const *title);
515 unsigned int sp_object_description_set(SPObject *object, gchar const *desc);
517 /* Public */
519 gchar const *sp_object_tagName_get(SPObject const *object, SPException *ex);
520 gchar const *sp_object_getAttribute(SPObject const *object, gchar const *key, SPException *ex);
521 void sp_object_setAttribute(SPObject *object, gchar const *key, gchar const *value, SPException *ex);
522 void sp_object_removeAttribute(SPObject *object, gchar const *key, SPException *ex);
524 /* Style */
526 gchar const *sp_object_get_style_property(SPObject const *object,
527 gchar const *key, gchar const *def);
529 Inkscape::Version sp_object_get_sodipodi_version(SPObject *object);
531 int sp_object_compare_position(SPObject const *first, SPObject const *second);
533 SPObject *sp_object_prev(SPObject *child);
536 #endif
539 /*
540 Local Variables:
541 mode:c++
542 c-file-style:"stroustrup"
543 c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
544 indent-tabs-mode:nil
545 fill-column:99
546 End:
547 */
548 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :