NAObject

NAObject — The Deepest Base Class Definition

Synopsis

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

#define             NA_TYPE_OBJECT
#define             NA_OBJECT                           (object)
#define             NA_IS_OBJECT                        (object)
                    NAObject;
                    NAObjectClass;
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_dump               (const NAObject *object);
void                na_object_object_dump_norec         (const NAObject *object);
void                na_object_object_dump_tree          (GList *tree);
void                na_object_object_check_status_rec   (const NAObject *object);
GList *             na_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.

All the API described here is rather private. External code should use the API described in caja-actions/na-object-api.h.

Details

NA_TYPE_OBJECT

#define NA_TYPE_OBJECT                ( na_object_object_get_type())

NA_OBJECT()

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

NA_IS_OBJECT()

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

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.
	 *
	 * The derived class should call its parent class at the end of the
	 * dump of its own datas.
	 *
	 * Since: 2.30
	 */
	void     ( *dump )     ( const NAObject *object );

	/**
	 * copy:
	 * @target: the NAObject-derived object which will receive data.
	 * @source: the NAObject-derived object which provides data.
	 * @mode: the copy mode.
	 *
	 * Copies data and properties from @source to @target.
	 *
	 * The derived class should call its parent class at the end of the
	 * copy of its own datas.
	 *
	 * Since: 2.30
	 */
	void     ( *copy )     ( NAObject *target, const NAObject *source, guint mode );

	/**
	 * are_equal:
	 * @a: a first NAObject object.
	 * @b: a second NAObject object to be compared to the first one.
	 *
	 * Compares the two objects.
	 *
	 * When testing for the modification status of an object, @a stands for
	 * the original object, while @b stands for the duplicated one.
	 *
	 * As long as no difference is detected, the derived class should call
	 * its parent class at the end of its comparison.
	 * As soon as a difference is detected, the calling sequence should
	 * 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 identifier is set.
	 *
	 * As long as the item is valid, the derived class should call its parent
	 * at the end of its checks.
	 * As soon as an error is detected, the calling sequence should 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_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 object.

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.

Note that we may want to free a copy+ref of a list of items whichy have had already disposed (which is probably a bug somewhere). So first test is the object is still alive.

object :

a NAObject -derived object.

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, children 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_check_status_rec ()

void                na_object_object_check_status_rec   (const NAObject *object);

Recursively checks for the edition status of object and its children (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_rec( object )
 +- na_iduplicable_check_status( object )
     +- get_origin( object )
     +- modified_status = v_are_equal( origin, object )
     |  +-> interface NAObjectClass::are_equal
     |      which happens to be iduplicable_are_equal( a, b )
     |       +- v_are_equal( a, b )
     |           +- NAObjectAction::are_equal()
     |               +- na_factory_object_are_equal()
     |               +- check NAObjectActionPrivate data
     |               +- call parent class
     |                  +- NAObjectItem::are_equal()
     |                      +- check NAObjectItemPrivate data
     |                      +- call parent class
     |                          +- NAObjectId::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 children is actually checked before those of the parent.

As of 3.1.0: . 

  • when the modification status of a NAObjectProfile changes, then its NAObjectAction parent is rechecked;

  • when the validity status of an object is changed, then its parent is also rechecked.

object :

the NAObject -derived object to be checked.

Since 2.30


na_object_get_hierarchy ()

GList *             na_object_get_hierarchy             (const NAObject *object);

Warning

na_object_get_hierarchy is deprecated and should not be used in newly-written code. 3.1

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);

Warning

na_object_free_hierarchy is deprecated and should not be used in newly-written code. 3.1

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