NAObject

## 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