## BtPattern

BtPattern — class for an event pattern of a BtMachine instance

## Synopsis

    #include <libbtcore/core.h>

                        BtPattern;
    enum                BtPatternCmd;
    BtPattern *         bt_pattern_new                      (const BtSong * const song,
                                                             const gchar * const id,
                                                             const gchar * const name,
                                                             const gulong length,
                                                             const BtMachine * const machine);
    BtPattern *         bt_pattern_new_with_event           (const BtSong * const song,
                                                             const BtMachine * const machine,
                                                             const BtPatternCmd cmd);
    BtPattern *         bt_pattern_copy                     (const BtPattern * const self);
    gulong              bt_pattern_get_global_param_index   (const BtPattern * const self,
                                                             const gchar * const name,
                                                             GError **error);
    gulong              bt_pattern_get_voice_param_index    (const BtPattern * const self,
                                                             const gchar * const name,
                                                             GError **error);
    GValue *            bt_pattern_get_global_event_data    (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    GValue *            bt_pattern_get_voice_event_data     (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);
    gboolean            bt_pattern_set_global_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param,
                                                             const gchar * const value);
    gboolean            bt_pattern_set_voice_event          (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param,
                                                             const gchar * const value);
    gchar *             bt_pattern_get_global_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    gchar *             bt_pattern_get_voice_event          (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);
    gboolean            bt_pattern_test_global_event        (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    gboolean            bt_pattern_test_voice_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);
    BtPatternCmd        bt_pattern_get_cmd                  (const BtPattern * const self,
                                                             const gulong tick);
    gboolean            bt_pattern_tick_has_data            (const BtPattern * const self,
                                                             const gulong tick);
    void                bt_pattern_insert_row               (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    void                bt_pattern_insert_full_row          (const BtPattern * const self,
                                                             const gulong tick);
    void                bt_pattern_delete_row               (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    void                bt_pattern_delete_full_row          (const BtPattern * const self,
                                                             const gulong tick);
    void                bt_pattern_blend_column             (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_pattern_blend_columns            (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    void                bt_pattern_randomize_column         (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_pattern_randomize_columns        (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);

## Object Hierarchy

      GObject
       +----BtPattern

## Implemented Interfaces

BtPattern implements

## Properties

      "id"                       gchar*                : Read / Write / Construct
      "is-internal"              gboolean              : Read / Write / Construct Only
      "length"                   gulong                : Read / Write / Construct
      "machine"                  BtMachine*            : Read / Write / Construct Only
      "name"                     gchar*                : Read / Write / Construct
      "song"                     BtSong*               : Read / Write / Construct Only
      "voices"                   gulong                : Read / Write

## Signals

      "global-param-changed"                           : Run Last / No Recursion / No Hooks
      "pattern-changed"                                : Run Last / No Recursion / No Hooks
      "voice-param-changed"                            : Run Last / No Recursion / No Hooks

## Description

A pattern contains a grid of events. Events are parameter changes in BtMachine objects. The events are stored aas GValues.

The patterns are used in the BtSequence to form the score of a song.

## Details

### BtPattern

    typedef struct _BtPattern BtPattern;

Holds a sequence of events for a BtMachine.

### enum BtPatternCmd

    typedef enum {
      BT_PATTERN_CMD_NORMAL=0,
      BT_PATTERN_CMD_MUTE,
      BT_PATTERN_CMD_BREAK,
      BT_PATTERN_CMD_SOLO,
      BT_PATTERN_CMD_BYPASS
    } BtPatternCmd;

A pattern has a command field for every tick. The commands are only used in static internal patterns.

`BT_PATTERN_CMD_NORMAL` | just working
`BT_PATTERN_CMD_MUTE` | be quiet immediately
`BT_PATTERN_CMD_BREAK` | no more notes
`BT_PATTERN_CMD_SOLO` | be the only one playing
`BT_PATTERN_CMD_BYPASS` | be uneffective (pass through)

### bt_pattern_new ()

    BtPattern *         bt_pattern_new                      (const BtSong * const song,
                                                             const gchar * const id,
                                                             const gchar * const name,
                                                             const gulong length,
                                                             const BtMachine * const machine);

Create a new instance. It will be automatically added to the machines pattern list.

`song` : | the song the new instance belongs to
`id` : | the id, we can use to lookup the pattern
`name` : | the display name of the pattern
`length` : | the number of ticks
`machine` : | the machine the pattern belongs to
Returns : | the new instance or `NULL` in case of an error

### bt_pattern_new_with_event ()

    BtPattern *         bt_pattern_new_with_event           (const BtSong * const song,
                                                             const BtMachine * const machine,
                                                             const BtPatternCmd cmd);

Create a new default pattern instance containg the given `cmd` event. It will be automatically added to the machines pattern list. If `cmd` is `BT_PATTERN_CMD_NORMAL` use `bt_pattern_new()` instead.

Don't call this from applications.

`song` : | the song the new instance belongs to
`machine` : | the machine the pattern belongs to
`cmd` : | a BtPatternCmd
Returns : | the new instance or `NULL` in case of an error

### bt_pattern_copy ()

    BtPattern *         bt_pattern_copy                     (const BtPattern * const self);

Create a new instance as a copy of the given instance.

`self` : | the pattern to create a copy from
Returns : | the new instance or `NULL` in case of an error

### bt_pattern_get_global_param_index ()

    gulong              bt_pattern_get_global_param_index   (const BtPattern * const self,
                                                             const gchar * const name,
                                                             GError **error);

Searches the list of registered dparam of the machine the pattern belongs to for a global dparam of the given name and returns the index if found.

`self` : | the pattern to search for the global dparam
`name` : | the name of the global dparam
`error` : | pointer to an error variable
Returns : | the index. If an error occurs the function returns 0 and sets the error variable. You should always check for error if you use this function.

### bt_pattern_get_voice_param_index ()

    gulong              bt_pattern_get_voice_param_index    (const BtPattern * const self,
                                                             const gchar * const name,
                                                             GError **error);

Searches the list of registered dparam of the machine the pattern belongs to for a voice dparam of the given name and returns the index if found.

`self` : | the pattern to search for the voice dparam
`name` : | the name of the voice dparam
`error` : | pointer to an error variable
Returns : | the index. If an error occurs the function returns 0 and sets the error variable. You should always check for error if you use this function.

### bt_pattern_get_global_event_data ()

    GValue *            bt_pattern_get_global_event_data    (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);

Fetches a cell from the given location in the pattern. If there is no event there, then the `GValue` is uninitialized. Test with G_IS_VALUE(event).

`self` : | the pattern to search for the global param
`tick` : | the tick (time) position starting with 0
`param` : | the number of the global parameter starting with 0
Returns : | the GValue or `NULL` if out of the pattern range

### bt_pattern_get_voice_event_data ()

    GValue *            bt_pattern_get_voice_event_data     (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);

Fetches a cell from the given location in the pattern. If there is no event there, then the `GValue` is uninitialized. Test with G_IS_VALUE(event).

`self` : | the pattern to search for the voice param
`tick` : | the tick (time) position starting with 0
`voice` : | the voice number starting with 0
`param` : | the number of the voice parameter starting with 0
Returns : | the GValue or `NULL` if out of the pattern range

### bt_pattern_set_global_event ()

    gboolean            bt_pattern_set_global_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param,
                                                             const gchar * const value);

Stores the supplied value into the specified pattern cell.

`self` : | the pattern the cell belongs to
`tick` : | the tick (time) position starting with 0
`param` : | the number of the global parameter starting with 0
`value` : | the string representation of the value to store
Returns : | `TRUE` for success

### bt_pattern_set_voice_event ()

    gboolean            bt_pattern_set_voice_event          (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param,
                                                             const gchar * const value);

Stores the supplied value into the specified pattern cell.

`self` : | the pattern the cell belongs to
`tick` : | the tick (time) position starting with 0
`voice` : | the voice number starting with 0
`param` : | the number of the global parameter starting with 0
`value` : | the string representation of the value to store
Returns : | `TRUE` for success

### bt_pattern_get_global_event ()

    gchar *             bt_pattern_get_global_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);

Returns the string representation of the specified cell. Free it when done.

`self` : | the pattern the cell belongs to
`tick` : | the tick (time) position starting with 0
`param` : | the number of the global parameter starting with 0
Returns : | a newly allocated string with the data or `NULL` on error

### bt_pattern_get_voice_event ()

    gchar *             bt_pattern_get_voice_event          (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);

Returns the string representation of the specified cell. Free it when done.

`self` : | the pattern the cell belongs to
`tick` : | the tick (time) position starting with 0
`voice` : | the voice number starting with 0
`param` : | the number of the global parameter starting with 0
Returns : | a newly allocated string with the data or `NULL` on error

### bt_pattern_test_global_event ()

    gboolean            bt_pattern_test_global_event        (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);

Tests if there is an event in the specified cell.

`self` : | the pattern the cell belongs to
`tick` : | the tick (time) position starting with 0
`param` : | the number of the global parameter starting with 0
Returns : | `TRUE` if there is an event

### bt_pattern_test_voice_event ()

    gboolean            bt_pattern_test_voice_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);

Tests if there is an event in the specified cell.

`self` : | the pattern the cell belongs to
`tick` : | the tick (time) position starting with 0
`voice` : | the voice number starting with 0
`param` : | the number of the global parameter starting with 0
Returns : | `TRUE` if there is an event

### bt_pattern_get_cmd ()

    BtPatternCmd        bt_pattern_get_cmd                  (const BtPattern * const self,
                                                             const gulong tick);

Returns the command id in the specified tick row.

`self` : | the pattern to query the command from
`tick` : | the tick (time) position starting with 0
Returns : | the command id

### bt_pattern_tick_has_data ()

    gboolean            bt_pattern_tick_has_data            (const BtPattern * const self,
                                                             const gulong tick);

Check if there are any event in the given pattern-row.

`self` : | the pattern to check
`tick` : | the tick index in the pattern
Returns : | `TRUE` is there are events, `FALSE` otherwise

### bt_pattern_insert_row ()

    void                bt_pattern_insert_row               (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);

Insert one empty row for given `param`.

`self` : | the pattern
`tick` : | the postion to insert at
`param` : | the parameter

Since 0.3

### bt_pattern_insert_full_row ()

    void                bt_pattern_insert_full_row          (const BtPattern * const self,
                                                             const gulong tick);

Insert one empty row for all parameters.

`self` : | the pattern
`tick` : | the postion to insert at

Since 0.3

### bt_pattern_delete_row ()

    void                bt_pattern_delete_row               (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);

Delete row for given `param`.

`self` : | the pattern
`tick` : | the postion to delete
`param` : | the parameter

Since 0.3

### bt_pattern_delete_full_row ()

    void                bt_pattern_delete_full_row          (const BtPattern * const self,
                                                             const gulong tick);

Delete row for all parameters.

`self` : | the pattern
`tick` : | the postion to delete

Since 0.3

### bt_pattern_blend_column ()

    void                bt_pattern_blend_column             (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);

Fade values from `start_tick` to `end_tick` for `param`.

`self` : | the pattern
`start_tick` : | the start postion for the range
`end_tick` : | the end postion for the range
`param` : | the parameter

Since 0.3

### bt_pattern_blend_columns ()

    void                bt_pattern_blend_columns            (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);

Fade values from `start_tick` to `end_tick` for all params.

`self` : | the pattern
`start_tick` : | the start postion for the range
`end_tick` : | the end postion for the range

Since 0.3

### bt_pattern_randomize_column ()

    void                bt_pattern_randomize_column         (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);

Randomize values from `start_tick` to `end_tick` for `param`.

`self` : | the pattern
`start_tick` : | the start postion for the range
`end_tick` : | the end postion for the range
`param` : | the parameter

Since 0.3

### bt_pattern_randomize_columns ()

    void                bt_pattern_randomize_columns        (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);

Randomize values from `start_tick` to `end_tick` for all params.

`self` : | the pattern
`start_tick` : | the start postion for the range
`end_tick` : | the end postion for the range

Since 0.3

## Property Details

### The `"id"` property

      "id"                       gchar*                : Read / Write / Construct

pattern identifier.

Default value: "unamed pattern"

### The `"is-internal"` property

      "is-internal"              gboolean              : Read / Write / Construct Only

internal (cmd-pattern) indicator.

Default value: FALSE

### The `"length"` property

      "length"                   gulong                : Read / Write / Construct

length of the pattern in ticks.

Allowed values: >= 1

### The `"machine"` property

      "machine"                  BtMachine*            : Read / Write / Construct Only

Machine object, the pattern belongs to.

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct

the display-name of the pattern.

Default value: "unamed"

### The `"song"` property

      "song"                     BtSong*               : Read / Write / Construct Only

Song object, the pattern belongs to.

### The `"voices"` property

      "voices"                   gulong                : Read / Write

number of voices in the pattern.

## Signal Details

### The `"global-param-changed"` signal

    void                user_function                      (BtPattern *self,
                                                            gulong     tick,
                                                            gulong     param,
                                                            gpointer   user_data)      : Run Last / No Recursion / No Hooks

signals that a global param of this pattern has been changed

`self` : | the pattern object that emitted the signal
`tick` : | the tick position inside the pattern
`param` : | the global parameter index
`user_data` : | user data set when the signal handler was connected.

### The `"pattern-changed"` signal

    void                user_function                      (BtPattern *self,
                                                            gpointer   user_data)      : Run Last / No Recursion / No Hooks

signals that this pattern has been changed (more than in one place)

`self` : | the pattern object that emitted the signal
`user_data` : | user data set when the signal handler was connected.

### The `"voice-param-changed"` signal

    void                user_function                      (BtPattern *self,
                                                            gulong     tick,
                                                            gulong     voice,
                                                            gulong     param,
                                                            gpointer   user_data)      : Run Last / No Recursion / No Hooks

signals that a voice param of this pattern has been changed

`self` : | the pattern object that emitted the signal
`tick` : | the tick position inside the pattern
`voice` : | the voice number
`param` : | the voice parameter index
`user_data` : | user data set when the signal handler was connected.