## BtSequence

BtSequence — class for the event timeline of a BtSong instance

## Synopsis

    #include <libbtcore/core.h>

                        BtSequence;
    BtSequence *        bt_sequence_new                     (const BtSong * const song);
    void                bt_sequence_repair_damage           (const BtSequence * const self);
    BtMachine *         bt_sequence_get_machine             (const BtSequence * const self,
                                                             const gulong track);
    gboolean            bt_sequence_add_track               (const BtSequence * const self,
                                                             const BtMachine * const machine);
    gboolean            bt_sequence_remove_track_by_ix      (const BtSequence * const self,
                                                             const gulong track);
    gboolean            bt_sequence_remove_track_by_machine (const BtSequence * const self,
                                                             const BtMachine * const machine);
    gboolean            bt_sequence_move_track_left         (const BtSequence * const self,
                                                             const gulong track);
    gboolean            bt_sequence_move_track_right        (const BtSequence * const self,
                                                             const gulong track);
    gchar *             bt_sequence_get_label               (const BtSequence * const self,
                                                             const gulong time);
    void                bt_sequence_set_label               (const BtSequence * const self,
                                                             const gulong time,
                                                             const gchar * const label);
    BtPattern *         bt_sequence_get_pattern             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track);
    gboolean            bt_sequence_set_pattern_quick       (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const BtPattern * const pattern);
    void                bt_sequence_set_pattern             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const BtPattern * const pattern);
    GstClockTime        bt_sequence_get_bar_time            (const BtSequence * const self);
    GstClockTime        bt_sequence_get_loop_time           (const BtSequence * const self);
    gulong              bt_sequence_limit_play_pos          (const BtSequence * const self,
                                                             const gulong play_pos);
    gboolean            bt_sequence_is_pattern_used         (const BtSequence * const self,
                                                             const BtPattern * const pattern);
    void                bt_sequence_insert_rows             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const gulong rows);
    void                bt_sequence_insert_full_rows        (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong rows);
    void                bt_sequence_delete_rows             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const gulong rows);
    void                bt_sequence_delete_full_rows        (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong rows);
    void                bt_sequence_update_tempo            (const BtSequence * const self);

## Object Hierarchy

      GObject
       +----BtSequence

## Implemented Interfaces

BtSequence implements

## Properties

      "length"                   gulong                : Read / Write
      "loop"                     gboolean              : Read / Write
      "loop-end"                 glong                 : Read / Write
      "loop-start"               glong                 : Read / Write
      "song"                     BtSong*               : Read / Write / Construct Only
      "tracks"                   gulong                : Read / Write

## Description

A sequence holds grid of BtPatterns, with labels on the time axis and BtMachine instances on the track axis. It supports looping a section of the sequence (see "loop", "loop-start", "loop-end").

The BtSequence manages the GstController event queues for the BtMachines and BtWires. It uses a damage-repair based two phase algorithm to update the controller queues whenever patterns or the sequence changes.

## Details

### BtSequence

    typedef struct _BtSequence BtSequence;

Starting point for the BtSong timeline data-structures. Holds a series of BtTimeLine objects, which define the events that are sent to a BtMachine at a time.

### bt_sequence_new ()

    BtSequence *        bt_sequence_new                     (const BtSong * const song);

Create a new instance. One would not call this directly, but rather get this from a BtSong instance.

`song` : | the song the new instance belongs to
Returns : | the new instance or `NULL` in case of an error

### bt_sequence_repair_damage ()

    void                bt_sequence_repair_damage           (const BtSequence * const self);

Works through the repair queue and rebuilds controller queues, where needed.

There is usualy no need to call that manualy. Only call after soing mass updates using bt_sequence_*`_quick()` functions.

`self` : | the BtSequence

Since 0.5

### bt_sequence_get_machine ()

    BtMachine *         bt_sequence_get_machine             (const BtSequence * const self,
                                                             const gulong track);

Fetches the BtMachine for the given `track`. Unref when done.

`self` : | the BtSequence that holds the tracks
`track` : | the requested track index
Returns : | a reference to the BtMachine pointer or `NULL` in case of an error

### bt_sequence_add_track ()

    gboolean            bt_sequence_add_track               (const BtSequence * const self,
                                                             const BtMachine * const machine);

Adds a new track with the `machine` to the end.

`self` : | the BtSequence that holds the tracks
`machine` : | the BtMachine
Returns : | `TRUE` for success

### bt_sequence_remove_track_by_ix ()

    gboolean            bt_sequence_remove_track_by_ix      (const BtSequence * const self,
                                                             const gulong track);

Removes the specified `track`.

`self` : | the BtSequence that holds the tracks
`track` : | the requested track index
Returns : | `TRUE` for success

### bt_sequence_remove_track_by_machine ()

    gboolean            bt_sequence_remove_track_by_machine (const BtSequence * const self,
                                                             const BtMachine * const machine);

Removes all tracks that belong the the given `machine`.

`self` : | the BtSequence that holds the tracks
`machine` : | the BtMachine
Returns : | `TRUE` for success

### bt_sequence_move_track_left ()

    gboolean            bt_sequence_move_track_left         (const BtSequence * const self,
                                                             const gulong track);

Move the selected track on column left.

`self` : | the BtSequence that holds the tracks
`track` : | the track to move
Returns : | `TRUE` for success

