## BtPattern

BtPattern — class for an event pattern of a BtMachine instance

## Functions

void | bt_pattern_blend_columns ()
void | bt_pattern_clear_columns ()
BtPattern * | bt_pattern_copy ()
void | bt_pattern_delete_row ()
void | bt_pattern_flip_columns ()
gchar * | bt_pattern_get_global_event ()
GValue * | bt_pattern_get_global_event_data ()
BtValueGroup * | bt_pattern_get_global_group ()
BtValueGroup * | bt_pattern_get_group_by_parameter_group ()
gchar * | bt_pattern_get_voice_event ()
GValue * | bt_pattern_get_voice_event_data ()
BtValueGroup * | bt_pattern_get_voice_group ()
gchar * | bt_pattern_get_wire_event ()
GValue * | bt_pattern_get_wire_event_data ()
BtValueGroup * | bt_pattern_get_wire_group ()
void | bt_pattern_insert_row ()
BtPattern * | bt_pattern_new ()
void | bt_pattern_randomize_columns ()
void | bt_pattern_range_randomize_columns ()
void | bt_pattern_serialize_columns ()
gboolean | bt_pattern_set_global_event ()
gboolean | bt_pattern_set_voice_event ()
gboolean | bt_pattern_set_wire_event ()
gboolean | bt_pattern_test_global_event ()
gboolean | bt_pattern_test_tick ()
gboolean | bt_pattern_test_voice_event ()
gboolean | bt_pattern_test_wire_event ()

## Properties

BtPattern * | copy-source | Write / Construct Only
gulong | length | Read / Write / Construct
gulong | voices | Read

## Signals

void | group-changed | No Hooks
void | param-changed | No Hooks
void | pattern-changed | No Hooks

## Types and Values

struct | BtPattern

## Object Hierarchy

        GObject
        ╰── BtCmdPattern
            ╰── BtPattern

## Implemented Interfaces

BtPattern implements BtPersistence.

## Includes

    #include <libbtcore/core.h>

## Description

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

Patterns can have individual lengths. The length is measured in ticks. How much that is in e.g. milliseconds is determined by “bpm” and “tpb”.

A pattern might consist of several groups. These are mapped to the global parameters of a machine and the voice parameters for each machine voice (if any). The number of voices (tracks) is the same in all patterns of a machine. If the voices are changed on the machine patterns resize themselves.

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

## Functions

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

#### Parameters

self | the pattern |
start_tick | the start position for the range |
end_tick | the end position for the range |

Since: 0.3

### bt_pattern_clear_columns ()

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

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

#### Parameters

self | the pattern |
start_tick | the start position for the range |
end_tick | the end position for the range |

Since: 0.6

### bt_pattern_copy ()

    BtPattern *
    bt_pattern_copy (const BtPattern * const self);

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

#### Parameters

self | the pattern to create a copy from |

#### Returns

the new instance or `NULL` in case of an error.

[transfer full]

### bt_pattern_delete_row ()

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

Delete row for all parameters.

#### Parameters

self | the pattern |
tick | the position to delete |

Since: 0.3

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

#### Parameters

self | the pattern |
start_tick | the start position for the range |
end_tick | the end position for the range |

Since: 0.5

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

#### Parameters

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

Do not modify the contents!

#### Parameters

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_group ()

    BtValueGroup *
    bt_pattern_get_global_group (const BtPattern * const self);

Get the BtValueGroup for global parameters.

#### Parameters

self | the pattern |

#### Returns

the group owned by the pattern.

[transfer none]

### bt_pattern_get_group_by_parameter_group ()

    BtValueGroup *
    bt_pattern_get_group_by_parameter_group
                                   (const BtPattern * const self,
                                    BtParameterGroup *param_group);

Get the BtValueGroup for the given `param_group` .

#### Parameters

self | the pattern |
param_group | the BtParameterGroup to get the group for |

#### Returns

the group owned by the pattern.

[transfer none]

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

#### Parameters

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

Do not modify the contents!

#### Parameters

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_group ()

    BtValueGroup *
    bt_pattern_get_voice_group (const BtPattern * const self,
                                const gulong voice);

Get the BtValueGroup for voice parameters.

#### Parameters

self | the pattern |
voice | the voice to get the group for |

#### Returns

the group owned by the pattern.

[transfer none]

### bt_pattern_get_wire_event ()

    gchar *
    bt_pattern_get_wire_event (const BtPattern * const self,
                               const gulong tick,
                               const BtWire *wire,
                               const gulong param);

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

#### Parameters

