IpatchContainer

IpatchContainer — An abstract patch container class.

Synopsis




void                (*IpatchContainerAddHook)           (IpatchContainer *container,
                                                         IpatchItem *item);
void                (*IpatchContainerRemoveHook)        (IpatchContainer *container,
                                                         IpatchItem *item);
                    IpatchContainer;
                    IpatchContainerClass;
IpatchList*         ipatch_container_get_children       (IpatchContainer *container,
                                                         GType type);
const GType*        ipatch_container_get_child_types    (IpatchContainer *container);
const GType*        ipatch_container_type_get_child_types
                                                        (GType container_type);
#define             ipatch_container_append             (container, item)
#define             ipatch_container_prepend            (container, item)
#define             ipatch_container_add
void                ipatch_container_insert             (IpatchContainer *container,
                                                         IpatchItem *item,
                                                         int pos);
void                ipatch_container_remove             (IpatchContainer *container,
                                                         IpatchItem *item);
guint               ipatch_container_count              (IpatchContainer *container,
                                                         GType type);
void                ipatch_container_make_unique        (IpatchContainer *container,
                                                         IpatchItem *item);
void                ipatch_container_add_unique         (IpatchContainer *container,
                                                         IpatchItem *item);
gboolean            ipatch_container_init_iter          (IpatchContainer *container,
                                                         IpatchIter *iter,
                                                         GType type);
void                ipatch_container_insert_iter        (IpatchContainer *container,
                                                         IpatchItem *item,
                                                         IpatchIter *iter);
void                ipatch_container_remove_iter        (IpatchContainer *container,
                                                         IpatchIter *iter);
void                ipatch_container_set_add_hook       (IpatchContainerAddHook hook_func);
void                ipatch_container_set_remove_hook    (IpatchContainerRemoveHook hook_func);
#define             IPATCH_CONTAINER_ERRMSG_INVALID_CHILD_2

Object Hierarchy


  GObject
   +----IpatchItem
         +----IpatchContainer
               +----IpatchBase
               +----IpatchDLS2Inst
               +----IpatchSampleData
               +----IpatchGigRegion
               +----IpatchSF2Preset
               +----IpatchSF2Inst

Description

An abstract class to derive patch items that contain other items.

Details

IpatchContainerAddHook ()

void                (*IpatchContainerAddHook)           (IpatchContainer *container,
                                                         IpatchItem *item);

A function prototype to hook container item adds. When assigned to IpatchContainerClass add_hook method - this function will be called after an item is added to any container.

MT-NOTE: This function is called within container item write lock, so time spent should be minimized, and care must be taken when locking other items (to prevent dead locks).

container : Container item
item : Item that was added to container

IpatchContainerRemoveHook ()

void                (*IpatchContainerRemoveHook)        (IpatchContainer *container,
                                                         IpatchItem *item);

A function prototype to hook container item removes. When assigned to IpatchContainerClass remove_hook method - this function will be called before every container remove.

container : Container item
item : Item being removed

IpatchContainer

typedef struct _IpatchContainer IpatchContainer;


IpatchContainerClass

typedef struct {
  IpatchItemClass parent_class;


  /* methods */
  const GType * (*child_types)(void);
  const GType * (*virtual_types)(void);
  gboolean (*init_iter)(IpatchContainer *container, IpatchIter *iter,
			GType type);
  void (*make_unique)(IpatchContainer *container, IpatchItem *item);
  gboolean (*get_dups)(IpatchContainer *container, IpatchItem *item,
		       IpatchList **list);

  /* virtual function hooks */
  IpatchContainerAddHook add_hook;
  IpatchContainerRemoveHook remove_hook;
} IpatchContainerClass;


ipatch_container_get_children ()

IpatchList*         ipatch_container_get_children       (IpatchContainer *container,
                                                         GType type);

Get a list of child items from a container object. A new IpatchList is created containing all matching child items. The returned list object can be iterated over safely even in a multi-thread environment. If performance is an issue, ipatch_container_init_iter() can be used instead, although it requires locking of the container object.

container : Container object
type : GType of child items to get
Returns : New object list containing all matching items (an empty list if no items matched). The caller owns a reference to the object list and removing the reference will destroy it.

ipatch_container_get_child_types ()

const GType*        ipatch_container_get_child_types    (IpatchContainer *container);

Get an array of child types for a container object. The number of types is the number of individual lists the container has.

container : Container object
Returns : Pointer to a zero terminated array of types. Array is static and should not be modified or freed.

ipatch_container_type_get_child_types ()

const GType*        ipatch_container_type_get_child_types
                                                        (GType container_type);

Get an array of child types for a container type. The number of types is the number of individual lists the container has. Like ipatch_container_get_child_types() but takes a container GType instead of a container object.

container_type : A IpatchContainer derived type to get child types of
Returns : Pointer to a zero terminated array of types. Array is static and should not be modified or freed.

