Top | ![]() |
![]() |
![]() |
![]() |
GObject ╰── IpatchItem ╰── IpatchContainer ├── IpatchBase ├── IpatchDLS2Inst ├── IpatchGigRegion ├── IpatchSF2Preset ├── IpatchSF2Inst ├── IpatchSLIInst ╰── IpatchVBankInst
Objects which are derived from this abstract type can contain other items, thus forming a tree of items in an instrument file for example.
void (*IpatchContainerCallback) (IpatchContainer *container
,IpatchItem *item
,gpointer user_data
);
A function prototype callback which is called for container adds or removes (after adds, before removes).
void (*IpatchContainerDisconnect) (IpatchContainer *container
,IpatchItem *child
,gpointer user_data
);
A function prototype which is called when a callback gets disconnected.
container |
Container item |
|
child |
Match child item of original connect
( |
|
user_data |
User defined pointer assigned when callback connected |
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.
[skip]
GList *
ipatch_container_get_children_list (IpatchContainer *container
);
Get a list of all child items from a container object. The returned list object can be iterated over safely even in a multi-thread environment.
[rename-to ipatch_container_get_children]
New object list containing all child items (an empty
list if no children). Free the list with ipatch_glist_unref_free()
when finished using it.
[element-type Ipatch.Item][transfer full][nullable]
Since: 1.1.0
GList * ipatch_container_get_children_by_type (IpatchContainer *container
,GType type
);
Get a list of child items from a container object. The returned list object can be iterated over safely even in a multi-thread environment.
container |
Container object |
|
type |
GType of child items to get (will match type descendants as well) |
New object list containing all matching items (an empty
list if no items matched). Free the list with ipatch_glist_unref_free()
when finished using it.
[element-type Ipatch.Item][transfer full][nullable]
Since: 1.1.0
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.
const GType *
ipatch_container_get_virtual_types (IpatchContainer *container
);
Get an array of virtual types for a container object. Virtual types are
used to group child items in user interfaces (an example is SoundFont
"Percussion Presets" which contains all presets in bank number 128). To
discover what virtual container a child object is part of lookup it's
"virtual-parent-type" type property (ipatch_type_get()
or
ipatch_type_object_get()
).
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.
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 (see other
special requirements for using this function).
Only inserting in the first or last position (pos
is 0 or less than 0)
is guaranteed.
void ipatch_container_append (IpatchContainer *container
,IpatchItem *item
);
Appends an item to a container's children.
void ipatch_container_add (IpatchContainer *container
,IpatchItem *item
);
Just an alias for ipatch_container_append()
.
void ipatch_container_prepend (IpatchContainer *container
,IpatchItem *item
);
Prepends an item to a container's children.
void ipatch_container_remove (IpatchContainer *container
,IpatchItem *item
);
Removes an item
from container
.
void
ipatch_container_remove_all (IpatchContainer *container
);
Removes all items from a container
object.
guint ipatch_container_count (IpatchContainer *container
,GType type
);
Counts children of a specific type
(or derived thereof) in
a container
object.
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).
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()
).
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
);
This function should not normally be used. It is provided to allow for custom high performance functions involving container adds. If used, certain precautions and requirements must be followed.
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.
Also left up to the caller is a call to ipatch_container_add_notify()
to
notify that the item has been added (should be called after this function
and outside of container
lock). It is not necessary to notify if hooks
are not enabled for container
or caller doesn't care.
MT-NOTE: The container
object should be write locked, or single thread
access ensured, for the duration of this call and prior iterator functions.
void ipatch_container_remove_iter (IpatchContainer *container
,IpatchIter *iter
);
This function should not normally be used. It is provided to allow for custom high performance functions involving container removes. If used, certain precautions and requirements must be followed.
Removes an item from a container
object. The item is specified by the
current position in iter
. It is left up to the caller to call
ipatch_container_remove_notify()
(should be called before this function
and out of container
lock) to notify that the item will be removed.
It is not necessary to notify if hooks are not enabled for container
or
caller doesn't care.
MT-NOTE: The container
object should be write locked, or single thread
access ensured, for the duration of this call and prior iterator functions.
void ipatch_container_add_notify (IpatchContainer *container
,IpatchItem *child
);
Notify that a child add has occurred to an IpatchContainer object.
Should be called after the add has occurred. This function is normally
not needed except when using ipatch_container_insert_iter()
.
void ipatch_container_remove_notify (IpatchContainer *container
,IpatchItem *child
);
Notify that a container remove will occur to an IpatchContainer object.
Should be called before the remove occurs. This function is normally not
needed, except when using ipatch_container_remove_iter()
.
guint ipatch_container_add_connect (IpatchContainer *container
,IpatchContainerCallback callback
,IpatchContainerDisconnect disconnect
,gpointer user_data
);
Adds a callback which gets called when a container item add operation occurs
and the container matches container
. When container
is NULL
, callback
will be called for every container add operation.
[skip]
guint ipatch_container_add_connect_notify (IpatchContainer *container
,IpatchContainerCallback callback
,GDestroyNotify notify_func
,gpointer user_data
);
Adds a callback which gets called when a container item add operation occurs
and the container matches container
. When container
is NULL
, callback
will be called for every container add operation.
[rename-to ipatch_container_add_connect]
container |
Container to match ( |
[nullable] |
callback |
Callback function to call on match. |
[scope notified][closure user_data] |
notify_func |
Callback destroy notify
when callback is disconnected or |
[scope async][closure user_data][nullable] |
user_data |
User defined data pointer to pass to |
[nullable] |
Handler ID which can be used to disconnect the callback or 0 on error (only occurs on invalid function parameters).
Since: 1.1.0
guint ipatch_container_remove_connect (IpatchContainer *container
,IpatchItem *child
,IpatchContainerCallback callback
,IpatchContainerDisconnect disconnect
,gpointer user_data
);
Adds a callback which gets called when a container item remove operation
occurs and the container matches container
and child item matches child
.
The container
and/or child
parameters can be NULL
in which case they are
wildcard. If both are NULL
then callback
will be called for every
container remove operation. Note that specifying only child
or both
container
and child
is the same, since a child belongs to only one container.
[skip]
container |
Container to match ( |
[nullable] |
child |
Child item to match ( |
[nullable] |
callback |
Callback function to call on match |
|
disconnect |
Function to call when callback is disconnected or |
[nullable] |
user_data |
User defined data pointer to pass to |
[closure] |
guint ipatch_container_remove_connect_notify (IpatchContainer *container
,IpatchItem *child
,IpatchContainerCallback callback
,GDestroyNotify notify_func
,gpointer user_data
);
Adds a callback which gets called when a container item remove operation
occurs and the container matches container
and child item matches child
.
The container
and/or child
parameters can be NULL
in which case they are
wildcard. If both are NULL
then callback
will be called for every
container remove operation. Note that specifying only child
or both
container
and child
is the same, since a child belongs to only one container.
[rename-to ipatch_container_remove_connect]
container |
Container to match ( |
[nullable] |
child |
Child item to match ( |
[nullable] |
callback |
Callback function to call on match. |
[scope notified][closure user_data] |
notify_func |
Function to call
when callback is disconnected or |
[scope async][closure user_data][nullable] |
user_data |
User defined data pointer to pass to |
[nullable] |
Handler ID which can be used to disconnect the callback or 0 on error (only occurs on invalid function parameters).
Since: 1.1.0
void
ipatch_container_add_disconnect (guint handler_id
);
Disconnects a container add callback previously connected with
ipatch_container_add_connect()
by handler ID. The
ipatch_container_add_disconnect_matched()
function can be used instead to
disconnect by original callback criteria and is actually faster.
void ipatch_container_add_disconnect_matched (IpatchContainer *container
,IpatchContainerCallback callback
,gpointer user_data
);
Disconnects a container add callback previously connected with
ipatch_container_add_connect()
by match criteria.
[skip]
void
ipatch_container_remove_disconnect (guint handler_id
);
Disconnects a container remove callback previously connected with
ipatch_container_remove_connect()
by handler ID. The
ipatch_container_remove_disconnect_matched()
function can be used instead to
disconnect by original callback criteria and is actually faster.
void ipatch_container_remove_disconnect_matched (IpatchContainer *container
,IpatchItem *child
,IpatchContainerCallback callback
,gpointer user_data
);
Disconnects a handler previously connected with
ipatch_container_remove_connect()
by match criteria.
[skip]