![]() |
![]() |
![]() |
libInstPatch Reference Manual | ![]() |
---|---|---|---|---|
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
GObject +----IpatchItem +----IpatchContainer +----IpatchBase +----IpatchDLS2Inst +----IpatchSampleData +----IpatchGigRegion +----IpatchSF2Preset +----IpatchSF2Inst
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
|
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 |
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;
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. |
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. |
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. |
#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 |
#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 |
#define ipatch_container_add ipatch_container_append
Just another name for ipatch_container_append()
, for ultra convenience.
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.
|
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
|
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 .
|
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 ).
|
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 |
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.
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.
|
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 |
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 |
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 |