## BtWirePattern

BtWirePattern — class for an event pattern of a BtMachine instance

## Synopsis

    #include <libbtcore/core.h>

    struct              BtWirePattern;
    void                bt_wire_pattern_blend_column        (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_wire_pattern_blend_columns       (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    BtWirePattern *     bt_wire_pattern_copy                (const BtWirePattern * const self,
                                                             const BtPattern * const pattern);
    void                bt_wire_pattern_delete_column       (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_wire_pattern_delete_columns      (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    void                bt_wire_pattern_delete_full_row     (const BtWirePattern * const self,
                                                             const gulong tick);
    void                bt_wire_pattern_delete_row          (const BtWirePattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    gboolean            bt_wire_pattern_deserialize_column  (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param,
                                                             const gchar *data);
    void                bt_wire_pattern_flip_column         (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_wire_pattern_flip_columns        (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    gchar *             bt_wire_pattern_get_event           (const BtWirePattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    GValue *            bt_wire_pattern_get_event_data      (const BtWirePattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    void                bt_wire_pattern_insert_full_row     (const BtWirePattern * const self,
                                                             const gulong tick);
    void                bt_wire_pattern_insert_row          (const BtWirePattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    BtWirePattern *     bt_wire_pattern_new                 (const BtSong * const song,
                                                             const BtWire * const wire,
                                                             const BtPattern * const pattern);
    void                bt_wire_pattern_randomize_column    (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param);
    void                bt_wire_pattern_randomize_columns   (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick);
    void                bt_wire_pattern_serialize_column    (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             const gulong param,
                                                             GString *data);
    void                bt_wire_pattern_serialize_columns   (const BtWirePattern * const self,
                                                             const gulong start_tick,
                                                             const gulong end_tick,
                                                             GString *data);
    gboolean            bt_wire_pattern_set_event           (const BtWirePattern * const self,
                                                             const gulong tick,
                                                             const gulong param,
                                                             const gchar * const value);
    gboolean            bt_wire_pattern_test_event          (const BtWirePattern * const self,
                                                             const gulong tick,
                                                             const gulong param);
    gboolean            bt_wire_pattern_tick_has_data       (const BtWirePattern * const self,
                                                             const gulong tick);

## Object Hierarchy

      GObject
       +----BtWirePattern

## Implemented Interfaces

BtWirePattern implements

## Properties

      "pattern"                  BtPattern*            : Read / Write / Construct Only
      "song"                     BtSong*               : Read / Write / Construct Only
      "wire"                     BtWire*               : Read / Write / Construct Only

## Signals

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

## Description

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

The wire-patterns are used in normal BtPattern objects as a group for each input of the BtMachine that is the owner of the pattern.

Wire-patterns synchronize their length to the length of the pattern they belong to.

## Details

### struct BtWirePattern

    struct BtWirePattern;

Class that holds a sequence of automation events for a BtWire.

### bt_wire_pattern_blend_column ()

    void                bt_wire_pattern_blend_column        (const BtWirePattern * 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_wire_pattern_blend_columns ()

    void                bt_wire_pattern_blend_columns       (const BtWirePattern * 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_wire_pattern_copy ()

    BtWirePattern *     bt_wire_pattern_copy                (const BtWirePattern * const self,
                                                             const BtPattern * const pattern);

Create a new instance as a copy of the given instance. This is usualy done in sync with `bt_pattern_copy()`.

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

### bt_wire_pattern_delete_column ()

    void                bt_wire_pattern_delete_column       (const BtWirePattern * 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_wire_pattern_delete_columns ()

    void                bt_wire_pattern_delete_columns      (const BtWirePattern * 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_wire_pattern_delete_full_row ()

    void                bt_wire_pattern_delete_full_row     (const BtWirePattern * const self,
                                                             const gulong tick);

Delete row for all parameters.

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

Since 0.3

### bt_wire_pattern_delete_row ()

    void                bt_wire_pattern_delete_row          (const BtWirePattern * 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_wire_pattern_deserialize_column ()

    gboolean            bt_wire_pattern_deserialize_column  (const BtWirePattern * 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_wire_pattern_flip_column ()

    void                bt_wire_pattern_flip_column         (const BtWirePattern * 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_wire_pattern_flip_columns ()

    void                bt_wire_pattern_flip_columns        (const BtWirePattern * 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.6

### bt_wire_pattern_get_event ()

    gchar *             bt_wire_pattern_get_event           (const BtWirePattern * 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 parameter starting with 0
Returns : | a newly allocated string with the data or `NULL` on error

### bt_wire_pattern_get_event_data ()

    GValue *            bt_wire_pattern_get_event_data      (const BtWirePattern * 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 param
`tick` : | the tick (time) position starting with 0
`param` : | the number of the parameter starting with 0
Returns : | the GValue or `NULL` if out of the pattern range

### bt_wire_pattern_insert_full_row ()

    void                bt_wire_pattern_insert_full_row     (const BtWirePattern * 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_wire_pattern_insert_row ()

    void                bt_wire_pattern_insert_row          (const BtWirePattern * 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_wire_pattern_new ()

    BtWirePattern *     bt_wire_pattern_new                 (const BtSong * const song,
                                                             const BtWire * const wire,
                                                             const BtPattern * const pattern);

Create a new instance.

`song` : | the song the new instance belongs to
`wire` : | the wire the pattern belongs to
`pattern` : | the pattern that gets extended
Returns : | the new instance or `NULL` in case of an error

### bt_wire_pattern_randomize_column ()

    void                bt_wire_pattern_randomize_column    (const BtWirePattern * 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_wire_pattern_randomize_columns ()

    void                bt_wire_pattern_randomize_columns   (const BtWirePattern * 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_wire_pattern_serialize_column ()

    void                bt_wire_pattern_serialize_column    (const BtWirePattern * 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_wire_pattern_serialize_columns ()

    void                bt_wire_pattern_serialize_columns   (const BtWirePattern * 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_wire_pattern_set_event ()

    gboolean            bt_wire_pattern_set_event           (const BtWirePattern * 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 parameter starting with 0
`value` : | the string representation of the value to store
Returns : | `TRUE` for success

### bt_wire_pattern_test_event ()

    gboolean            bt_wire_pattern_test_event          (const BtWirePattern * 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 parameter starting with 0
Returns : | `TRUE` if there is an event

### bt_wire_pattern_tick_has_data ()

    gboolean            bt_wire_pattern_tick_has_data       (const BtWirePattern * 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 `"pattern"` property

      "pattern"                  BtPattern*            : Read / Write / Construct Only

Pattern object, the wire-pattern belongs to.

### The `"song"` property

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

Song object, the pattern belongs to.

### The `"wire"` property

      "wire"                     BtWire*               : Read / Write / Construct Only

Wire object, the wire-pattern belongs to.

## Signal Details

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

    void                user_function                      (BtWirePattern *self,
                                                            gulong         tick,
                                                            BtWire        *wire,
                                                            gulong         param,
                                                            gpointer       user_data)      : No Hooks

signals that a param of this wire-pattern has been changed

`self` : | the wire-pattern object that emitted the signal
`tick` : | the tick position inside the pattern
`wire` : | the wire for which it changed
`param` : | the parameter index
`user_data` : | user data set when the signal handler was connected.

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

    void                user_function                      (BtWirePattern *self,
                                                            gpointer       user_data)      : No Hooks

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

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