BtSequence: Buzztrax Bt-Core Reference Manual

## BtSequence BtSequence — class for the event timeline of a BtSong instance |

## Functions

gboolean | bt_sequence_add_track ()
void | bt_sequence_delete_full_rows ()
void | bt_sequence_delete_rows ()
gchar * | bt_sequence_get_label ()
gulong | bt_sequence_get_loop_length ()
BtMachine * | bt_sequence_get_machine ()
BtCmdPattern * | bt_sequence_get_pattern ()
glong | bt_sequence_get_tick_by_pattern ()
glong | bt_sequence_get_track_by_machine ()
void | bt_sequence_insert_full_rows ()
void | bt_sequence_insert_rows ()
gboolean | bt_sequence_is_pattern_used ()
gulong | bt_sequence_limit_play_pos ()
gboolean | bt_sequence_move_track_left ()
gboolean | bt_sequence_move_track_right ()
BtSequence * | bt_sequence_new ()
gboolean | bt_sequence_remove_track_by_ix ()
gboolean | bt_sequence_remove_track_by_machine ()
void | bt_sequence_set_label ()
void | bt_sequence_set_pattern ()
gboolean | bt_sequence_set_pattern_quick ()

## Properties

gulong | length | Read / Write
gboolean | loop | Read / Write
glong | loop-end | Read / Write
glong | loop-start | Read / Write
gpointer | properties | Read
BtSong * | song | Read / Write / Construct Only
gpointer | toc | Read
gulong | tracks | Read / Write

## Signals

void | pattern-added | No Hooks
void | pattern-removed | No Hooks
void | rows-changed | No Hooks
void | track-added | No Hooks
void | track-removed | No Hooks

## Types and Values

struct | BtSequence

## Object Hierarchy

        GObject
        ╰── BtSequence

## Implemented Interfaces

BtSequence implements BtPersistence.

## Includes

    #include <libbtcore/core.h>

## Description

A sequence holds grid of BtCmdPatterns, with labels on the time axis and BtMachine instances on the track axis. It tracks first and last use of patterns and provides two signals for notification - “pattern-added” and “pattern-removed”. The labels are exported as a GstToc, readable through the “toc” property.

It supports looping a section of the sequence (see “loop”, “loop-start”, “loop-end”).

The sequence is not aware of timing related information; for this take a look at BtSongInfo.

## Functions

### bt_sequence_add_track ()

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

Adds a new track with the `machine` at `ix` or the end.

#### Parameters

self | the BtSequence that holds the tracks |
machine | the BtMachine |
ix | position to add the track at, use -1 to append |

#### Returns

`TRUE` for success

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

#### Parameters

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

Since: 0.3

### bt_sequence_delete_rows ()

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

Delete row for given `track` .

#### Parameters

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

Since: 0.3

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

#### Parameters

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

    gulong
    bt_sequence_get_loop_length (const BtSequence * const self);

Calculates the length of the song loop in ticks.

#### Parameters

self | the BtSequence of the song |

#### Returns

the length of the song loop in ticks

### bt_sequence_get_machine ()

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

Fetches the BtMachine for the given `track` .

#### Parameters

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. Unref when done.

[transfer full]

### bt_sequence_get_pattern ()

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

Fetches the pattern for the given `time` and `track` position.

#### Parameters

self | the BtSequence that holds the patterns |
time | the requested time position |
track | the requested track index |

#### Returns

a reference to the BtCmdPattern or `NULL` when empty. Unref when done.

[transfer full]

### bt_sequence_get_tick_by_pattern ()

    glong
    bt_sequence_get_tick_by_pattern (const BtSequence * const self,
                                     gulong track,
                                     const BtCmdPattern * const pattern,
                                     gulong tick);

Gets the next tick position >= `tick` this `pattern` is on.

#### Parameters

self | the sequence to search in |
track | the track to search in |
pattern | the pattern to find the next track for |
tick | the tick position to start the search from |

#### Returns

the tick position or -1 if there is no further tick for this `pattern` .

Since: 0.6