self | the pattern the cell belongs to |
tick | the tick (time) position starting with 0 |
wire | the related wire object |
param | the number of the wire parameter starting with 0 |

#### Returns

a newly allocated string with the data or `NULL` on error

### bt_pattern_get_wire_event_data ()

    GValue *
    bt_pattern_get_wire_event_data (const BtPattern * const self,
                                    const gulong tick,
                                    const BtWire *wire,
                                    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).

Do not modify the contents!

#### Parameters

self | the pattern to search for the wire param |
tick | the tick (time) position starting with 0 |
wire | the related wire object |
param | the number of the wire parameter starting with 0 |

#### Returns

the GValue or `NULL` if out of the pattern range

### bt_pattern_get_wire_group ()

    BtValueGroup *
    bt_pattern_get_wire_group (const BtPattern * const self,
                               const BtWire *wire);

Get the BtValueGroup for wire parameters.

#### Parameters

self | the pattern |
wire | the BtWire to get the group for |

#### Returns

the group owned by the pattern.

[transfer none]

### bt_pattern_insert_row ()

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

Insert one empty row for all parameters.

#### Parameters

self | the pattern |
tick | the position to insert at |

Since: 0.3

### bt_pattern_new ()

    BtPattern *
    bt_pattern_new (const BtSong * const song,
                    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.

#### Parameters

song | the song the new instance belongs to |
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_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.

#### Parameters

self | the pattern |
start_tick | the start position for the range |
end_tick | the end position for the range |

Since: 0.3

### bt_pattern_range_randomize_columns ()

    void
    bt_pattern_range_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 using the first and last value as bounds for the random values.

#### Parameters

self | the pattern |
start_tick | the start position for the range |
end_tick | the end position for the range |

Since: 0.7

### 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` .

#### Parameters

self | the pattern |
start_tick | the start position for the range |
end_tick | the end position 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.

#### Parameters

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.

#### Parameters

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 voice parameter starting with 0 |
value | the string representation of the value to store |

#### Returns

`TRUE` for success

### bt_pattern_set_wire_event ()

    gboolean
    bt_pattern_set_wire_event (const BtPattern * const self,
                               const gulong tick,
                               const BtWire *wire,
                               const gulong param,
                               const gchar * const value);

Stores the supplied value into the specified pattern cell.

#### Parameters

self | the pattern the cell belongs to |
tick | the tick (time) position starting with 0 |
wire | the related wire object |
param | the number of the wire 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.

#### Parameters

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_tick ()

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

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

#### Parameters

self | the pattern to check |
tick | the tick index in the pattern |

#### Returns

`TRUE` is there are events, `FALSE` otherwise

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

#### Parameters

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 voice parameter starting with 0 |

#### Returns

`TRUE` if there is an event

### bt_pattern_test_wire_event ()

    gboolean
    bt_pattern_test_wire_event (const BtPattern * const self,
                                const gulong tick,
                                const BtWire *wire,
                                const gulong param);

Tests if there is an event in the specified cell.

#### Parameters

self | the pattern the cell belongs to |
tick | the tick (time) position starting with 0 |
wire | the related wire object |
param | the number of the wire parameter starting with 0 |

#### Returns

`TRUE` if there is an event

## Types and Values

### struct BtPattern

    struct BtPattern;

Holds a sequence of events for a BtMachine.

## Property Details

### The `“copy-source”` property

      “copy-source”              BtPattern *

pattern to copy data from.

Flags: Write / Construct Only

### The `“length”` property

      “length”                   gulong

length of the pattern in ticks.

Flags: Read / Write / Construct

### The `“voices”` property

      “voices”                   gulong

number of voices in the pattern.

Flags: Read

## Signal Details

### The `“group-changed”` signal

    void
    user_function (BtPattern        *self,
                   BtParameterGroup *param_group,
                   gboolean          intermediate,
                   gpointer          user_data)

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

#### Parameters

self | the pattern object that emitted the signal |
param_group | the parameter group |
intermediate | flag that is `TRUE` to signal that more change are coming |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

### The `“param-changed”` signal

    void
    user_function (BtPattern        *self,
                   BtParameterGroup *param_group,
                   gulong            tick,
                   gulong            param,
                   gpointer          user_data)

Signals that a param of this pattern has been changed.

#### Parameters

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

Flags: No Hooks

### The `“pattern-changed”` signal

    void
    user_function (BtPattern *self,
                   gboolean   intermediate,
                   gpointer   user_data)

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

#### Parameters

self | the pattern object that emitted the signal |
intermediate | flag that is `TRUE` to signal that more change are coming |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks