GwyInventory: Gwyddion Library Reference Manual

## GwyInventory GwyInventory — Ordered item inventory, indexed by both name and position. |

## Functions

GwyInventory * | gwy_inventory_new ()
GwyInventory * | gwy_inventory_new_filled ()
GwyInventory * | gwy_inventory_new_from_array ()
guint | gwy_inventory_get_n_items ()
gboolean | gwy_inventory_can_make_copies ()
gboolean | gwy_inventory_is_const ()
const GwyInventoryItemType * | gwy_inventory_get_item_type ()
gpointer | gwy_inventory_get_item ()
gpointer | gwy_inventory_get_item_or_default ()
gpointer | gwy_inventory_get_nth_item ()
guint | gwy_inventory_get_item_position ()
void | gwy_inventory_foreach ()
gpointer | gwy_inventory_find ()
void | gwy_inventory_set_default_item_name ()
const gchar * | gwy_inventory_get_default_item_name ()
gpointer | gwy_inventory_get_default_item ()
void | gwy_inventory_item_updated ()
void | gwy_inventory_nth_item_updated ()
void | gwy_inventory_restore_order ()
void | gwy_inventory_forget_order ()
gpointer | gwy_inventory_insert_item ()
gpointer | gwy_inventory_insert_nth_item ()
gboolean | gwy_inventory_delete_item ()
gboolean | gwy_inventory_delete_nth_item ()
gpointer | gwy_inventory_rename_item ()
gpointer | gwy_inventory_new_item ()

## Signals

void | default-changed | No Recursion
void | item-deleted | No Recursion
void | item-inserted | No Recursion
void | item-updated | No Recursion
void | items-reordered | No Recursion

## Types and Values

struct | GwyInventoryItemType
struct | GwyInventory
struct | GwyInventoryClass

## Object Hierarchy

        GObject
        ╰── GwyInventory

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyInventory is a uniform container that offers both hash table and array (sorted or unsorted) interfaces. Both types of read access are fast, operations that modify it may be slower. Inventory can also maintain a notion of default item.

GwyInventory can be used both as an actual container for some data, or just wrap a static array with a the same interface so the actual storage is opaque to inventory user. The former kind of inventories can be created with `gwy_inventory_new()` or `gwy_inventory_new_filled()`; constant inventory is created with `gwy_inventory_new_from_array()`. Contantess of an inventory can be tested with `gwy_inventory_is_const()`.

Possible operations with data items stored in an inventory are specified upon inventory creation with GwyInventoryItemType structure. Not all fields are mandatory, with items allowing more operations the inventory is more capable too. For example, if items offer a method to make copies, `gwy_inventory_new_item()` can be used to directly create new items in the inventory (this capability can be tested with `gwy_inventory_can_make_copies()`).

Item can have `traits', that is data that can be obtained generically. They are similar to GObject properties. Actually, if items are objects, they should simply map object properties to traits. But it is possible to define traits for simple structures too.

## Functions

### gwy_inventory_new ()

    GwyInventory *
    gwy_inventory_new (const GwyInventoryItemType *itype);

Creates a new inventory.

#### Parameters

itype | Type of items the inventory will contain. |

#### Returns

The newly created inventory.

### gwy_inventory_new_filled ()

    GwyInventory *
    gwy_inventory_new_filled (const GwyInventoryItemType *itype,
                              guint nitems,
                              gpointer *items);

Creates a new inventory and fills it with items.

#### Parameters

itype | Type of items the inventory will contain. |
nitems | The number of pointers in `items` . |
items | Item pointers to fill the newly created inventory with. |

#### Returns

The newly created inventory.

### gwy_inventory_new_from_array ()

    GwyInventory *
    gwy_inventory_new_from_array (const GwyInventoryItemType *itype,
                                  guint item_size,
                                  guint nitems,
                                  gconstpointer items);

Creates a new inventory from static item array.

The inventory is neither modifiable nor sortable, it simply serves as an adaptor for the array `items` .

#### Parameters

itype | Type of items the inventory will contain. Inventory keeps a copy of it, so it can be an automatic variable. |
item_size | Item size in bytes. |
nitems | The number of items in `items` . |
items | An array with items. It will be directly used as thus must exist through the whole lifetime of inventory. |

#### Returns

The newly created inventory.

### gwy_inventory_get_n_items ()

    guint
    gwy_inventory_get_n_items (GwyInventory *inventory);

Returns the number of items in an inventory.

#### Parameters

inventory | An inventory. |

#### Returns

The number of items.

### gwy_inventory_can_make_copies ()

    gboolean
    gwy_inventory_can_make_copies (GwyInventory *inventory);

Returns whether an inventory can create new items itself.

The prerequistie is that item type is a serializable object. It enables functions like `gwy_inventory_new_item()`.

#### Parameters

inventory | An inventory. |

#### Returns

`TRUE` if inventory can create new items itself.

### gwy_inventory_is_const ()

    gboolean
    gwy_inventory_is_const (GwyInventory *inventory);

Returns whether an inventory is an constant inventory.

Not only you cannot modify a constant inventory, but functions like `gwy_inventory_get_item()` may return pointers to constant memory.

#### Parameters

inventory | An inventory. |

#### Returns

`TRUE` if inventory is constant.

### gwy_inventory_get_item_type ()

    const GwyInventoryItemType *
    gwy_inventory_get_item_type (GwyInventory *inventory);

Returns the type of item an inventory holds.

#### Parameters

inventory | An inventory. |

#### Returns

The item type. It is owned by inventory and must not be modified or freed.

### gwy_inventory_get_item ()

    gpointer
    gwy_inventory_get_item (GwyInventory *inventory,
                            const gchar *name);

Looks up an item in an inventory.

#### Parameters

inventory | An inventory. |
name | Item name. |

#### Returns

Item called `name` , or `NULL` if there is no such item.

### gwy_inventory_get_item_or_default ()

    gpointer
    gwy_inventory_get_item_or_default (GwyInventory *inventory,
                                       const gchar *name);

Looks up an item in an inventory, eventually falling back to default.

The lookup order is: item of requested name, default item (if set), any inventory item, `NULL` (can happen only when inventory is empty).

#### Parameters

inventory | An inventory. |
name | Item name. |

#### Returns

Item called `name` , or default item.

### gwy_inventory_get_nth_item ()

    gpointer
    gwy_inventory_get_nth_item (GwyInventory *inventory,
                                guint n);

Returns item on given position in an inventory.

#### Parameters

inventory | An inventory. |
n | Item position. It must be between zero and the number of items in inventory, inclusive. If it is equal to the number of items, `NULL` is returned. In other words, inventory behaves like a `NULL`-terminated array, you can simply iterate over it until `gwy_inventory_get_nth_item()` returns `NULL`. |

#### Returns

Item at given position.

### gwy_inventory_get_item_position ()

    guint
    gwy_inventory_get_item_position (GwyInventory *inventory,
                                     const gchar *name);

Finds position of an item in an inventory.

#### Parameters

inventory | An inventory. |
name | Item name. |

#### Returns

Item position, or (guint)-1 if there is no such item.

### gwy_inventory_foreach ()

    void
    gwy_inventory_foreach (GwyInventory *inventory,
                           GHFunc function,
                           gpointer user_data);

Calls a function on each item of an inventory, in order.

`function` 's first argument is item position (transformed with `GUINT_TO_POINTER()`), second is item pointer, and the last is `user_data` .

#### Parameters

inventory | An inventory. |
function | A function to call on each item. It must not modify `inventory` . |
user_data | Data passed to `function` . |

### gwy_inventory_find ()

    gpointer
    gwy_inventory_find (GwyInventory *inventory,
                        GHRFunc predicate,
                        gpointer user_data);

Finds an inventory item using user-specified predicate function.

`predicate` is called for each item in `inventory` (in order) until it returns `TRUE`. Its arguments are the same as in `gwy_inventory_foreach()`.

#### Parameters

inventory | An inventory. |
predicate | A function testing some item property. It must not modify `inventory` . |
user_data | Data passed to `predicate` . |

#### Returns

The item for which `predicate` returned `TRUE`. If there is no such item in the inventory, `NULL` is returned.

### gwy_inventory_set_default_item_name ()

    void
    gwy_inventory_set_default_item_name (GwyInventory *inventory,
                                         const gchar *name);

Sets the default of an inventory.

Item `name` must already exist in the inventory.

#### Parameters

inventory | An inventory. |
name | Item name, pass `NULL` to unset default item. |

### gwy_inventory_get_default_item_name ()

    const gchar *
    gwy_inventory_get_default_item_name (GwyInventory *inventory);

Returns the name of the default item of an inventory.

#### Parameters

inventory | An inventory. |

#### Returns

The default item name, `NULL` if no default name is set. Item of this name may or may not exist in the inventory.

### gwy_inventory_get_default_item ()

    gpointer
    gwy_inventory_get_default_item (GwyInventory *inventory);

Returns the default item of an inventory.

#### Parameters

inventory | An inventory. |

#### Returns

The default item. If there is no default item, `NULL` is returned.

### gwy_inventory_item_updated ()

    void
    gwy_inventory_item_updated (GwyInventory *inventory,
                                const gchar *name);

Notifies inventory an item was updated.

This function makes sense primarily for non-object items, as object items can notify inventory via signals.

#### Parameters

inventory | An inventory. |
name | Item name. |

### gwy_inventory_nth_item_updated ()

    void
    gwy_inventory_nth_item_updated (GwyInventory *inventory,
                                    guint n);

Notifies inventory item on given position was updated.

This function makes sense primarily for non-object items, as object items can provide `watchable_signal` .

#### Parameters

inventory | An inventory. |
n | Item position. |

### gwy_inventory_restore_order ()

    void
    gwy_inventory_restore_order (GwyInventory *inventory);

Assures an inventory is sorted.

#### Parameters

inventory | An inventory. |

### gwy_inventory_forget_order ()

    void
    gwy_inventory_forget_order (GwyInventory *inventory);

Forces an inventory to be unsorted.

Item positions don't change, but future `gwy_inventory_insert_item()` won't try to insert items in order.

#### Parameters

inventory | An inventory. |

### gwy_inventory_insert_item ()

    gpointer
    gwy_inventory_insert_item (GwyInventory *inventory,
                               gpointer item);

Inserts an item into an inventory.

Item of the same name must not exist yet.

If the inventory is sorted, item is inserted to keep order. If the inventory is unsorted, item is simply added to the end.

#### Parameters

inventory | An inventory. |
item | An item to insert. |

#### Returns

`item` , for convenience.

### gwy_inventory_insert_nth_item ()

    gpointer
    gwy_inventory_insert_nth_item (GwyInventory *inventory,
                                   gpointer item,
                                   guint n);

Inserts an item to an explicit position in an inventory.

Item of the same name must not exist yet.

#### Parameters

inventory | An inventory. |
item | An item to insert. |
n | Position to insert `item` to. |

#### Returns

`item` , for convenience.

### gwy_inventory_delete_item ()

    gboolean
    gwy_inventory_delete_item (GwyInventory *inventory,
                               const gchar *name);

Deletes an item from an inventory.

#### Parameters

inventory | An inventory. |
name | Name of item to delete. |

#### Returns

`TRUE` if item was deleted.

### gwy_inventory_delete_nth_item ()

    gboolean
    gwy_inventory_delete_nth_item (GwyInventory *inventory,
                                   guint n);

Deletes an item on given position from an inventory.

#### Parameters

inventory | An inventory. |
n | Position of `item` to delete. |

#### Returns

`TRUE` if item was deleted.

### gwy_inventory_rename_item ()

    gpointer
    gwy_inventory_rename_item (GwyInventory *inventory,
                               const gchar *name,
                               const gchar *newname);

Renames an inventory item.

If an item of name `newname` is already present in `inventory` , the rename will fail.

#### Parameters

inventory | An inventory. |
name | Name of item to rename. |
newname | New name of item. |

#### Returns

The item, for convenience.

### gwy_inventory_new_item ()

    gpointer
    gwy_inventory_new_item (GwyInventory *inventory,
                            const gchar *name,
                            const gchar *newname);

Creates a new item as a copy of existing one and inserts it to inventory.

The newly created item can be called differently than `newname` if that already exists.

#### Parameters

inventory | An inventory. |
name | Name of item to duplicate, may be `NULL` to use default item (the same happens when `name` does not exist). |
newname | Name of new item, it must not exist yet. It may be `NULL`, the new name is based on `name` then. |

#### Returns

The newly added item.

## Types and Values

### struct GwyInventoryItemType

    struct GwyInventoryItemType {
        GType         type;
        const gchar  *watchable_signal;
        gboolean     (*is_fixed)       (gconstpointer item);
        const gchar* (*get_name)       (gpointer item);
        gint         (*compare)        (gconstpointer item1,
                                        gconstpointer item2);
        void         (*rename)         (gpointer item,
                                        const gchar *newname);
        void         (*dismantle)      (gpointer item);
        gpointer     (*copy)           (gpointer item);
        const GType* (*get_traits)     (gint *ntraits);
        const gchar* (*get_trait_name) (gint i);
        void         (*get_trait_value)(gpointer item,
                                        gint i,
                                        GValue *value);
    };

Infromation about a GwyInventory item type.

Note only one of the fields must be always defined: `get_name` . All the others give inventory (and thus inventory users) some additional powers over items. They may be set to `NULL` or 0 if particular item type does not (want to) support this operation.

The three trait methods are not used by GwyInventory itself, but allows GwyInventoryStore to generically map item properties to virtual columns of a GtkTreeModel. If items are objects, you will usually want to directly map some or all GObject properties to item traits. If they are plain C structs or something else, you can easily export their data members as virtual GtkTreeModel columns by defining traits for them.

#### Members

GType `type`; | Object type, if item is object or other type with registered GType. May be zero to indicate an unregistered item type. If items are objects, inventory takes a reference on them. |
const gchar *`watchable_signal`; | Item signal name to watch, used only for objects. When item emits this signal, inventory emits "item-updated" signal for it. May be `NULL` to indicate no signal should be watched, you can still emit "item-updated" with `gwy_inventory_item_updated()` or `gwy_inventory_nth_item_updated()`. |
`is_fixed` () | If not `NULL` and returns `TRUE` for some item, such an item cannot be removed from inventory, fixed items can be only added. This is checked each time an attempt is made to remove an item. |
`get_name` () | Returns item name (the string is owned by item and it is assumed to exist until item ceases to exist or is renamed). This function is obligatory. |
`compare` () | Item comparation function for sorting. If `NULL`, inventory never attempts to keep any item order and `gwy_inventory_restore_order()` does nothing. Otherwise inventory is sorted unless sorting is (temporarily) disabled with `gwy_inventory_forget_order()` or it was created with `gwy_inventory_new_filled()` and the initial array was not sorted according to `compare` . |
`rename` () | Function to rename an item. If not `NULL`, calls to `gwy_inventory_rename_item()` are possible. Note items must not be renamed by any other means than this method, because when an item is renamed and inventory does not know it, very bad things will happen and you will lose all your good karma. |
`dismantle` () | Called on item before it's removed from inventory. May be `NULL`. |
`copy` () | Method to create a copy of an item. If this function and `rename` are defined, calls to `gwy_inventory_new_item()` are possible. Inventory sets the copy's name immediately after creation, so it normally does not matter which name `copy` gives it. |
`get_traits` () | Function to get item traits. It returns array of item trait GTypes (keeping its ownership) and if `nitems` is not `NULL`, it stores the length of returned array there. |
`get_trait_name` () | Returns name of `i` -th trait (keeping ownership of the returned string). It is not obligatory, but advisable to give traits names. |
`get_trait_value` () | Sets `value` to value of `i` -th trait of item. |

### struct GwyInventory

    struct GwyInventory;

The GwyInventory struct contains private data only and should be accessed using the functions below.

### struct GwyInventoryClass

    struct GwyInventoryClass {
        GObjectClass parent_class;

        /* Signals */
        void (*item_inserted)(GwyInventory *inventory,
                              guint position);
        void (*item_deleted)(GwyInventory *inventory,
                             guint position);
        void (*item_updated)(GwyInventory *inventory,
                             guint position);
        void (*items_reordered)(GwyInventory *inventory,
                                const gint *new_order);
        void (*default_changed)(GwyInventory *inventory);
    };

## Signal Details

### The `“default-changed”` signal

    void
    user_function (GwyInventory *gwyinventory,
                   gpointer      user_data)

The ::default-changed signal is emitted when either default inventory item name changes or the presence of such an item in the inventory changes.

#### Parameters

gwyinventory | The GwyInventory which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: No Recursion

### The `“item-deleted”` signal

    void
    user_function (GwyInventory *gwyinventory,
                   guint         arg1,
                   gpointer      user_data)

The ::item-deleted signal is emitted when an item is deleted from an inventory.

#### Parameters

gwyinventory | The GwyInventory which received the signal. |
arg1 | Position an item was deleted from. |
user_data | user data set when the signal handler was connected. |

Flags: No Recursion

### The `“item-inserted”` signal

    void
    user_function (GwyInventory *gwyinventory,
                   guint         arg1,
                   gpointer      user_data)

The ::item-inserted signal is emitted when an item is inserted into an inventory.

#### Parameters

gwyinventory | The GwyInventory which received the signal. |
arg1 | Position an item was inserted at. |
user_data | user data set when the signal handler was connected. |

Flags: No Recursion

### The `“item-updated”` signal

    void
    user_function (GwyInventory *gwyinventory,
                   guint         arg1,
                   gpointer      user_data)

The ::item-updated signal is emitted when an item in an inventory is updated.

#### Parameters

gwyinventory | The GwyInventory which received the signal. |
arg1 | Position of updated item. |
user_data | user data set when the signal handler was connected. |

Flags: No Recursion

### The `“items-reordered”` signal

    void
    user_function (GwyInventory *gwyinventory,
                   gpointer      arg1,
                   gpointer      user_data)

The ::items-reordered signal is emitted when item in an inventory are reordered.

#### Parameters

gwyinventory | The GwyInventory which received the signal. |
arg1 | New item order map as in GtkTreeModel, `arg1` [new_position] = old_position. |
user_data | user data set when the signal handler was connected. |

Flags: No Recursion

## See Also

GwyContainer