### bt_sequence_get_track_by_machine ()

    glong
    bt_sequence_get_track_by_machine (const BtSequence * const self,
                                      const BtMachine * const machine,
                                      gulong track);

Gets the next track >= `track` this `machine` is on.

#### Parameters

self | the sequence to search in |
machine | the machine to find the next track for |
track | the track to start the search from |

#### Returns

the track-index or -1 if there is no further track for this `machine` .

Since: 0.6

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

#### Parameters

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

Since: 0.3

### bt_sequence_insert_rows ()

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

Insert one empty row for given `track` .

#### Parameters

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

Since: 0.3

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

#### Parameters

self | the sequence to check for pattern use |
pattern | the pattern to check for |

#### Returns

`TRUE` if `pattern` is used.

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

#### Parameters

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

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

Move the selected track on column left.

#### Parameters

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.

#### Parameters

self | the BtSequence that holds the tracks |
track | the track to move |

#### Returns

`TRUE` for success

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

#### Parameters

song | the song the new instance belongs to |

#### Returns

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

### bt_sequence_remove_track_by_ix ()

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

Removes the specified `track` .

#### Parameters

self | the BtSequence that holds the tracks |
ix | 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` .

#### Parameters

self | the BtSequence that holds the tracks |
machine | the BtMachine |

#### Returns

`TRUE` for success

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

#### Parameters

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

### bt_sequence_set_pattern ()

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

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

#### Parameters

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

### bt_sequence_set_pattern_quick ()

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

A quick version of `bt_sequence_set_pattern()` that does not check parameters. Useful when doing mass updates.

#### Parameters

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

#### Returns

`TRUE` if a change has been made.

Since: 0.5

## Types and Values

### struct BtSequence

    struct BtSequence;

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

## Property Details

### The `“length”` property

      “length”                   gulong

length of the sequence in timeline bars.

Flags: Read / Write

Allowed values: <= G_MAXINT64

### The `“loop”` property

      “loop”                     gboolean

is loop activated.

Flags: Read / Write

Default value: FALSE

### The `“loop-end”` property

      “loop-end”                 glong

end of the repeat sequence on the timeline.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“loop-start”` property

      “loop-start”               glong

start of the repeat sequence on the timeline.

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“properties”` property

      “properties”               gpointer

hashtable of sequence properties.

Flags: Read

### The `“song”` property

      “song”                     BtSong *

Set song object, the sequence belongs to.

Flags: Read / Write / Construct Only

### The `“toc”` property

      “toc”                      gpointer

TOC containing the labels.

Flags: Read

### The `“tracks”` property

      “tracks”                   gulong

number of tracks in the sequence.

Flags: Read / Write

## Signal Details

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

    void
    user_function (BtSequence *self,
                   BtPattern  *pattern,
                   gpointer    user_data)

A pattern has been used in the sequence for the first time.

#### Parameters

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

Flags: No Hooks

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

    void
    user_function (BtSequence *self,
                   BtPattern  *pattern,
                   gpointer    user_data)

The last occurance of pattern has been removed from the sequence.

#### Parameters

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

Flags: No Hooks

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

    void
    user_function (BtSequence *self,
                   gulong      begin,
                   gulong      end,
                   gpointer    user_data)

The content of the given rows in the sequence has changed.

#### Parameters

self | the sequence object that emitted the signal |
begin | start row that changed |
end | last row that changed |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 0.6

### The `“track-added”` signal

    void
    user_function (BtSequence *self,
                   BtMachine  *machine,
                   gulong      track,
                   gpointer    user_data)

A new track for `machine` has been added with the `track` index.

#### Parameters

self | the sequence object that emitted the signal |
machine | the machine for the track |
track | the track index |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 0.6

### The `“track-removed”` signal

    void
    user_function (BtSequence *self,
                   BtMachine  *machine,
                   gulong      track,
                   gpointer    user_data)

A track for `machine` has been removed at the `track` index.

#### Parameters

self | the sequence object that emitted the signal |
machine | the machine for the track |
track | the track index |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 0.6