### bt_sequence_move_track_right ()

    gboolean            bt_sequence_move_track_right        (const BtSequence * const self,
                                                             const gulong track);

Move the selected track on column left.

`self` : | the BtSequence that holds the tracks
`track` : | the track to move
Returns : | `TRUE` for success

### bt_sequence_get_label ()

    gchar *             bt_sequence_get_label               (const BtSequence * const self,
                                                             const gulong time);

Fetches the label for the given `time` position. Free when done.

`self` : | the BtSequence that holds the labels
`time` : | the requested time position
Returns : | a copy of the label or `NULL` in case of an error

### bt_sequence_set_label ()

    void                bt_sequence_set_label               (const BtSequence * const self,
                                                             const gulong time,
                                                             const gchar * const label);

Sets a new label for the respective `time` position.

`self` : | the BtSequence that holds the labels
`time` : | the requested time position
`label` : | the new label

### bt_sequence_get_pattern ()

    BtPattern *         bt_sequence_get_pattern             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track);

Fetches the pattern for the given `time` and `track` position. Unref when done.

`self` : | the BtSequence that holds the patterns
`time` : | the requested time position
`track` : | the requested track index
Returns : | a reference to the BtPattern or `NULL` when empty

### bt_sequence_set_pattern_quick ()

    gboolean            bt_sequence_set_pattern_quick       (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const BtPattern * const pattern);

A quick version of `bt_sequence_set_pattern()` that does not repair damaged area. Useful when doing mass updates.

Returns : | `TRUE` if a change has been made. One should call `bt_sequence_repair_damage()` in that case.

Since 0.5

### bt_sequence_set_pattern ()

    void                bt_sequence_set_pattern             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const BtPattern * const pattern);

Sets the BtPattern for the respective `time` and `track` position.

`self` : | the BtSequence that holds the patterns
`time` : | the requested time position
`track` : | the requested track index
`pattern` : | the BtPattern or `NULL` to unset

### bt_sequence_get_bar_time ()

    GstClockTime        bt_sequence_get_bar_time            (const BtSequence * const self);

Calculates the length of one sequence bar in microseconds. Divide it by `G_USEC_PER_SEC` to get it in milliseconds.

`self` : | the BtSequence of the song
Returns : | the length of one sequence bar in microseconds

### bt_sequence_get_loop_time ()

    GstClockTime        bt_sequence_get_loop_time           (const BtSequence * const self);

Calculates the length of the song loop in microseconds. Divide it by `G_USEC_PER_SEC` to get it in milliseconds.

`self` : | the BtSequence of the song
Returns : | the length of the song loop in microseconds

### bt_sequence_limit_play_pos ()

    gulong              bt_sequence_limit_play_pos          (const BtSequence * const self,
                                                             const gulong play_pos);

Enforce the playback position to be within loop start and end or the song bounds if there is no loop.

`self` : | the sequence to trim the play position of
`play_pos` : | the time position to lock inbetween loop-boundaries
Returns : | the new `play_pos`

### bt_sequence_is_pattern_used ()

    gboolean            bt_sequence_is_pattern_used         (const BtSequence * const self,
                                                             const BtPattern * const pattern);

Checks if the `pattern` is used in the sequence.

`self` : | the sequence to check for pattern use
`pattern` : | the pattern to check for
Returns : | `TRUE` if `pattern` is used.

### bt_sequence_insert_rows ()

    void                bt_sequence_insert_rows             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const gulong rows);

Insert one empty row for given `track`.

`self` : | the sequence
`time` : | the postion to insert at
`track` : | the track
`rows` : | the number of rows to insert

Since 0.3

### bt_sequence_insert_full_rows ()

    void                bt_sequence_insert_full_rows        (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong rows);

Insert one empty row for all tracks.

`self` : | the sequence
`time` : | the postion to insert at
`rows` : | the number of rows to insert

Since 0.3

### bt_sequence_delete_rows ()

    void                bt_sequence_delete_rows             (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong track,
                                                             const gulong rows);

Delete row for given `track`.

`self` : | the sequence
`time` : | the postion to delete
`track` : | the track
`rows` : | the number of rows to remove

Since 0.3

### bt_sequence_delete_full_rows ()

    void                bt_sequence_delete_full_rows        (const BtSequence * const self,
                                                             const gulong time,
                                                             const gulong rows);

Delete row for all tracks.

`self` : | the sequence
`time` : | the postion to delete
`rows` : | the number of rows to remove

Since 0.3

### bt_sequence_update_tempo ()

    void                bt_sequence_update_tempo            (const BtSequence * const self);

Refresh sequence after tempo changes.

`self` : | the sequence

## Property Details

### The `"length"` property

      "length"                   gulong                : Read / Write

length of the sequence in timeline bars.

Allowed values: <= G_MAXLONG

### The `"loop"` property

      "loop"                     gboolean              : Read / Write

is loop activated.

Default value: FALSE

### The `"loop-end"` property

      "loop-end"                 glong                 : Read / Write

end of the repeat sequence on the timeline.

Allowed values: >= -1

Default value: -1

### The `"loop-start"` property

      "loop-start"               glong                 : Read / Write

start of the repeat sequence on the timeline.

Allowed values: >= -1

Default value: -1

### The `"song"` property

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

Set song object, the sequence belongs to.

### The `"tracks"` property

      "tracks"                   gulong                : Read / Write

number of tracks in the sequence.