## IpatchItem

IpatchItem — Abstract base item object

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    IpatchItem *        (*IpatchItemCopyLinkFunc)           (IpatchItem *item,
                                                             IpatchItem *link,
                                                             gpointer user_data);
                        IpatchItem;
    enum                IpatchItemFlags;
    #define             IPATCH_ITEM_UNUSED_FLAG_SHIFT
    #define             IPATCH_ITEM_WLOCK                   (item)
    #define             IPATCH_ITEM_WUNLOCK                 (item)
    #define             IPATCH_ITEM_RLOCK                   (item)
    #define             IPATCH_ITEM_RUNLOCK                 (item)
    #define             IPATCH_ITEM_PROP_NOTIFY_SET_EVENT   (info, index, data, destroy)
    void                (*IpatchItemPropCallback)           (IpatchItemPropNotify *notify);
    void                (*IpatchItemPropDisconnect)         (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             gpointer user_data);
    #define             IPATCH_ITEM_COPY_LINK_FUNC          (item, link, func, userdata)
    extern              GParamSpec *ipatch_item_pspec_title;
    void                ipatch_item_set_parent              (IpatchItem *item,
                                                             IpatchItem *parent);
    void                ipatch_item_unparent                (IpatchItem *item);
    IpatchItem *        ipatch_item_get_parent              (IpatchItem *item);
    IpatchItem *        ipatch_item_peek_parent             (IpatchItem *item);
    IpatchItem *        ipatch_item_get_base                (IpatchItem *item);
    IpatchItem *        ipatch_item_peek_base               (IpatchItem *item);
    IpatchItem *        ipatch_item_get_ancestor_by_type    (IpatchItem *item,
                                                             GType ancestor_type);
    IpatchItem *        ipatch_item_peek_ancestor_by_type   (IpatchItem *item,
                                                             GType ancestor_type);
    void                ipatch_item_remove                  (IpatchItem *item);
    void                ipatch_item_changed                 (IpatchItem *item);
    void                ipatch_item_get_property_fast       (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             GValue *value);
    void                ipatch_item_copy                    (IpatchItem *dest,
                                                             IpatchItem *src);
    void                ipatch_item_copy_link_func          (IpatchItem *dest,
                                                             IpatchItem *src,
                                                             IpatchItemCopyLinkFunc link_func,
                                                             gpointer user_data);
    void                ipatch_item_copy_replace            (IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GHashTable *repl_hash);
    IpatchItem *        ipatch_item_duplicate               (IpatchItem *item);
    IpatchItem *        ipatch_item_duplicate_link_func     (IpatchItem *item,
                                                             IpatchItemCopyLinkFunc link_func,
                                                             gpointer user_data);
    IpatchItem *        ipatch_item_duplicate_replace       (IpatchItem *item,
                                                             GHashTable *repl_hash);
    IpatchList *        ipatch_item_duplicate_deep          (IpatchItem *item);
    IpatchItem *        ipatch_item_copy_link_func_deep     (IpatchItem *item,
                                                             IpatchItem *link,
                                                             gpointer user_data);
    IpatchItem *        ipatch_item_copy_link_func_hash     (IpatchItem *item,
                                                             IpatchItem *link,
                                                             gpointer user_data);
    gboolean            ipatch_item_type_can_conflict       (GType item_type);
    GParamSpec **       ipatch_item_type_get_unique_specs   (GType item_type,
                                                             guint32 *groups);
    GValueArray *       ipatch_item_get_unique_props        (IpatchItem *item);
    guint               ipatch_item_test_conflict           (IpatchItem *item1,
                                                             IpatchItem *item2);
    void                ipatch_item_set_atomic              (gpointer item,
                                                             const char *first_property_name,
                                                             ...);
    void                ipatch_item_get_atomic              (gpointer item,
                                                             const char *first_property_name,
                                                             ...);
    IpatchItem *        ipatch_item_first                   (IpatchIter *iter);
    IpatchItem *        ipatch_item_next                    (IpatchIter *iter);
    void                ipatch_item_prop_notify             (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             const GValue *new_value,
                                                             const GValue *old_value);
    void                ipatch_item_prop_notify_by_name     (IpatchItem *item,
                                                             const char *prop_name,
                                                             const GValue *new_value,
                                                             const GValue *old_value);
    guint               ipatch_item_prop_connect            (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             IpatchItemPropCallback callback,
                                                             IpatchItemPropDisconnect disconnect,
                                                             gpointer user_data);
    guint               ipatch_item_prop_connect_by_name    (IpatchItem *item,
                                                             const char *prop_name,
                                                             IpatchItemPropCallback callback,
                                                             IpatchItemPropDisconnect disconnect,
                                                             gpointer user_data);
    void                ipatch_item_prop_disconnect         (guint handler_id);
    void                ipatch_item_prop_disconnect_matched (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             IpatchItemPropCallback callback,
                                                             gpointer user_data);
    void                ipatch_item_prop_disconnect_by_name (IpatchItem *item,
                                                             const char *prop_name,
                                                             IpatchItemPropCallback callback,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchContainer
             +----IpatchFile
             +----IpatchDLS2Sample
             +----IpatchVirtualContainer
             +----IpatchDLS2Region
             +----IpatchSampleData
             +----IpatchGigDimension
             +----IpatchGigSubRegion
             +----IpatchSampleStore
             +----IpatchSF2Sample
             +----IpatchSF2Zone
             +----IpatchVBankRegion

## Known Derived Interfaces

IpatchItem is required by IpatchSF2ModItemIface, IpatchSample and IpatchSF2GenItemIface.

## Properties

      "base"                     IpatchBase*           : Read
      "flags"                    guint                 : Read / Write
      "parent"                   IpatchItem*           : Read / Write
      "title"                    gchar*                : Read

## Description

The abstract base item type from which all instrument objects are derived and many other object types as well.

## Details

### IpatchItemCopyLinkFunc ()

    IpatchItem *        (*IpatchItemCopyLinkFunc)           (IpatchItem *item,
                                                             IpatchItem *link,
                                                             gpointer user_data);

A callback function called during item copy/duplicate operations for any item link reference which needs to be resolved. An example usage is for deep duplicating an object (all references can also be duplicated). Item copy methods should call this for any linked item references which are not part of the new object.

`item` : | Item which is being linked (contains a reference to `link`).
`link` : | The item being referenced (can be NULL).
`user_data` : | User data supplied to copy/duplicate function.
Returns : | Pointer to item to use for link property (can be the `link` item if the duplicated/copied item is local to the same file).

### IpatchItem

    typedef struct _IpatchItem IpatchItem;

### enum IpatchItemFlags

    typedef enum
    {
      IPATCH_ITEM_HOOKS_ACTIVE = 1 << 0,  /* hook callbacks active? */
      IPATCH_ITEM_FREE_MUTEX   = 1 << 1   /* TRUE if item should free its mutex */
    } IpatchItemFlags;

### IPATCH_ITEM_UNUSED_FLAG_SHIFT

    #define IPATCH_ITEM_UNUSED_FLAG_SHIFT 4

### IPATCH_ITEM_WLOCK()

    #define             IPATCH_ITEM_WLOCK(item)

### IPATCH_ITEM_WUNLOCK()

    #define             IPATCH_ITEM_WUNLOCK(item)

### IPATCH_ITEM_RLOCK()

    #define IPATCH_ITEM_RLOCK(item)		IPATCH_ITEM_WLOCK(item)

### IPATCH_ITEM_RUNLOCK()

    #define IPATCH_ITEM_RUNLOCK(item)	IPATCH_ITEM_WUNLOCK(item)

### IPATCH_ITEM_PROP_NOTIFY_SET_EVENT()

    #define             IPATCH_ITEM_PROP_NOTIFY_SET_EVENT(info, index, data, destroy)

A macro for assigning per event pointers to IpatchItemPropNotify.

`info` : | IpatchItemPropNotify pointer
`index` : | Pointer index (0-3)
`data` : | Data to assign to pointer field
`destroy` : | Callback function to cleanup `data` when done (or `NULL`)

### IpatchItemPropCallback ()

    void                (*IpatchItemPropCallback)           (IpatchItemPropNotify *notify);

IpatchItem property change callback function prototype.

### IpatchItemPropDisconnect ()

    void                (*IpatchItemPropDisconnect)         (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             gpointer user_data);

Function prototype which gets called when a property notify callback gets disconnected.

`item` : | Item of prop change match criteria
`pspec` : | Parameter spec of prop change match criteria
`user_data` : | User defined pointer from when callback was added

### IPATCH_ITEM_COPY_LINK_FUNC()

    #define             IPATCH_ITEM_COPY_LINK_FUNC(item, link, func, userdata)

### ipatch_item_pspec_title

    extern GParamSpec *ipatch_item_pspec_title;

### ipatch_item_set_parent ()

    void                ipatch_item_set_parent              (IpatchItem *item,
                                                             IpatchItem *parent);

Usually only used by IpatchItem type implementations. Sets the parent of a patch item. Also recursively sets base parent and IPATCH_ITEM_HOOKS_ACTIVE flag if set in `parent`. Also assigns the item's thread mutex to that of the parent if its class has mutex_slave set. The `parent` container is responsible for adding a reference to `item` - this function does not do so.

NOTE: If the `item` has mutex_slave set in its class then the item will use `parent` object's mutex. During the call to this function `item` should not be accessed by any other threads, otherwise problems may occur when the mutex is changed. Normally this shouldn't be much of an issue, since new item's are often only accessed by 1 thread until being parented.

`item` : | Item to set parent of (should not have a parent).
`parent` : | New parent of item.

### ipatch_item_unparent ()

    void                ipatch_item_unparent                (IpatchItem *item);

Usually only used by IpatchItem type implementations. Unparent an item. Also recursively unsets base parent and IPATCH_ITEM_HOOKS_ACTIVE flag. Parent container object is responsible for removing reference of `item` - this function does not do so.

`item` : | Item to unparent

### ipatch_item_get_parent ()

    IpatchItem *        ipatch_item_get_parent              (IpatchItem *item);

Gets the parent of `item` after incrementing its reference count. The caller is responsible for decrementing the reference count with g_object_unref when finished with it. This function is useful because all code paths must contain references to the items that they are working with in a multi-thread environment (there is no guarantee an item won't be destroyed unless a refcount is held).

`item` : | Item to get parent of
Returns : | The parent of `item` or `NULL` if not parented or a root item. If not `NULL` then the reference count of parent has been incremented and the caller is responsible for removing it when finished with parent.

### ipatch_item_peek_parent ()

    IpatchItem *        ipatch_item_peek_parent             (IpatchItem *item);

This function is the same as `ipatch_item_get_parent()` (gets an item's parent) but does not increment the parent's ref count. Therefore this function should only be used when the caller already holds a reference or when only the value of the pointer will be used (not the contents), to avoid multi-thread problems.

`item` : | Item to get the parent of
Returns : | The parent of `item` or `NULL` if not parented or a root item.

### ipatch_item_get_base ()

    IpatchItem *        ipatch_item_get_base                (IpatchItem *item);

Gets the base parent of `item` (toplevel patch file object) after incrementing its reference count. The caller is responsible for decrementing the reference count with g_object_unref when finished with it. If `item` is itself a IpatchBase object then it is returned.

`item` : | Item to get base parent of
Returns : | The base parent of `item` or `NULL` if no IpatchBase type in parent ancestry. If not `NULL` then the reference count of parent has been incremented and the caller is responsible for removing it when finished with the base parent.

### ipatch_item_peek_base ()

    IpatchItem *        ipatch_item_peek_base               (IpatchItem *item);

This function is the same as `ipatch_item_get_base()` (gets an item's toplevel base parent) but does not increment the parent's ref count. Therefore this function should only be used when the caller already holds a reference or when only the value of the pointer will be used (not the contents), to avoid multi-thread problems.

`item` : | Item to get the base parent of
Returns : | The base parent of `item` or `NULL` if no IpatchBase type in parent ancestry.

### ipatch_item_get_ancestor_by_type ()

    IpatchItem *        ipatch_item_get_ancestor_by_type    (IpatchItem *item,
                                                             GType ancestor_type);

Searches for the first parent item that is derived from `ancestor_type` in the `item` object's ancestry. `ancestor_type` must be an IpatchItem derived type (as well as the ancestry of `item`). Of note is that `item` can also match. The returned item's reference count has been incremented and it is the responsiblity of the caller to remove it with `g_object_unref()` when finished with it.

`item` : | Item to search for parent of a given type
`ancestor_type` : | Type of parent in the `item` object's ancestry
Returns : | The matched item (can be the `item` itself) or `NULL` if no item matches `ancestor_type` in the ancestry. Remember to unref the matched item when done with it.

### ipatch_item_peek_ancestor_by_type ()

    IpatchItem *        ipatch_item_peek_ancestor_by_type   (IpatchItem *item,
                                                             GType ancestor_type);

Just like `ipatch_item_get_ancestor_by_type()` but doesn't ref returned item. This should only be used when caller already owns a reference or only the pointer value is of importance, since otherwise there is a potential multi-thread race condition.

`item` : | Item to search for parent of a given type
`ancestor_type` : | Type of parent in the `item` object's ancestry
Returns : | The matched item (can be the `item` itself) or `NULL` if no item matches `ancestor_type` in the ancestry. Remember that the returned item is not referenced.

### ipatch_item_remove ()

    void                ipatch_item_remove                  (IpatchItem *item);

This function removes an item from its parent container and removes other references from within the same patch (e.g., a IpatchSF2Sample will be removed from its parent IpatchSF2 and all IpatchSF2IZone objects referencing the sample will also be removed).

`item` : | Item to remove

### ipatch_item_changed ()

    void                ipatch_item_changed                 (IpatchItem *item);

This function should be called when an item's saveable state (what ends up in a patch file) has changed. Causes the `item` object's base parent to have its changed flag set, indicating that the file has changes that have not been saved. Note that this function is automatically called when an `ipatch_item_prop_notify()` occurs for a property without the IPATCH_PARAM_NO_SAVE_CHANGE flag in its GParamSpec and therefore this function should not be called additionally.

`item` : | Item that has changed

### ipatch_item_get_property_fast ()

    void                ipatch_item_get_property_fast       (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             GValue *value);

Usually only used by IpatchItem implementations. A faster way to retrieve an object property. Often used for fetching current value for property notifies. Notice that this function currently doesn't work with interface or class overridden properties.

`item` : | Item to get property value from
`pspec` : | Parameter spec of property to get
`value` : | Uninitialized caller supplied value to store the current value in. Remember to call g_value_unset when done with it.

### ipatch_item_copy ()

    void                ipatch_item_copy                    (IpatchItem *dest,
                                                             IpatchItem *src);

Copy an item using the item class' "copy" method. Object links are copied as is, meaning the resulting object is a local object to the same IpatchBase.

`dest` : | New destination item to copy to (should be same type or derived from `src` type)
`src` : | Item to copy from

### ipatch_item_copy_link_func ()

    void                ipatch_item_copy_link_func          (IpatchItem *dest,
                                                             IpatchItem *src,
                                                             IpatchItemCopyLinkFunc link_func,
                                                             gpointer user_data);

Copy an item using the item class' "copy" method. Like `ipatch_item_copy()` but takes a `link_func` which can be used for handling replication of externally linked objects (recursively deep duplicate for example, although there is `ipatch_item_duplicate_deep()` specifically for that).

`dest` : | New destination item to copy to (should be same type or derived from `src` type)
`src` : | Item to copy from
`link_func` : | Function to call for each object link pointer in `src`. This function can alter the copied link if desired.
`user_data` : | User defined data to pass to `link_func`.

### ipatch_item_copy_replace ()

    void                ipatch_item_copy_replace            (IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GHashTable *repl_hash);

Like `ipatch_item_copy()` but takes a link replacement hash, which can be used for substituting different objects for object links. See `ipatch_item_copy_link_func()` if even more flexibility is desired.

`dest` : | New destination item to copy to (should be same type or derived from `src` type)
`src` : | Item to copy from
`repl_hash` : | Hash of link pointer substitutions. The original link pointer is the hash key, and the hash value is the replacement pointer.

### ipatch_item_duplicate ()

    IpatchItem *        ipatch_item_duplicate               (IpatchItem *item);

A convenience function to duplicate an item. Like `ipatch_item_copy()` but creates a new duplicate item, rather than using an existing item. Note that externally linked objects are not duplicated for non IpatchBase derived types, making the item local to the same IpatchBase object.

`item` : | Item to duplicate
Returns : | New duplicate item. Caller owns the reference to the new item.

### ipatch_item_duplicate_link_func ()

    IpatchItem *        ipatch_item_duplicate_link_func     (IpatchItem *item,
                                                             IpatchItemCopyLinkFunc link_func,
                                                             gpointer user_data);

Like `ipatch_item_copy_link_func()` but duplicates the item instead of copying to an existing item.

`item` : | Item to duplicate
`link_func` : | Function to call for each object link pointer in `item`. This function can alter the copied link if desired.
`user_data` : | User defined data to pass to `link_func`.
Returns : | New duplicate item. Caller owns the reference to the new item.

### ipatch_item_duplicate_replace ()

    IpatchItem *        ipatch_item_duplicate_replace       (IpatchItem *item,
                                                             GHashTable *repl_hash);

Like `ipatch_item_copy_replace()` but duplicates the item instead of copying it to an already created item.

`item` : | Item to duplicate
`repl_hash` : | Hash of link pointer substitutions. The original link pointer is the hash key, and the hash value is the replacement pointer.
Returns : | New duplicate item. Caller owns the reference to the new item.

### ipatch_item_duplicate_deep ()

    IpatchList *        ipatch_item_duplicate_deep          (IpatchItem *item);

Recursively duplicate an item (i.e., its dependencies also).

`item` : | Item to deep duplicate
Returns : | List of duplicated `item` and dependencies (duplicated `item` is the first in the list). List object is owned by the caller and should be unreferenced when finished using it.

### ipatch_item_copy_link_func_deep ()

    IpatchItem *        ipatch_item_copy_link_func_deep     (IpatchItem *item,
                                                             IpatchItem *link,
                                                             gpointer user_data);

### ipatch_item_copy_link_func_hash ()

    IpatchItem *        ipatch_item_copy_link_func_hash     (IpatchItem *item,
                                                             IpatchItem *link,
                                                             gpointer user_data);

A predefined IpatchItemCopyLinkFunc which takes a hash for the `user_data` component, which is used for replacing link pointers. `link` is used as the hash key, the hash value is used in its place if present otherwise `link` is used unchanged.

`item` : | Item which is being linked (contains a reference to `link`).
`link` : | The item being referenced.
`user_data` : | User data supplied to copy/duplicate function.
Returns : | Value in hash (`user_data`) if `link` is present in hash, or `link` itself if not.

### ipatch_item_type_can_conflict ()

    gboolean            ipatch_item_type_can_conflict       (GType item_type);

Test if a given IpatchItem derived type can conflict with another item (only applies to items of the same type in the same IpatchBase object).

`item_type` : | Type to test
Returns : | `TRUE` if `item_type` can conflict (has properties which should be unique among its siblings), `FALSE` otherwise.

### ipatch_item_type_get_unique_specs ()

    GParamSpec **       ipatch_item_type_get_unique_specs   (GType item_type,
                                                             guint32 *groups);

Get the list of unique parameter specs which can conflict for a given item type.

`item_type` : | Type to get unique parameter specs for
`groups` : | Location to store an integer describing groups. Each bit corresponds to a GParamSpec in the returned array. GParamSpecs of the same group will have the same bit value (0 or 1) and be consecutive. Unique properties in the same group must all match (logic AND) for a conflict to occur. Pass `NULL` to ignore.
Returns : | `NULL` terminated list of parameter specs or `NULL` if `item_type` can never conflict. The returned array is internal and should not be modified or freed.

### ipatch_item_get_unique_props ()

    GValueArray *       ipatch_item_get_unique_props        (IpatchItem *item);

Get the values of the unique properties for `item`. This is useful when doing conflict detection processing and more flexibility is desired than with `ipatch_item_test_conflict()`.

`item` : | Item to get unique properties of
Returns : | GValueArray of the unique property values of `item` in the same order as the parameter specs returned by `ipatch_item_type_get_unique_specs()`. `NULL` is returned if `item` doesn't have any unique properties. Use `g_value_array_free()` to free the array when finished using it.

### ipatch_item_test_conflict ()

    guint               ipatch_item_test_conflict           (IpatchItem *item1,
                                                             IpatchItem *item2);

Test if two items would conflict if they were siblings (doesn't actually test if they are siblings).

`item1` : | First item to test
`item2` : | Second item to test
Returns : | Flags of unique properties which conflict. The bit index corresponds to the parameter index in the array returned by `ipatch_item_type_get_unique_specs()`. 0 is returned if the items do not conflict.

### ipatch_item_set_atomic ()

    void                ipatch_item_set_atomic              (gpointer item,
                                                             const char *first_property_name,
                                                             ...);

Sets properties on a patch item atomically (i.e. item is multi-thread locked while all properties are set). This avoids critical parameter sync problems when multiple threads are accessing the same item. See `g_object_set()` for more information on setting properties.

`item` : | IpatchItem derived object to set properties of
`first_property_name` : | Name of first property
`...` : | Variable list of arguments that should start with the value to set `first_property_name` to, followed by property name/value pairs. List is terminated with a `NULL` property name.

### ipatch_item_get_atomic ()

    void                ipatch_item_get_atomic              (gpointer item,
                                                             const char *first_property_name,
                                                             ...);

Gets properties from a patch item atomically (i.e. item is multi-thread locked while all properties are retrieved). This avoids critical parameter sync problems when multiple threads are accessing the same item. See `g_object_get()` for more information on getting properties.

`item` : | IpatchItem derived object to get properties from
`first_property_name` : | Name of first property
`...` : | Variable list of arguments that should start with a pointer to store the value from `first_property_name`, followed by property name/value pointer pairs. List is terminated with a `NULL` property name.

### ipatch_item_first ()

    IpatchItem *        ipatch_item_first                   (IpatchIter *iter);

Gets the first item in a patch item iterator. A convenience wrapper for `ipatch_iter_first()`.

`iter` : | Patch item iterator containing IpatchItem items
Returns : | The first item in `iter` or `NULL` if empty.

### ipatch_item_next ()

    IpatchItem *        ipatch_item_next                    (IpatchIter *iter);

Gets the next item in a patch item iterator. A convenience wrapper for `ipatch_iter_next()`.

`iter` : | Patch item iterator containing IpatchItem items
Returns : | The next item in `iter` or `NULL` if no more items.

### ipatch_item_prop_notify ()

    void                ipatch_item_prop_notify             (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             const GValue *new_value,
                                                             const GValue *old_value);

Usually only used by IpatchItem object implementations, rather than explicitly called by the user. It should be called AFTER item property changes that occur outside of the IpatchItem `item_set_property` method.

`item` : | Item whose property changed
`pspec` : | Parameter specification for `item` of parameter that changed
`new_value` : | The new value that was assigned
`old_value` : | Old value that property had (can be `NULL` for read only props)

### ipatch_item_prop_notify_by_name ()

    void                ipatch_item_prop_notify_by_name     (IpatchItem *item,
                                                             const char *prop_name,
                                                             const GValue *new_value,
                                                             const GValue *old_value);

Usually only used by IpatchItem object implementations, rather than explicitly called by the user. Like `ipatch_item_prop_notify()` except takes a property name instead of a parameter spec, for added convenience.

`item` : | Item whose property changed
`prop_name` : | Name of property that changed
`new_value` : | The new value that was assigned
`old_value` : | Old value that property had (can be `NULL` for read only properties)

### ipatch_item_prop_connect ()

    guint               ipatch_item_prop_connect            (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             IpatchItemPropCallback callback,
                                                             IpatchItemPropDisconnect disconnect,
                                                             gpointer user_data);

Connect a callback for a specific IpatchItem and property. If a property change occurs for the given `item` and `pspec` then the callback is invoked. The parameters `item` and/or `pspec` may be `NULL` for wild card matching (if both are `NULL` then callback will be called for all IpatchItem property changes).

`item` : | IpatchItem to match (or `NULL` for wildcard)
`pspec` : | Property parameter specification to match (or `NULL` for wildcard)
`callback` : | Callback function
`disconnect` : | Callback disconnect function (called when the callback is disconnected) can be NULL.
`user_data` : | User defined data to pass to `callback` and `disconnect` function.
Returns : | Unique handler ID which can be used to remove the handler or 0 on error (only when function params are incorrect).

### ipatch_item_prop_connect_by_name ()

    guint               ipatch_item_prop_connect_by_name    (IpatchItem *item,
                                                             const char *prop_name,
                                                             IpatchItemPropCallback callback,
                                                             IpatchItemPropDisconnect disconnect,
                                                             gpointer user_data);

Like `ipatch_item_prop_add_callback()` but takes the name of a property\ instead of the parameter spec, for added convenience.

`item` : | IpatchItem to match (or `NULL` for wildcard)
`prop_name` : | Name of property of `item` to match
`callback` : | Callback function
`disconnect` : | Callback disconnect function (called when the callback is disconnect) can be NULL.
`user_data` : | User defined data to pass to `callback` and `disconnect` function.
Returns : | Unique handler ID which can be used to remove the handler or 0 on error (only when function params are incorrect).

### ipatch_item_prop_disconnect ()

    void                ipatch_item_prop_disconnect         (guint handler_id);

Disconnects an IpatchItem property change callback handler by its ID.

`handler_id` : | Handler ID as returned from `ipatch_item_prop_connect()`.

### ipatch_item_prop_disconnect_matched ()

    void                ipatch_item_prop_disconnect_matched (IpatchItem *item,
                                                             GParamSpec *pspec,
                                                             IpatchItemPropCallback callback,
                                                             gpointer user_data);

Disconnects first IpatchItem property change callback matching all the function parameters. Note: Only the pointer values of `item` and `pspec` are used so they don't actually need to be valid anymore.

`item` : | IpatchItem of handler to match (does not need to be valid)
`pspec` : | GParamSpec of handler to match (does not need to be valid)
`callback` : | Callback function to match
`user_data` : | User data to match

### ipatch_item_prop_disconnect_by_name ()

    void                ipatch_item_prop_disconnect_by_name (IpatchItem *item,
                                                             const char *prop_name,
                                                             IpatchItemPropCallback callback,
                                                             gpointer user_data);

Like `ipatch_item_prop_disconnect_matched()` but takes a name of the property to match instead of a parameter spec, for added convenience. Note: `item` must still be valid (to look up the property), contrary to `ipatch_item_prop_disconnect_matched()`.

`item` : | IpatchItem of handler to match (NOTE: Must be a valid object!)
`prop_name` : | Name of property of `item` to match
`callback` : | Callback function to match
`user_data` : | User data to match

## Property Details

### The `"base"` property

      "base"                     IpatchBase*           : Read

Base.

### The `"flags"` property

      "flags"                    guint                 : Read / Write

Flags.

Default value: 0

### The `"parent"` property

      "parent"                   IpatchItem*           : Read / Write

Parent.

### The `"title"` property

      "title"                    gchar*                : Read

Title.

Default value: NULL