IpatchBase

IpatchBase — Base instrument file object type

Stability Level

Stable, unless otherwise indicated

Functions

Properties

gboolean changed Read / Write
IpatchFile * file Read / Write
char * file-name Read / Write
gboolean saved Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── IpatchItem
        ╰── IpatchContainer
            ╰── IpatchBase
                ├── IpatchDLS2
                ├── IpatchSF2
                ├── IpatchSLI
                ╰── IpatchVBank

Description

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

Functions

ipatch_base_type_get_mime_type ()

char *
ipatch_base_type_get_mime_type (GType base_type);

Get the mime type of the file type associated with the given base patch file type.

Parameters

base_type

IpatchBase derived type to get mime type of

 

Returns

Mime type or NULL if none assigned for this base type. Free the string when finished with it.

Since: 1.1.0


ipatch_base_set_file ()

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

Sets the file object associated with a patch.

Parameters

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.

Parameters

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.

[transfer full]


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.

Parameters

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.

Parameters

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.

Parameters

base

Patch base object

 

bank

MIDI bank number.

[inout]

program

MIDI program number.

[inout]

exclude

Child of base with MIDI locale to exclude or NULL.

[nullable]

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).

Parameters

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.

[transfer full]


ipatch_base_save ()

gboolean
ipatch_base_save (IpatchBase *base,
                  GError **err);

Save a patch item to the assigned filename or file object. This function handles saving over an existing file and migrates sample stores as needed.

Parameters

base

Base item to save

 

err

Location to store error info or NULL

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


ipatch_base_save_to_filename ()

gboolean
ipatch_base_save_to_filename (IpatchBase *base,
                              const char *filename,
                              GError **err);

Save a patch item to a file. This function handles saving over an existing file and migrates sample stores as needed. It is an error to try to save over an open file that is not owned by base .

Parameters

base

Base item to save

 

filename

New file name to save to or NULL to use current one.

[nullable]

err

Location to store error info or NULL

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


ipatch_base_save_a_copy ()

gboolean
ipatch_base_save_a_copy (IpatchBase *base,
                         const char *filename,
                         GError **err);

Save a patch item to a file name.

Parameters

base

Base item to save

 

filename

File name to save a copy to

 

err

Location to store error info or NULL

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


ipatch_base_close ()

gboolean
ipatch_base_close (IpatchBase *base,
                   GError **err);

Close a base instrument object (using ipatch_item_remove()), migrating sample data as needed.

Parameters

base

Base item to close

 

err

Location to store error info or NULL

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0


ipatch_close_base_list ()

gboolean
ipatch_close_base_list (IpatchList *list,
                        GError **err);

Close a list of base instrument objects (using ipatch_item_remove_recursive()), migrating sample data as needed. Using this function instead of ipatch_base_close() can save on unnecessary sample data migrations, if multiple base objects reference the same sample data.

Parameters

list

List of base objects to close (non base objects are skipped)

 

err

Location to store error info or NULL

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)

Since: 1.1.0

Types and Values

enum IpatchBaseFlags

Members

IPATCH_BASE_CHANGED

Does the base object have any unsaved changes?

 

IPATCH_BASE_SAVED

Has the base object ever been saved?

 

IPATCH_BASE_UNUSED_FLAG_SHIFT

#define IPATCH_BASE_UNUSED_FLAG_SHIFT (IPATCH_ITEM_UNUSED_FLAG_SHIFT + 4)

IPATCH_BASE_DEFAULT_NAME

#define IPATCH_BASE_DEFAULT_NAME "Untitled"

Property Details

The “changed” property

  “changed”                  gboolean

Changed Flag.

Owner: IpatchBase

Flags: Read / Write

Default value: TRUE


The “file” property

  “file”                     IpatchFile *

File Object.

Owner: IpatchBase

Flags: Read / Write


The “file-name” property

  “file-name”                char *

File Name.

Owner: IpatchBase

Flags: Read / Write

Default value: "untitled"


The “saved” property

  “saved”                    gboolean

Been Saved Flag.

Owner: IpatchBase

Flags: Read / Write

Default value: FALSE