ipatch_container_append()

#define             ipatch_container_append(container, item)

A convenience macro for appending a child item in a container.

container : IPatchContainer derived item to append child to
item : Child IPatchItem to append

ipatch_container_prepend()

#define             ipatch_container_prepend(container, item)

A convenience macro for prepending a child item in a container.

container : IPatchContainer derived item to prepend child to
item : Child IPatchItem to prepend

ipatch_container_add

#define ipatch_container_add  ipatch_container_append

Just another name for ipatch_container_append(), for ultra convenience.


ipatch_container_insert ()

void                ipatch_container_insert             (IpatchContainer *container,
                                                         IpatchItem *item,
                                                         int pos);

Inserts an item into a patch item container.

MT-NOTE: If position in list is critical the container item should be locked and ipatch_container_insert_iter() used instead. Only inserting in the first or last position (pos is 0 or less than 0) is guaranteed.

container : Container item to insert into
item : Item to insert
pos : Index position to insert item into (item type is used to determine what list to insert into). 0 = first, less than 0 = last.

ipatch_container_remove ()

void                ipatch_container_remove             (IpatchContainer *container,
                                                         IpatchItem *item);

Removes an item from container.

container : Container item to remove from
item : Item to remove from container

ipatch_container_count ()

guint               ipatch_container_count              (IpatchContainer *container,
                                                         GType type);

Counts children of a specific type (or derived thereof) in a container object.

container : Container object to count children of
type : Type of children to count
Returns : Count of children of type in container.

ipatch_container_make_unique ()

void                ipatch_container_make_unique        (IpatchContainer *container,
                                                         IpatchItem *item);

Ensures an item's duplicate sensitive properties are unique among items of the same type in container. The item need not be a child of container, but can be. The initial values of the duplicate sensitive properties are used if already unique, otherwise they are modified (name strings have numbers appended to them, unused MIDI locale is found, etc).

container : Patch item container
item : An item of a type that can be added to container (but not necessarily parented to container).

ipatch_container_add_unique ()

void                ipatch_container_add_unique         (IpatchContainer *container,
                                                         IpatchItem *item);

Adds a patch item to a container and ensures that the item's duplicate sensitive properties are unique (see ipatch_container_make_unique()).

container : Container to add item to
item : Item to add

ipatch_container_init_iter ()

gboolean            ipatch_container_init_iter          (IpatchContainer *container,
                                                         IpatchIter *iter,
                                                         GType type);

Initialize an iterator structure to a child list of the specified type in a container object.

MT-NOTE: The container must be locked, or single thread access ensured, for the duration of this call and iteration of iter as the container object's lists are used directly. The iterator related functions are meant to be used for latency critical operations, and they should try and minimize the locking duration.

container : Container object
iter : Iterator structure to initialize
type : Container child type list to initialize iter to
Returns : TRUE on success, FALSE otherwise in which case the contents of iter are undefined.

ipatch_container_insert_iter ()

void                ipatch_container_insert_iter        (IpatchContainer *container,
                                                         IpatchItem *item,
                                                         IpatchIter *iter);

Insert a patch item into a container after the position marked by iter. No checking is done to see if child item is actually a valid type in container, this is left up to the caller for added performance.

MT-NOTE: The container object should be write locked, or single thread access ensured, for the duration of this call and prior iterator functions.

container : Container object
item : Patch item to insert
iter : Iterator marking position to insert after (NULL position to prepend). Iterator is advanced after insert to point to new inserted item. Note that this makes appending multiple items rather fast.

ipatch_container_remove_iter ()

void                ipatch_container_remove_iter        (IpatchContainer *container,
                                                         IpatchIter *iter);

Removes an item from a container object. The item is specified by the current position in iter.

MT-NOTE: The container object should be write locked, or single thread access ensured, for the duration of this call and prior iterator functions.

container : Container object
iter : Iterator marking item to remove

ipatch_container_set_add_hook ()

void                ipatch_container_set_add_hook       (IpatchContainerAddHook hook_func);

Set the IpatchContainer item add hook function. This function will be executed when an item is added to IpatchContainer objects with the IPATCH_ITEM_HOOKS_ACTIVE flag set.

MT-NOTE: Setting to NULL is not multi-thread safe.

hook_func : Hook callback function

ipatch_container_set_remove_hook ()

void                ipatch_container_set_remove_hook    (IpatchContainerRemoveHook hook_func);

Set the IpatchContainer item remove hook function. This function will be executed when an item is removed from IpatchContainer objects with the IPATCH_ITEM_HOOKS_ACTIVE flag set.

MT-NOTE: Setting to NULL is not multi-thread safe.

hook_func : Hook callback function

IPATCH_CONTAINER_ERRMSG_INVALID_CHILD_2

#define             IPATCH_CONTAINER_ERRMSG_INVALID_CHILD_2

See Also

IPatchBase