## IpatchBase IpatchBase — Base instrument file object type |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    enum                IpatchBaseFlags;
    #define             IPATCH_BASE_UNUSED_FLAG_SHIFT
                        IpatchBase;
    #define             IPATCH_BASE_DEFAULT_NAME
    void                ipatch_base_set_file                (IpatchBase *base,
                                                             IpatchFile *file);
    IpatchFile *        ipatch_base_get_file                (IpatchBase *base);
    void                ipatch_base_set_file_name           (IpatchBase *base,
                                                             const char *file_name);
    char *              ipatch_base_get_file_name           (IpatchBase *base);
    void                ipatch_base_find_unused_midi_locale (IpatchBase *base,
                                                             int *bank,
                                                             int *program,
                                                             const IpatchItem *exclude,
                                                             gboolean percussion);
    IpatchItem *        ipatch_base_find_item_by_midi_locale
                                                            (IpatchBase *base,
                                                             int bank,
                                                             int program);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchContainer
                   +----IpatchBase
                         +----IpatchDLS2
                         +----IpatchSF2
                         +----IpatchVBank

## Properties

      "changed"                  gboolean              : Read / Write
      "file"                     IpatchFile*           : Read / Write
      "file-name"                gchar*                : Read / Write
      "saved"                    gboolean              : Read / Write

## Description

Defines an abstract object type which is used as the basis of instrument files, such as IpatchSF2, IpatchDLS, etc.

## Details

### enum IpatchBaseFlags

    typedef enum
    {
      /* patch changed flag */
      IPATCH_BASE_CHANGED = 1 << IPATCH_ITEM_UNUSED_FLAG_SHIFT,
      /* patch been saved ever? */
      IPATCH_BASE_SAVED   = 1 << (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 1)
    } IpatchBaseFlags;

### IPATCH_BASE_UNUSED_FLAG_SHIFT

    #define IPATCH_BASE_UNUSED_FLAG_SHIFT (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 4)

### IpatchBase

    typedef struct _IpatchBase IpatchBase;

### IPATCH_BASE_DEFAULT_NAME

    #define IPATCH_BASE_DEFAULT_NAME "Untitled"

### ipatch_base_set_file ()

    void                ipatch_base_set_file                (IpatchBase *base,
                                                             IpatchFile *file);

Sets the file object associated with a patch.

`base` : | Patch base object to set file object of
`file` : | File object

### ipatch_base_get_file ()

    IpatchFile *        ipatch_base_get_file                (IpatchBase *base);

Get the file object associated with a patch base object. Caller owns a reference to the returned file object and it should be unrefed when done with it.

`base` : | Patch base object to get file object from
Returns : | File object or `NULL` if not set. Remember to unref it when done with it.

### ipatch_base_set_file_name ()

    void                ipatch_base_set_file_name           (IpatchBase *base,
                                                             const char *file_name);

Sets the file name of the file object in a patch base object. File object should have been set before calling this function (otherwise request is silently ignored). A convenience function as one could get the file object and set it directly.

`base` : | Patch base object to set file name of
`file_name` : | Path and name to set filename to

### ipatch_base_get_file_name ()

    char *              ipatch_base_get_file_name           (IpatchBase *base);

Get the file name of the file object in a base patch item. A convenience function.

`base` : | Base patch item to get file name from.
Returns : | New allocated file name or `NULL` if not set or file object not set. String should be freed when finished with it.

### ipatch_base_find_unused_midi_locale ()

    void                ipatch_base_find_unused_midi_locale (IpatchBase *base,
                                                             int *bank,
                                                             int *program,
                                                             const IpatchItem *exclude,
                                                             gboolean percussion);

Finds an unused MIDI locale (bank:program number pair) in a patch base object. The way in which MIDI bank and program numbers are used is implementation dependent. Percussion instruments often affect the bank parameter (for example SoundFont uses bank 128 for percussion presets). On input the `bank` and `program` parameters set the initial locale to start from (set to 0:0 to find the first free value). If the `percussion` parameter is set it may affect `bank`, if its not set, bank will not be modified (e.g., if bank is a percussion value it will be used). The exclude parameter can be set to a child item of `base` to exclude from the list of "used" locales (useful when making an item unique that is already parented to `base`). On return `bank` and `program` will be set to an unused MIDI locale based on the input criteria.

`base` : | Patch base object
`bank` : | MIDI bank number (input and output parameter)
`program` : | MIDI program number (input and output parameter)
`exclude` : | Child of `base` with MIDI locale to exclude or `NULL`
`percussion` : | Set to `TRUE` to find a free percussion MIDI locale

### ipatch_base_find_item_by_midi_locale ()

    IpatchItem *        ipatch_base_find_item_by_midi_locale
                                                            (IpatchBase *base,
                                                             int bank,
                                                             int program);

Find a child object in a base patch object which matches the given MIDI locale (`bank` and `program` numbers).

`base` : | Patch base object
`bank` : | MIDI bank number of item to search for
`program` : | MIDI program number of item to search for
Returns : | The item or `NULL` if not found. The caller owns a reference to the returned object, and is responsible for unref'ing when finished.

## Property Details

### The `"changed"` property

      "changed"                  gboolean              : Read / Write

Changed Flag.

Default value: TRUE

### The `"file"` property

      "file"                     IpatchFile*           : Read / Write

File Object.

### The `"file-name"` property

      "file-name"                gchar*                : Read / Write

File Name.

Default value: "untitled"

### The `"saved"` property

      "saved"                    gboolean              : Read / Write

Been Saved Flag.

Default value: FALSE