NAObject

NAObject — The Deepest Base Class Definition

Synopsis

#include <nautilus-actions/na-object.h>

#define             NA_OBJECT_TYPE
#define             NA_OBJECT                           (object)
#define             NA_IS_OBJECT                        (object)
                    NAObject;
                    NAObjectClass;
void                na_object_object_check_status       (const NAObject *object);
gboolean            na_object_object_check_status_up    (const NAObject *object);
void                na_object_object_reset_origin       (NAObject *object,
                                                         const NAObject *origin);
NAObject *          na_object_object_ref                (NAObject *object);
void                na_object_object_unref              (NAObject *object);
void                na_object_object_copy               (NAObject *target,
                                                         const NAObject *source,
                                                         gboolean recursive);
void                na_object_object_dump               (const NAObject *object);
void                na_object_object_dump_norec         (const NAObject *object);
void                na_object_object_dump_tree          (GList *tree);
GList *             na_object_object_get_hierarchy      (const NAObject *object);
void                na_object_free_hierarchy            (GList *hierarchy);
void                na_object_object_debug_invalid      (const NAObject *object,
                                                         const gchar *reason);

Object Hierarchy

  GObject
   +----NAObject
         +----NAObjectId

Implemented Interfaces

NAObject implements NAIDuplicable.

Description

This is the base class of all our data object hierarchy. NAObject is supposed to be used as a pure virtual base class, i.e. should only be derived.

Details

NA_OBJECT_TYPE

#define NA_OBJECT_TYPE                  ( na_object_object_get_type())

NA_OBJECT()

#define NA_OBJECT( object )             ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_TYPE, NAObject ))

NA_IS_OBJECT()

#define NA_IS_OBJECT( object )          ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_TYPE ))

NAObject

typedef struct _NAObject NAObject;

NAObjectClass

typedef struct {
	/**
	 * dump:
	 * @object: the NAObject-derived object to be dumped.
	 *
	 * Dumps via g_debug the content of the object.
	 *
	 * NAObject class takes care of calling this function for each
	 * derived class, starting from topmost base class up to most-
	 * derived one. Each derived class has so only to take care of
	 * dumping its own data.
	 *
	 * Since: 2.30
	 */
	void     ( *dump )     ( const NAObject *object );

	/**
	 * copy:
	 * @target: the NAObject-derived object which will receive data.
	 * @source: the NAObject-derived object which will provide data.
	 * @recursive: whether children should be recursively copied.
	 *
	 * Copies data and properties from @source to @target.
	 *
	 * Each derived class should take care of implementing this function
	 * when relevant. NAObject class will take care of calling this
	 * function for each class of the hierarchy, starting from topmost
	 * base class up to the most-derived one. Each class has so only to
	 * take care of dumping its own data.
	 *
	 * Since: 2.30
	 */
	void     ( *copy )     ( NAObject *target, const NAObject *source, gboolean recursive );

	/**
	 * are_equal:
	 * @a: a first NAObject object.
	 * @b: a second NAObject object to be compared to the first one.
	 *
	 * Compares the two objects.
	 *
	 * Each derived class should take care of implementing this function
	 * when relevant. NAObject class will take care of calling this
	 * function for each class of the hierarchy, starting from topmost
	 * base class up to the most-derived one, at least while result
	 * stays at TRUE.
	 * As soon as a difference is detected, the calling sequence will
	 * be stopped, and the result returned.
	 *
	 * Returns: TRUE if @a and @b are identical, FALSE else.
	 *
	 * Since: 2.30
	 */
	gboolean ( *are_equal )( const NAObject *a, const NAObject *b );

	/**
	 * is_valid:
	 * @object: the NAObject object to be checked.
	 *
	 * Checks @object for validity.
	 *
	 * A NAObject is valid if its internal identifiant is set.
	 *
	 * Each derived class should take care of implementing this function
	 * when relevant. NAObject class will take care of calling this
	 * function for each class of the hierarchy, starting from topmost
	 * base class up to the most-derived one, at least while result
	 * stays at TRUE.
	 * As soon as a difference is detected, the calling sequence will
	 * be stopped, and the result returned.
	 *
	 * Returns: TRUE if @object is valid, FALSE else.
	 *
	 * Since: 2.30
	 */
	gboolean ( *is_valid ) ( const NAObject *object );
} NAObjectClass;

The NAObjectClass defines some methods available to derived classes.

dump ()

Dumps the NAObject -part of the NAObject -derived object.

copy ()

Copies a NAObject to another.

are_equal ()

Tests if two NAObject are equal.

is_valid ()

Tests if a NAObject is valid.

na_object_object_check_status ()

void                na_object_object_check_status       (const NAObject *object);

Recursively checks for the edition status of object and its childs (if any).

Internally set some properties which may be requested later. This two-steps check-request let us optimize some work in the UI.

na_object_object_check_status( object ) +- na_iduplicable_check_status( object ) +- get_origin( object ) +- modified_status = v_are_equal( origin, object ) -> interface NAObjectClass::are_equal +- valid_status = v_is_valid( object ) -> interface NAObjectClass::is_valid

Note that the recursivity is managed here, so that we can be sure that edition status of childs is actually checked before those of the parent.

object :

the NAObject -derived object to be checked.

Since 2.30


na_object_object_check_status_up ()

gboolean            na_object_object_check_status_up    (const NAObject *object);

Checks for modification and validity status of the object, its parent, the parent of its parent, etc. up to the top of the hierarchy.

Checking the modification of any of the status should be more efficient that systematically force the display of the item.

object :

the object at the start of the hierarchy.

Returns :

TRUE if at least one of the status has changed, FALSE else.

Since 2.30


na_object_object_reset_origin ()

void                na_object_object_reset_origin       (NAObject *object,
                                                         const NAObject *origin);

Recursively reset origin of object and its children to origin (and its children), so that origin appears as the actual origin of object.

The origin of origin itself is set to NULL.

This only works if origin has just been duplicated from object, and thus we do not have to check if children lists are equal.

object :

a NAObject -derived object.

origin :

must be a duplication of object.

Since 2.30


na_object_object_ref ()

NAObject *          na_object_object_ref                (NAObject *object);

Recursively ref the object and all its children, incrementing their reference_count by 1.

object :

a NAObject -derived object.

Returns :

a reference on the pbject.

Since 2.30


na_object_object_unref ()

void                na_object_object_unref              (NAObject *object);

Recursively unref the object and all its children, decrementing their reference_count by 1.

object :

a NAObject -derived object.

Since 2.30


na_object_object_copy ()

void                na_object_object_copy               (NAObject *target,
                                                         const NAObject *source,
                                                         gboolean recursive);

Copies source to target.

target :

the target NAObject -derived object.

source :

the source NAObject -derived object.

recursive :

whether the copy should be recursive.

Since 2.30


na_object_object_dump ()

void                na_object_object_dump               (const NAObject *object);

Dumps via g_debug() the actual content of the object.

The recursivity is dealt with here because, if we would let NAObjectItem do this, the dump of NAObjectItem -derived object would be splitted, childs being inserted inside.

na_object_dump() doesn't modify the reference count of the dumped object.

object :

the NAObject -derived object to be dumped.

Since 2.30


na_object_object_dump_norec ()

void                na_object_object_dump_norec         (const NAObject *object);

Dumps via g_debug the actual content of the object.

This function is not recursive.

object :

the NAObject -derived object to be dumped.

Since 2.30


na_object_object_dump_tree ()

void                na_object_object_dump_tree          (GList *tree);

Outputs a brief, hierarchical dump of the provided list.

tree :

a hierarchical list of NAObject -derived objects.

Since 2.30


na_object_object_get_hierarchy ()

GList *             na_object_object_get_hierarchy      (const NAObject *object);

object :

the NAObject -derived object.

Returns :

the class hierarchy, from the topmost base class, to the most-derived one.

Since 2.30


na_object_free_hierarchy ()

void                na_object_free_hierarchy            (GList *hierarchy);

Releases the NAObject hierarchy.

hierarchy :

the GList of hierarchy, as returned from na_object_get_hierarchy().

Since 2.30


na_object_object_debug_invalid ()

void                na_object_object_debug_invalid      (const NAObject *object,
                                                         const gchar *reason);

Dump the object with the invalidity reason.

object :

the NAObject -derived object which is invalid.

reason :

the reason.

Since 2.30