FMAIDuplicable

## FMAIDuplicable FMAIDuplicable — The Duplication Interface |

## Functions

#define | FMA_IDUPLICABLE()
#define | FMA_IS_IDUPLICABLE()
#define | FMA_IDUPLICABLE_GET_INTERFACE()
void | fma_iduplicable_dispose ()
void | fma_iduplicable_dump ()
FMAIDuplicable * | fma_iduplicable_duplicate ()
void | fma_iduplicable_check_status ()
FMAIDuplicable * | fma_iduplicable_get_origin ()
gboolean | fma_iduplicable_is_valid ()
gboolean | fma_iduplicable_is_modified ()
void | fma_iduplicable_set_origin ()
void | fma_iduplicable_set_modified ()
void | fma_iduplicable_register_consumer ()

## Types and Values

#define | FMA_TYPE_IDUPLICABLE
| FMAIDuplicable
| FMAIDuplicableInterface
#define | IDUPLICABLE_SIGNAL_MODIFIED_CHANGED
#define | IDUPLICABLE_SIGNAL_VALID_CHANGED
enum | FMADuplicableMode

## Includes

    #include <filemanager-actions/private/fma-iduplicable.h>

## Description

This interface is implemented by FMAObject in order to let FMAObject -derived instance duplication be easily tracked. This works by keeping a pointer on the original object at duplication time, and then only checking edition status when explicitely required.

As the reference count of the original object is not incremented here, the caller has to garantee itself that the original object will stay in life at least as long as the duplicated one.

### Modification status in FileManager-Actions configuration tool

- Objects whose origin is NULL are considered as modified ; this is in particular the case of new, pasted, imported and dropped objects.

- when a new object, whether is is really new or it has been pasted, imported or dropped, is inserted somewhere in the tree, its immediate parent is also marked as modified.

- Check for edition status, which positions modification and validity status, is not recursive ; it is the responsability of the implementation to check for edition status of children of object..

### Versions historic

Table 9. Historic of the versions of the FMAIDuplicable interface

FileManager-Actions™ version | FMAIDuplicable interface version |
--- | --- | ---
since 2.30 | 1 | current version

## Functions

### FMA_IDUPLICABLE()

    #define FMA_IDUPLICABLE( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, FMA_TYPE_IDUPLICABLE, FMAIDuplicable ))

### FMA_IS_IDUPLICABLE()

    #define FMA_IS_IDUPLICABLE( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, FMA_TYPE_IDUPLICABLE ))

### FMA_IDUPLICABLE_GET_INTERFACE()

    #define FMA_IDUPLICABLE_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), FMA_TYPE_IDUPLICABLE, FMAIDuplicableInterface ))

### fma_iduplicable_dispose ()

    void
    fma_iduplicable_dispose (const FMAIDuplicable *object);

Releases resources.

#### Parameters

object | the FMAIDuplicable object to be initialized. |

Since: 2.30

### fma_iduplicable_dump ()

    void
    fma_iduplicable_dump (const FMAIDuplicable *object);

Dumps via g_debug the properties of the object.

We ouput here only the data we set ourselves againt the FMAIDuplicable -implemented object.

This function should be called by the implementation when it dumps itself its own content.

#### Parameters

object | the FMAIDuplicable object to be dumped. |

Since: 2.30

### fma_iduplicable_duplicate ()

    FMAIDuplicable *
    fma_iduplicable_duplicate (const FMAIDuplicable *object,
                               guint mode);

Exactly duplicates a FMAIDuplicable -implemented object, including modification and validity status which are copied from `object` to the duplicated one.

#### Parameters

object | the FMAIDuplicable object to be duplicated. |
mode | the `FMADuplicableMode` duplication mode. |

#### Returns

a new FMAIDuplicable.

Since: 2.30

### fma_iduplicable_check_status ()

    void
    fma_iduplicable_check_status (const FMAIDuplicable *object);

Checks the edition status of the FMAIDuplicable object, and set up the corresponding properties.

This function is supposed to be called each time the object may have been modified in order to set the corresponding properties. Helper functions `fma_iduplicable_is_modified()` and `fma_iduplicable_is_valid()` will then only return the current value of the properties.

fma_iduplicable_check_status() is not, as itself, recursive. That is, the modification and validity status are only set on the specified object. FMAObject implementation has chosen to handle itself the recursivity: `fma_object_check_status()` so first check status for children, before calling this function.

#### Parameters

object | the FMAIDuplicable object to be checked. |

Since: 2.30

### fma_iduplicable_get_origin ()

    FMAIDuplicable *
    fma_iduplicable_get_origin (const FMAIDuplicable *object);

Returns the origin of a duplicated FMAIDuplicable.

#### Parameters

object | the FMAIDuplicable object whose origin is to be returned. |

#### Returns

the original FMAIDuplicable, or NULL.

Since: 2.30

### fma_iduplicable_is_valid ()

    gboolean
    fma_iduplicable_is_valid (const FMAIDuplicable *object);

Returns the current value of the relevant property without rechecking the edition status itself.

#### Parameters

object | the FMAIDuplicable object whose status is to be returned. |

#### Returns

`TRUE` is the provided object is valid.

Since: 2.30

### fma_iduplicable_is_modified ()

    gboolean
    fma_iduplicable_is_modified (const FMAIDuplicable *object);

Returns the current value of the 'is_modified' property without rechecking the edition status itself.

#### Parameters

object | the FMAIDuplicable object whose status is to be returned. |

#### Returns

`TRUE` is the provided object has been modified regarding of the original one.

Since: 2.30

### fma_iduplicable_set_origin ()

    void
    fma_iduplicable_set_origin (FMAIDuplicable *object,
                                const FMAIDuplicable *origin);

Sets the new origin of a duplicated FMAIDuplicable.

#### Parameters

object | the FMAIDuplicable object whose origin is to be set. |
origin | the new original FMAIDuplicable. |

Since: 2.30

### fma_iduplicable_set_modified ()

    void
    fma_iduplicable_set_modified (FMAIDuplicable *object,
                                  gboolean modified);

`fma_iduplicable_set_modified` has been deprecated since version 3.1 and should not be used in newly-written code.

Sets the new modification status of a duplicated FMAIDuplicable.

#### Parameters

object | the FMAIDuplicable object whose modification status is to be set. |
modified | the new modification status FMAIDuplicable. |

Since: 2.30

### fma_iduplicable_register_consumer ()

    void
    fma_iduplicable_register_consumer (GObject *consumer);

This function registers a consumer, i.e. an instance to which edition status signals will be propagated.

#### Parameters

consumer | the target instance. |

Since: 2.30

## Types and Values

### FMA_TYPE_IDUPLICABLE

    #define FMA_TYPE_IDUPLICABLE                      ( fma_iduplicable_get_type())

### FMAIDuplicable

    typedef struct _FMAIDuplicable FMAIDuplicable;

### FMAIDuplicableInterface

    typedef struct {
    	/**
    	 * copy:
    	 * @target: the #FMAIDuplicable target of the copy.
    	 * @source: the #FMAIDuplicable source of the copy.
    	 * @mode: the duplication mode.
    	 *
    	 * Copies data from @source to @ŧarget, so that @target becomes an
    	 * exact copy of @source.
    	 *
    	 * Each derived class of the implementation should define this
    	 * function to copy its own data. The implementation should take
    	 * care itself of calling each function in the class hierarchy,
    	 * from topmost base class to most-derived one.
    	 *
    	 * Since: 2.30
    	 */
    	void     ( *copy )      ( FMAIDuplicable *target, const FMAIDuplicable *source, guint mode );

    	/**
    	 * are_equal:
    	 * @a: a first #FMAIDuplicable object.
    	 * @b: a second #FMAIDuplicable object to be compared to the first
    	 * one.
    	 *
    	 * Compares the two objects.
    	 *
    	 * Each derived class of the implementation should define this
    	 * function to compare its own data. The implementation should take
    	 * care itself of calling each function in the class hierarchy,
    	 * from topmost base class to most-derived one.
    	 *
    	 * When testing for the modification status of an object, @a stands for
    	 * the original object, while @b stands for the duplicated one.
    	 *
    	 * Returns: TRUE if @a and @b are identical, FALSE else.
    	 *
    	 * Since: 2.30
    	 */
    	gboolean ( *are_equal ) ( const FMAIDuplicable *a, const FMAIDuplicable *b );

    	/**
    	 * is_valid:
    	 * @object: the FMAIDuplicable object to be checked.
    	 *
    	 * Checks @object for validity.
    	 *
    	 * Each derived class of the implementation should define this
    	 * function to compare its own data. The implementation should take
    	 * care itself of calling each function in the class hierarchy,
    	 * from topmost base class to most-derived one.
    	 *
    	 * Returns: TRUE if @object is valid, FALSE else.
    	 *
    	 * Since: 2.30
    	 */
    	gboolean ( *is_valid )  ( const FMAIDuplicable *object );
    } FMAIDuplicableInterface;

This interface is implemented by FMAObject objects, in order to be able to keep the trace of all duplicated objects.

#### Members

`copy` () | copies one object to another. |
`are_equal` () | tests if two objects are equals. |
`is_valid` () | tests if one object is valid. |

### IDUPLICABLE_SIGNAL_MODIFIED_CHANGED

    #define IDUPLICABLE_SIGNAL_MODIFIED_CHANGED		"iduplicable-modified-changed"

### IDUPLICABLE_SIGNAL_VALID_CHANGED

    #define IDUPLICABLE_SIGNAL_VALID_CHANGED		"iduplicable-valid-changed"

### enum FMADuplicableMode

The duplication mode which is to be applied to the supplied object.

#### Members

FMA_DUPLICATE_ONLY | only duplicates the provided object. |
FMA_DUPLICATE_OBJECT | only duplicate a menu (a menu with some subitems is duplicated to an empty menu) |
FMA_DUPLICATE_REC | recursively duplicates all the provided hierarchy. |