## BtPattern

BtPattern — class for an event pattern of a BtMachine instance

## Synopsis

    #include <libbtcore/core.h>

    struct              BtPattern;
    enum                BtPatternCmd;
    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);
    BtPattern *         bt_pattern_copy                     (const BtPattern * const self);
    void                bt_pattern_delete_column            (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_pattern_delete_columns           (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    void                bt_pattern_delete_full_row          (const BtPattern * const self,
                                                             const gulong tick);
    void                bt_pattern_delete_row               (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    gboolean            bt_pattern_deserialize_column       (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param,
                                                             const gchar *data);
    void                bt_pattern_flip_column              (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_pattern_flip_columns             (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    BtPatternCmd        bt_pattern_get_cmd                  (const BtPattern * const self,
                                                             const gulong tick);
    gchar *             bt_pattern_get_global_event         (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    GValue *            bt_pattern_get_global_event_data    (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    gulong              bt_pattern_get_global_param_index   (const BtPattern * const self,
                                                             const gchar * const name,
                                                             GError **error);
    gchar *             bt_pattern_get_voice_event          (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);
    GValue *            bt_pattern_get_voice_event_data     (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong voice,
                                                             const gulong param);
    gulong              bt_pattern_get_voice_param_index    (const BtPattern * const self,
                                                             const gchar * const name,
                                                             GError **error);
    void                bt_pattern_insert_full_row          (const BtPattern * const self,
                                                             const gulong tick);
    void                bt_pattern_insert_row               (const BtPattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    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);
    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);
    void                bt_pattern_serialize_column         (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param,
                                                             GString *data);
    void                bt_pattern_serialize_columns        (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             GString *data);
    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);
    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);
    gboolean            bt_pattern_tick_has_data            (const BtPattern * const self,
                                                             const gulong 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

## Signals

      "global-param-changed"                           : No Hooks
      "pattern-changed"                                : No Hooks
      "voice-param-changed"                            : No Hooks

## Description

A pattern contains a grid of events. Events are parameter changes in BtMachine objects. The events are stored as GValues. Cells contaning `NULL` have no event for the parameter at the time.

Patterns can have individual length. The length is meassured in ticks. How much that is in e.g. milliseconds is determined by "bpm" and "tpm".

The number of voices (tracks) is the same in all patterns of a machine. If the voices are changed on the machine patterns resize themself.

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

## Details

### struct BtPattern

    struct BtPattern;

Holds a sequence of events for a BtMachine.

### enum BtPatternCmd

    typedef enum {
      BT_PATTERN_CMD_NORMAL=0,
      BT_PATTERN_CMD_BREAK,
      BT_PATTERN_CMD_MUTE,
      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_BREAK` | no more notes
`BT_PATTERN_CMD_MUTE` | be quiet immediately
`BT_PATTERN_CMD_SOLO` | be the only one playing
`BT_PATTERN_CMD_BYPASS` | be uneffective (pass through)

### 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_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_delete_column ()

    void                bt_pattern_delete_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.6

### bt_pattern_delete_columns ()

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

Clear 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.6

### 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_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_deserialize_column ()

    gboolean            bt_pattern_deserialize_column       (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param,
                                                             const gchar *data);

Deserializes values to `start_tick` to `end_tick` for `param` from `data`.

`self` : | the pattern
`start_tick` : | the start postion for the range
`end_tick` : | the end postion for the range
`param` : | the parameter
`data` : | the source data
Returns : | `TRUE` for success, `FALSE` e.g. to indicate incompative GType values for the column specified by `param` and the `data`.

Since 0.6

### bt_pattern_flip_column ()

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

Flips values from `start_tick` to `end_tick` for `param` up-side down.

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

Since 0.6

### bt_pattern_flip_columns ()

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

Flips values from `start_tick` to `end_tick` for all params up-side down.

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

Since 0.5

### 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_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_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 BT_IS_GVALUE(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_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_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_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 BT_IS_GVALUE(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_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_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_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_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_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

### bt_pattern_serialize_column ()

    void                bt_pattern_serialize_column         (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param,
                                                             GString *data);

Serializes values from `start_tick` to `end_tick` for `param` into `data`.

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

Since 0.6

### bt_pattern_serialize_columns ()

    void                bt_pattern_serialize_columns        (const BtPattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             GString *data);

Serializes values from `start_tick` to `end_tick` for all params into `data`.

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

Since 0.6

### 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_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_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

## Property Details

### The `"id"` property

      "id"                       gchar*                : Read / Write / Construct

pattern identifier (unique per song).

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

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)      : 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,
                                                            gboolean   intermediate,
                                                            gpointer   user_data)         : No Hooks

Signals that this pattern has been changed (more than in one place). When doing e.g. lin inserts, one will receive two updtes, one before and one after. The first will have `intermediate`=TRUE. Applications can use that to defer change-consolidation.

`self` : | the pattern object that emitted the signal
`intermediate` : | boolean flag that is `TRUE` to signal that more change are comming
`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)      : 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.