BtSequence

BtSequence — class for the event timeline of a BtSong instance

Functions

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