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 /** @brief cleans up an SPObject, releasing its references and
162 * requesting that references to it be released
163 */
164 void releaseReferences();
166 /** @brief connects to the release request signal
167 *
168 * @param slot the slot to connect
169 *
170 * @returns the sigc::connection formed
171 */
172 sigc::connection connectRelease(sigc::slot<void, SPObject *> slot) {
173 return _release_signal.connect(slot);
174 }
176 /**
177 * Represents the style properties, whether from presentation attributes, the <tt>style</tt>
178 * attribute, or inherited.
179 *
180 * sp_object_private_set doesn't handle SP_ATTR_STYLE or any presentation attributes at the
181 * time of writing, so this is probably NULL for all SPObject's that aren't an SPItem.
182 *
183 * However, this gives rise to the bugs mentioned in sp_object_get_style_property.
184 * Note that some non-SPItem SPObject's, such as SPStop, do need styling information,
185 * and need to inherit properties even through other non-SPItem parents like \<defs\>.
186 */
187 SPStyle *style;
189 /// Switch containing next() method.
190 struct ParentIteratorStrategy {
191 static SPObject const *next(SPObject const *object) {
192 return object->parent;
193 }
194 };
195 /// Switch containing next() method.
196 struct SiblingIteratorStrategy {
197 static SPObject const *next(SPObject const *object) {
198 return object->next;
199 }
200 };
202 typedef Inkscape::Util::ForwardPointerIterator<SPObject, ParentIteratorStrategy> ParentIterator;
203 typedef Inkscape::Util::ForwardPointerIterator<SPObject const, ParentIteratorStrategy> ConstParentIterator;
204 typedef Inkscape::Util::ForwardPointerIterator<SPObject, SiblingIteratorStrategy> SiblingIterator;
205 typedef Inkscape::Util::ForwardPointerIterator<SPObject const, SiblingIteratorStrategy> ConstSiblingIterator;
207 bool isSiblingOf(SPObject const *object) const {
208 g_return_val_if_fail(object != NULL, false);
209 return this->parent && this->parent == object->parent;
210 }
211 bool isAncestorOf(SPObject const *object) const;
213 SPObject const *nearestCommonAncestor(SPObject const *object) const;
214 /* A non-const version can be similarly constructed if you want one.
215 * (Don't just cast away the constness, which would be ill-formed.) */
217 bool hasChildren() const { return ( children != NULL ); }
219 SPObject *firstChild() { return children; }
220 SPObject const *firstChild() const { return children; }
221 SPObject *lastChild() { return _last_child; }
222 SPObject const *lastChild() const { return _last_child; }
224 enum Action { ActionGeneral, ActionBBox, ActionUpdate, ActionShow };
225 /** @brief Retrieves children as a GSList */
226 GSList *childList(bool add_ref, Action action = ActionGeneral);
228 SPObject *appendChildRepr(Inkscape::XML::Node *repr);
230 /** @brief Gets the author-visible label for this object. */
231 gchar const *label() const;
232 /** @brief Returns a default label for this object. */
233 gchar const *defaultLabel() const;
234 /** @brief Sets the author-visible label for this object.
235 *
236 * Sets the author-visible label for the object.
237 *
238 * @param label the new label
239 */
240 void setLabel(gchar const *label);
242 /** Retrieves the title of this object */
243 gchar const *title() const { return NULL; /* TODO */ }
244 /** Sets the title of this object */
245 void setTitle(gchar const *title) { (void)title; /* TODO */ }
247 /** Retrieves the description of this object */
248 gchar const *desc() const { return NULL; /* TODO */ }
249 /** Sets the description of this object */
250 void setDesc(gchar const *desc) { (void)desc; /* TODO */ }
252 /** @brief Set the policy under which this object will be
253 * orphan-collected.
254 *
255 * Orphan-collection is the process of deleting all objects which no longer have
256 * hyper-references pointing to them. The policy determines when this happens. Many objects
257 * should not be deleted simply because they are no longer referred to; other objects (like
258 * "intermediate" gradients) are more or less throw-away and should always be collected when no
259 * longer in use.
260 *
261 * Along these lines, there are currently two orphan-collection policies:
262 *
263 * COLLECT_WITH_PARENT - don't worry about the object's hrefcount;
264 * if its parent is collected, this object
265 * will be too
266 *
267 * COLLECT_ALWAYS - always collect the object as soon as its
268 * hrefcount reaches zero
269 *
270 * @returns the current collection policy in effect for this object
271 */
272 CollectionPolicy collectionPolicy() const { return _collection_policy; }
274 /** @brief Sets the orphan-collection policy in effect for this object.
275 *
276 * @see SPObject::collectionPolicy
277 *
278 * @param policy the new policy to adopt
279 */
280 void setCollectionPolicy(CollectionPolicy policy) {
281 _collection_policy = policy;
282 }
284 /** @brief Requests a later automatic call to collectOrphan().
285 *
286 * This method requests that collectOrphan() be called during the document update cycle,
287 * deleting the object if it is no longer used.
288 *
289 * If the current collection policy is COLLECT_WITH_PARENT, this function has no effect.
290 *
291 * @see SPObject::collectOrphan
292 */
293 void requestOrphanCollection();
295 /** @brief Unconditionally delete the object if it is not referenced.
296 *
297 * Unconditionally delete the object if there are no outstanding hyper-references to it.
298 * Observers are not notified of the object's deletion (at the SPObject level; XML tree
299 * notifications still fire).
300 *
301 * @see SPObject::deleteObject
302 */
303 void collectOrphan() {
304 if ( _total_hrefcount == 0 ) {
305 deleteObject(false);
306 }
307 }
309 /** @brief Check if object is referenced by any other object.
310 */
311 bool isReferenced() { return ( _total_hrefcount > 0 ); }
313 /** @brief Deletes an object.
314 *
315 * Detaches the object's repr, and optionally sends notification that the object has been
316 * deleted.
317 *
318 * @param propagate notify observers that the object has been deleted?
319 *
320 * @param propagate_descendants notify observers of children that they have been deleted?
321 */
322 void deleteObject(bool propagate, bool propagate_descendants);
324 /** @brief Deletes on object.
325 *
326 * @param propagate Notify observers of this object and its children that they have been
327 * deleted?
328 */
329 void deleteObject(bool propagate=true) {
330 deleteObject(propagate, propagate);
331 }
333 /** @brief Connects a slot to be called when an object is deleted.
334 *
335 * This connects a slot to an object's internal delete signal, which is invoked when the object
336 * is deleted
337 *
338 * The signal is mainly useful for e.g. knowing when to break hrefs or dissociate clones.
339 *
340 * @param slot the slot to connect
341 *
342 * @see SPObject::deleteObject
343 */
344 sigc::connection connectDelete(sigc::slot<void, SPObject *> slot) {
345 return _delete_signal.connect(slot);
346 }
348 sigc::connection connectPositionChanged(sigc::slot<void, SPObject *> slot) {
349 return _position_changed_signal.connect(slot);
350 }
352 /** @brief Returns the object which supercedes this one (if any).
353 *
354 * This is mainly useful for ensuring we can correctly perform a series of moves or deletes,
355 * even if the objects in question have been replaced in the middle of the sequence.
356 */
357 SPObject *successor() { return _successor; }
359 /** @brief Indicates that another object supercedes this one. */
360 void setSuccessor(SPObject *successor) {
361 g_assert(successor != NULL);
362 g_assert(_successor == NULL);
363 g_assert(successor->_successor == NULL);
364 sp_object_ref(successor, NULL);
365 _successor = successor;
366 }
368 /* modifications; all three sets of methods should probably ultimately be protected, as they
369 * are not really part of its public interface. However, other parts of the code to
370 * occasionally use them at present. */
372 /* the no-argument version of updateRepr() is intended to be a bit more public, however -- it
373 * essentially just flushes any changes back to the backing store (the repr layer); maybe it
374 * should be called something else and made public at that point. */
376 /** @brief Updates the object's repr based on the object's state.
377 *
378 * This method updates the the repr attached to the object to reflect the object's current
379 * state; see the two-argument version for details.
380 *
381 * @param flags object write flags that apply to this update
382 *
383 * @return the updated repr
384 */
385 Inkscape::XML::Node *updateRepr(unsigned int flags=SP_OBJECT_WRITE_EXT);
387 /** @brief Updates the given repr based on the object's state.
388 *
389 * This method updates the given repr to reflect the object's current state. There are
390 * several flags that affect this:
391 *
392 * SP_OBJECT_WRITE_BUILD - create new reprs
393 *
394 * SP_OBJECT_WRITE_EXT - write elements and attributes
395 * which are not part of pure SVG
396 * (i.e. the Inkscape and Sodipodi
397 * namespaces)
398 *
399 * SP_OBJECT_WRITE_ALL - create all nodes and attributes,
400 * even those which might be redundant
401 *
402 * @param repr the repr to update
403 * @param flags object write flags that apply to this update
404 *
405 * @return the updated repr
406 */
407 Inkscape::XML::Node *updateRepr(Inkscape::XML::Node *repr, unsigned int flags);
409 /** @brief Queues an deferred update of this object's display.
410 *
411 * This method sets flags to indicate updates to be performed later, during the idle loop.
412 *
413 * There are several flags permitted here:
414 *
415 * SP_OBJECT_MODIFIED_FLAG - the object has been modified
416 *
417 * SP_OBJECT_CHILD_MODIFIED_FLAG - a child of the object has been
418 * modified
419 *
420 * SP_OBJECT_STYLE_MODIFIED_FLAG - the object's style has been
421 * modified
422 *
423 * There are also some subclass-specific modified flags which are hardly ever used.
424 *
425 * One of either MODIFIED or CHILD_MODIFIED is required.
426 *
427 * @param flags flags indicating what to update
428 */
429 void requestDisplayUpdate(unsigned int flags);
431 /** @brief Updates the object's display immediately
432 *
433 * This method is called during the idle loop by SPDocument in order to update the object's
434 * display.
435 *
436 * One additional flag is legal here:
437 *
438 * SP_OBJECT_PARENT_MODIFIED_FLAG - the parent has been
439 * modified
440 *
441 * @param ctx an SPCtx which accumulates various state
442 * during the recursive update -- beware! some
443 * subclasses try to cast this to an SPItemCtx *
444 *
445 * @param flags flags indicating what to update (in addition
446 * to any already set flags)
447 */
448 void updateDisplay(SPCtx *ctx, unsigned int flags);
450 /** @brief Requests that a modification notification signal
451 * be emitted later (e.g. during the idle loop)
452 *
453 * @param flags flags indicating what has been modified
454 */
455 void requestModified(unsigned int flags);
457 /** @brief Emits a modification notification signal
458 *
459 * @param flags indicating what has been modified
460 */
461 void emitModified(unsigned int flags);
463 /** @brief Connects to the modification notification signal
464 *
465 * @param slot the slot to connect
466 *
467 * @returns the connection formed thereby
468 */
469 sigc::connection connectModified(
470 sigc::slot<void, SPObject *, unsigned int> slot
471 ) {
472 return _modified_signal.connect(slot);
473 }
475 void _sendDeleteSignalRecursive();
476 void _updateTotalHRefCount(int increment);
478 void _requireSVGVersion(unsigned major, unsigned minor) {
479 _requireSVGVersion(Inkscape::Version(major, minor));
480 }
481 void _requireSVGVersion(Inkscape::Version version);
483 sigc::signal<void, SPObject *> _release_signal;
484 sigc::signal<void, SPObject *> _delete_signal;
485 sigc::signal<void, SPObject *> _position_changed_signal;
486 sigc::signal<void, SPObject *, unsigned int> _modified_signal;
487 SPObject *_successor;
488 CollectionPolicy _collection_policy;
489 gchar *_label;
490 mutable gchar *_default_label;
491 };
493 /// The SPObject vtable.
494 struct SPObjectClass {
495 GObjectClass parent_class;
497 void (* build) (SPObject *object, SPDocument *doc, Inkscape::XML::Node *repr);
498 void (* release) (SPObject *object);
500 /* Virtual handlers of repr signals */
501 void (* child_added) (SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *ref);
502 void (* remove_child) (SPObject *object, Inkscape::XML::Node *child);
504 void (* order_changed) (SPObject *object, Inkscape::XML::Node *child, Inkscape::XML::Node *old, Inkscape::XML::Node *new_repr);
506 void (* set) (SPObject *object, unsigned int key, gchar const *value);
508 void (* read_content) (SPObject *object);
510 /* Update handler */
511 void (* update) (SPObject *object, SPCtx *ctx, unsigned int flags);
512 /* Modification handler */
513 void (* modified) (SPObject *object, unsigned int flags);
515 Inkscape::XML::Node * (* write) (SPObject *object, Inkscape::XML::Node *repr, unsigned int flags);
516 };
519 /*
520 * Attaching/detaching
521 */
523 void sp_object_attach(SPObject *parent, SPObject *object, SPObject *prev);
524 void sp_object_reorder(SPObject *object, SPObject *prev);
525 void sp_object_detach(SPObject *parent, SPObject *object);
527 inline SPObject *sp_object_first_child(SPObject *parent) {
528 return parent->firstChild();
529 }
530 SPObject *sp_object_get_child_by_repr(SPObject *object, Inkscape::XML::Node *repr);
532 void sp_object_invoke_build(SPObject *object, SPDocument *document, Inkscape::XML::Node *repr, unsigned int cloned);
534 void sp_object_set(SPObject *object, unsigned int key, gchar const *value);
536 void sp_object_read_attr(SPObject *object, gchar const *key);
538 /*
539 * Get and set descriptive parameters.
540 *
541 * These are inefficent, so they are not intended to be used interactively.
542 */
544 gchar const *sp_object_title_get(SPObject *object);
545 gchar const *sp_object_description_get(SPObject *object);
546 unsigned int sp_object_title_set(SPObject *object, gchar const *title);
547 unsigned int sp_object_description_set(SPObject *object, gchar const *desc);
549 /* Public */
551 gchar const *sp_object_tagName_get(SPObject const *object, SPException *ex);
552 gchar const *sp_object_getAttribute(SPObject const *object, gchar const *key, SPException *ex);
553 void sp_object_setAttribute(SPObject *object, gchar const *key, gchar const *value, SPException *ex);
554 void sp_object_removeAttribute(SPObject *object, gchar const *key, SPException *ex);
556 /* Style */
558 gchar const *sp_object_get_style_property(SPObject const *object,
559 gchar const *key, gchar const *def);
561 Inkscape::Version sp_object_get_sodipodi_version(SPObject *object);
563 int sp_object_compare_position(SPObject const *first, SPObject const *second);
565 SPObject *sp_object_prev(SPObject *child);
568 #endif
571 /*
572 Local Variables:
573 mode:c++
574 c-file-style:"stroustrup"
575 c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
576 indent-tabs-mode:nil
577 fill-column:99
578 End:
579 */
580 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :