## NAObjectItem NAObjectItem — The Object Item Base Class Definition |

## Synopsis

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

    #define             NA_TYPE_OBJECT_ITEM
    #define             NA_OBJECT_ITEM                      (object)
    #define             NA_IS_OBJECT_ITEM                   (object)
                        NAObjectItem;
    enum                NAItemTarget;
    gboolean            na_object_item_is_finally_writable  (const NAObjectItem *item,
                                                             guint *reason);
    void                na_object_item_set_writability_status
                                                            (NAObjectItem *item,
                                                             gboolean writable,
                                                             guint reason);
    NAObjectId *        na_object_item_get_item             (const NAObjectItem *item,
                                                             const gchar *id);
    gint                na_object_item_get_position         (const NAObjectItem *item,
                                                             const NAObjectId *child);
    void                na_object_item_append_item          (NAObjectItem *item,
                                                             const NAObjectId *child);
    void                na_object_item_insert_at            (NAObjectItem *item,
                                                             const NAObjectId *child,
                                                             gint pos);
    void                na_object_item_insert_item          (NAObjectItem *item,
                                                             const NAObjectId *child,
                                                             const NAObjectId *before);
    void                na_object_item_remove_item          (NAObjectItem *item,
                                                             const NAObjectId *child);
    guint               na_object_item_get_items_count      (const NAObjectItem *item);
    void                na_object_item_count_items          (GList *items,
                                                             gint *menus,
                                                             gint *actions,
                                                             gint *profiles,
                                                             gboolean recurse);
    GList *             na_object_item_copyref_items        (GList *items);
    GList *             na_object_item_free_items           (GList *items);
    void                na_object_item_rebuild_children_slist
                                                            (NAObjectItem *item);
    void                na_object_item_deals_with_version   (NAObjectItem *item);

## Object Hierarchy

      GObject
       +----NAObject
             +----NAObjectId
                   +----NAObjectItem
                         +----NAObjectAction
                         +----NAObjectMenu

## Implemented Interfaces

NAObjectItem implements NAIDuplicable.

## Description

This is a pure virtual class, i.e. not an instantiatable one, but serves as the base class for NAObjectAction and NAObjectMenu.

## Details

### NA_TYPE_OBJECT_ITEM

    #define NA_TYPE_OBJECT_ITEM                ( na_object_item_get_type())

### NA_OBJECT_ITEM()

    #define NA_OBJECT_ITEM( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_TYPE_OBJECT_ITEM, NAObjectItem ))

### NA_IS_OBJECT_ITEM()

    #define NA_IS_OBJECT_ITEM( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_TYPE_OBJECT_ITEM ))

### NAObjectItem

    typedef struct _NAObjectItem NAObjectItem;

### enum NAItemTarget

    typedef enum {
    	ITEM_TARGET_SELECTION = 1,
    	ITEM_TARGET_LOCATION,
    	ITEM_TARGET_TOOLBAR,
    	ITEM_TARGET_ANY
    } NAItemTarget;

The NAItemTarget mode is Caja-driven. It determines in which part of the Caja UI our actions will be displayed.

`ITEM_TARGET_SELECTION` | when targeting the selection context menu.
`ITEM_TARGET_LOCATION` | when targeting the background context menu.
`ITEM_TARGET_TOOLBAR` | when targeting the toolbar.
`ITEM_TARGET_ANY` | a wilcard target defined in order to be able to activate an action from a keyboard shortcut, while keeping this same action hidden from the UI.

### na_object_item_is_finally_writable ()

    gboolean            na_object_item_is_finally_writable  (const NAObjectItem *item,
                                                             guint *reason);

`item` : | this NAObjectItem -derived object.
`reason` : | if not `NULL`, a pointer to a guint which will hold the reason code.
Returns : | the writability status of the `item`.

Since 3.1

### na_object_item_set_writability_status ()

    void                na_object_item_set_writability_status
                                                            (NAObjectItem *item,
                                                             gboolean writable,
                                                             guint reason);

Set the writability status of the `item`.

`item` : | this NAObjectItem -derived object.
`writable` : | whether the item is finally writable.
`reason` : | the reason code.

Since 3.1

### na_object_item_get_item ()

    NAObjectId *        na_object_item_get_item             (const NAObjectItem *item,
                                                             const gchar *id);

`item` : | the NAObjectItem from which we want retrieve a subitem.
`id` : | the id of the searched subitem.
Returns : | a pointer to the NAObjectId -derived child with the required id. The returned NAObjectId is owned by the `item` object ; the caller should not try to `g_free()` nor `g_object_unref()` it.

Since 2.30

### na_object_item_get_position ()

    gint                na_object_item_get_position         (const NAObjectItem *item,
                                                             const NAObjectId *child);

`item` : | this NAObjectItem object.
`child` : | a NAObjectId -derived child.
Returns : | the position of `child` in the subitems list of `item`, starting from zero, or -1 if not found.

Since 2.30

### na_object_item_append_item ()

    void                na_object_item_append_item          (NAObjectItem *item,
                                                             const NAObjectId *child);

Appends a new `child` to the list of subitems of `item`, and setup the parent pointer of the child to its new parent.

Doesn't modify the reference count on `object`.

`item` : | the NAObjectItem to which add the subitem.
`child` : | a NAObjectId to be added to list of subitems.

Since 2.30

### na_object_item_insert_at ()

    void                na_object_item_insert_at            (NAObjectItem *item,
                                                             const NAObjectId *child,
                                                             gint pos);

Inserts a new `child` in the list of subitems of `item`.

Doesn't modify the reference count on `child`.

`item` : | the NAObjectItem in which add the subitem.
`child` : | a NAObjectId -derived to be inserted in the list of subitems.
`pos` : | the position at which the `child` should be inserted.

Since 2.30

### na_object_item_insert_item ()

    void                na_object_item_insert_item          (NAObjectItem *item,
                                                             const NAObjectId *child,
                                                             const NAObjectId *before);

Inserts a new `child` in the list of subitems of `item`.

Doesn't modify the reference count on `child`.

`item` : | the NAObjectItem to which add the subitem.
`child` : | a NAObjectId to be inserted in the list of subitems.
`before` : | the NAObjectId before which the `child` should be inserted.

Since 2.30

### na_object_item_remove_item ()

    void                na_object_item_remove_item          (NAObjectItem *item,
                                                             const NAObjectId *child);

Removes a `child` from the list of subitems of `item`.

Doesn't modify the reference count on `child`.

`item` : | the NAObjectItem from which the subitem must be removed.
`child` : | a NAObjectId -derived to be removed from the list of subitems.

Since 2.30

### na_object_item_get_items_count ()

    guint               na_object_item_get_items_count      (const NAObjectItem *item);

`item` : | the NAObjectItem from which we want a count of subitems.
Returns : | the count of subitems of `item`.

Since 2.30

### na_object_item_count_items ()

    void                na_object_item_count_items          (GList *items,
                                                             gint *menus,
                                                             gint *actions,
                                                             gint *profiles,
                                                             gboolean recurse);

`items` : | a list if NAObject -derived to be counted.
`menus` : | will be set to the count of menus.
`actions` : | will be set to the count of actions.
`profiles` : | will be set to the count of profiles.
`recurse` : | whether to recursively count all items, or only those in level zero of the list.
Returns : | the count the numbers of items if the provided list. As this function is recursive, the counters should be initialized by the caller before calling it.

Since 2.30

### na_object_item_copyref_items ()

    GList *             na_object_item_copyref_items        (GList *items);

Creates a copy of the provided list, recursively incrementing the reference count of NAObjects.

`items` : | a list of NAObject -derived items.
Returns : | the new list, which should be `na_object_free_items()` by the caller.

Since 3.1

### na_object_item_free_items ()

    GList *             na_object_item_free_items           (GList *items);

Free the items list.

`items` : | a list of NAObject -derived items.
Returns : | a `NULL` pointer.

Since 3.1

### na_object_item_rebuild_children_slist ()

    void                na_object_item_rebuild_children_slist
                                                            (NAObjectItem *item);

Rebuild the string list of children.

`item` : | this NAObjectItem -derived object.

Since 2.30

### na_object_item_deals_with_version ()

    void                na_object_item_deals_with_version   (NAObjectItem *item);

Just after the `item` has been read from NAIFactoryProvider, setup the version. This is needed because some conversions may occur in this object.

Note that there is only some 2.x versions where the version string was not systematically written. If `item` has been read from a .desktop file, then iversion is already set to (at least) 3.

`item` : | this NAObjectItem -derived object.

Since 2.30