## IpatchSF2ModItem

IpatchSF2ModItem — SoundFont modulator item interface

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    typedef             IpatchSF2ModItem;
                        IpatchSF2ModItemIface;
    #define             ipatch_sf2_mod_item_add             (item, mod)
    GSList *            ipatch_sf2_mod_item_get_mods        (IpatchSF2ModItem *item);
    void                ipatch_sf2_mod_item_set_mods        (IpatchSF2ModItem *item,
                                                             GSList *mod_list,
                                                             int flags);
    void                ipatch_sf2_mod_item_insert          (IpatchSF2ModItem *item,
                                                             const IpatchSF2Mod *mod,
                                                             int pos);
    void                ipatch_sf2_mod_item_remove          (IpatchSF2ModItem *item,
                                                             const IpatchSF2Mod *mod);
    void                ipatch_sf2_mod_item_change          (IpatchSF2ModItem *item,
                                                             const IpatchSF2Mod *oldmod,
                                                             const IpatchSF2Mod *newmod);
    guint               ipatch_sf2_mod_item_count           (IpatchSF2ModItem *item);

## Object Hierarchy

      GInterface
       +----IpatchSF2ModItemIface

## Prerequisites

IpatchSF2ModItemIface requires IpatchItem.

## Known Implementations

IpatchSF2ModItemIface is implemented by IpatchSF2Inst, IpatchSF2Zone, IpatchSF2PZone, IpatchSF2IZone and IpatchSF2Preset.

## Properties

      "modulators"               IpatchSF2ModList*     : Read / Write

## Description

An interface type which is used by IpatchSF2Preset, IpatchSF2Inst, IpatchSF2PZone and IpatchSF2IZone objects to add modulator realtime effect functionality.

## Details

### IpatchSF2ModItem

    typedef IpatchItem IpatchSF2ModItem;

### IpatchSF2ModItemIface

    typedef struct _IpatchSF2ModItemIface IpatchSF2ModItemIface;

### ipatch_sf2_mod_item_add()

    #define             ipatch_sf2_mod_item_add(item, mod)

### ipatch_sf2_mod_item_get_mods ()

    GSList *            ipatch_sf2_mod_item_get_mods        (IpatchSF2ModItem *item);

Gets a list of modulators from an item with modulators. List should be freed with `ipatch_sf2_mod_list_free()` (free_mods set to `TRUE`) when finished with it.

`item` : | Item with modulators
Returns : | New list of modulators (IpatchSF2Mod) in `item` or `NULL` if no modulators. Remember to free it with `ipatch_sf2_mod_list_free()` when finished.

### ipatch_sf2_mod_item_set_mods ()

    void                ipatch_sf2_mod_item_set_mods        (IpatchSF2ModItem *item,
                                                             GSList *mod_list,
                                                             int flags);

Sets the complete modulator list of an item with modulators. If IPATCH_SF2_MOD_NO_NOTIFY is not in `flags` then IpatchItem property notify is done.

`item` : | Item with modulators
`mod_list` : | Modulator list to assign to zone.
`flags` : | Flags for controlling list duplication and item property notification (IpatchSF2ModFlags). If IPATCH_SF2_MOD_NO_DUPLICATE is set then ownership of `mod_list` is taken over (not duplicated). If IPATCH_SF2_MOD_NO_NOTIFY is set, then item property notify will not be done.

### ipatch_sf2_mod_item_insert ()

    void                ipatch_sf2_mod_item_insert          (IpatchSF2ModItem *item,
                                                             const IpatchSF2Mod *mod,
                                                             int pos);

Inserts a modulator into an item's modulator list. Does not check for duplicates! The modulator is not used directly, a new one is created and the values in `mod` are copied to it. An IpatchItem property notify is done.

`item` : | Item with modulators
`mod` : | Modulator to insert (a new modulator is created and the values are copied to it)
`pos` : | Index position in zone's modulator list to insert (0 = first, < 0 = last)

### ipatch_sf2_mod_item_remove ()

    void                ipatch_sf2_mod_item_remove          (IpatchSF2ModItem *item,
                                                             const IpatchSF2Mod *mod);

Remove a modulator from an item with modulators. The modulator values in `mod` are used to search the modulator list. The first modulator that matches all fields in `mod` is removed. An IpatchItem property notify is done.

`item` : | Item with modulators
`mod` : | Matching values of modulator to remove

### ipatch_sf2_mod_item_change ()

    void                ipatch_sf2_mod_item_change          (IpatchSF2ModItem *item,
                                                             const IpatchSF2Mod *oldmod,
                                                             const IpatchSF2Mod *newmod);

Sets the values of an existing modulator in an item with modulators. The modulator list in item is searched for a modulator that matches the values in `oldmod`. If a modulator is found its values are set to those in `newmod`. If it is not found, nothing is done. If change occurs IpatchItem property notify is done.

`item` : | Item with modulators
`oldmod` : | Current values of modulator to set
`newmod` : | New modulator values

### ipatch_sf2_mod_item_count ()

    guint               ipatch_sf2_mod_item_count           (IpatchSF2ModItem *item);

Count number of modulators in an item with modulators.

`item` : | Item with modulators
Returns : | Count of modulators

## Property Details

### The `"modulators"` property

      "modulators"               IpatchSF2ModList*     : Read / Write

Modulators.