AgsProgram: Advanced Gtk+ Sequencer Audio Reference Manual

AgsProgram

AgsProgram — Program class supporting selection and clipboard

Stability Level

Stable, unless otherwise indicated

Functions

#define	AGS_PROGRAM_GET_OBJ_MUTEX()
GRecMutex *	ags_program_get_obj_mutex ()
gboolean	ags_program_test_flags ()
void	ags_program_set_flags ()
void	ags_program_unset_flags ()
GList *	ags_program_find_port ()
GList *	ags_program_find_near_timestamp ()
GList *	ags_program_find_near_timestamp_extended ()
gint	ags_program_sort_func ()
GList *	ags_program_add ()
GList *	ags_program_remove_all_empty ()
GObject *	ags_program_get_audio ()
void	ags_program_set_audio ()
AgsTimestamp *	ags_program_get_timestamp ()
void	ags_program_set_timestamp ()
gpointer	ags_program_get_control_key ()
void	ags_program_set_control_key ()
gchar *	ags_program_get_control_name ()
void	ags_program_set_control_name ()
GObject *	ags_program_get_port ()
void	ags_program_set_port ()
GList *	ags_program_get_marker ()
void	ags_program_set_marker ()
void	ags_program_add_marker ()
void	ags_program_remove_marker ()
gboolean	ags_program_remove_marker_at_position ()
GList *	ags_program_get_selection ()
gboolean	ags_program_is_marker_selected ()
AgsMarker *	ags_program_find_point ()
GList *	ags_program_find_region ()
void	ags_program_free_selection ()
void	ags_program_free_all_selection ()
void	ags_program_add_point_to_selection ()
void	ags_program_remove_point_from_selection ()
void	ags_program_add_region_to_selection ()
void	ags_program_remove_region_from_selection ()
void	ags_program_add_all_to_selection ()
xmlNode *	ags_program_copy_selection ()
xmlNode *	ags_program_cut_selection ()
void	ags_program_insert_from_clipboard ()
void	ags_program_insert_from_clipboard_extended ()
gchar **	ags_program_get_control_name_unique ()
GList *	ags_program_find_control_name ()
guint	ags_program_get_value ()
GList *	ags_program_filter ()
AgsProgram *	ags_program_new ()

Properties

gpointer	control-key	Read / Write
char *	control-name	Read / Write
gpointer	marker	Read / Write
AgsTimestamp *	timestamp	Read / Write

Types and Values

#define	AGS_PROGRAM_DEFAULT_BPM
#define	AGS_PROGRAM_TICS_PER_BEAT
#define	AGS_PROGRAM_MINIMUM_MARKER_LENGTH
#define	AGS_PROGRAM_MAXIMUM_MARKER_LENGTH
#define	AGS_PROGRAM_DEFAULT_LENGTH
#define	AGS_PROGRAM_DEFAULT_JIFFIE
#define	AGS_PROGRAM_DEFAULT_DURATION
#define	AGS_PROGRAM_DEFAULT_OFFSET
#define	AGS_PROGRAM_DEFAULT_PRECISION
#define	AGS_PROGRAM_MAXIMUM_STEPS
#define	AGS_PROGRAM_CLIPBOARD_VERSION
#define	AGS_PROGRAM_CLIPBOARD_TYPE
#define	AGS_PROGRAM_CLIPBOARD_FORMAT
#define	AGS_PROGRAM_CLIPBOARD_LEGACY_FORMAT
enum	AgsProgramFlags

Object Hierarchy

    GFlags
    ╰── AgsProgramFlags
    GObject
    ╰── AgsProgram

Includes

#include <ags/audio/ags_program.h>

Description

AgsProgram acts as a container of AgsMarker. The timestamp property tells the engine what the first x offset of AgsMarker applies.

You can lookup AgsMarker by start x offet with ags_program_find_near_timestamp(). The next x offset is calculated as following:

next_x_offset = x_offset + relative_offset;

The relative_offset is calculated as following:

relative_offset = AGS_PROGRAM_DEFAULT_OFFSET;

Use ags_program_add_marker() to add AgsMarker to AgsProgram and ags_program_remove_marker() to remove it again.

In order to copy or cut markers you select them first by calling ags_program_add_region_to_selection().

Functions

AGS_PROGRAM_GET_OBJ_MUTEX()

#define AGS_PROGRAM_GET_OBJ_MUTEX(obj) (&(((AgsProgram *) obj)->obj_mutex))

ags_program_get_obj_mutex ()

GRecMutex *
ags_program_get_obj_mutex (AgsProgram *program);

Get object mutex.

Parameters

program

the AgsProgram

Returns

the GRecMutex to lock program .

[transfer none]

Since: 3.1.0

ags_program_test_flags ()

gboolean
ags_program_test_flags (AgsProgram *program,
                        AgsProgramFlags flags);

Test flags to be set on program .

Parameters

program	the AgsProgram
flags	the flags

Returns

TRUE if flags are set, else FALSE

Since: 5.1.0

ags_program_set_flags ()

void
ags_program_set_flags (AgsProgram *program,
                       AgsProgramFlags flags);

Set flags on program .

Parameters

program	the AgsProgram
flags	the flags

Since: 5.1.0

ags_program_unset_flags ()

void
ags_program_unset_flags (AgsProgram *program,
                         AgsProgramFlags flags);

Unset flags on program .

Parameters

program	the AgsProgram
flags	the flags

Since: 5.1.0

ags_program_find_port ()

GList *
ags_program_find_port (GList *program,
                       GObject *port);

ags_program_find_near_timestamp ()

GList *
ags_program_find_near_timestamp (GList *program,
                                 AgsTimestamp *timestamp);

Retrieve appropriate program for timestamp.

Parameters

program	the GList containing AgsProgram.	[element-type AgsAudio.Program][transfer none]
timestamp	the matching AgsTimestamp, or `NULL` to match any timestamp

Returns

Next matching GList or NULL if not found.

[element-type AgsAudio.Program][transfer none]

Since: 5.1.0

ags_program_find_near_timestamp_extended ()

GList *
ags_program_find_near_timestamp_extended
                               (GList *program,
                                gchar *control_name,
                                AgsTimestamp *timestamp);

Retrieve appropriate program for control name and timestamp.

Parameters

program	the GList containing AgsProgram.	[element-type AgsAudio.Program][transfer none]
control_name	the control name
timestamp	the matching AgsTimestamp, or `NULL` to match any timestamp

Returns

Next matching GList or NULL if not found.

[element-type AgsAudio.Program][transfer none]

Since: 5.1.0

ags_program_sort_func ()

gint
ags_program_sort_func (gconstpointer a,
                       gconstpointer b);

Compare a and b .

Parameters

a	the AgsProgram
b	another AgsProgram

Returns

0 if equal, -1 if smaller and 1 if bigger timestamp

Since: 5.1.0

ags_program_add ()

GList *
ags_program_add (GList *program,
                 AgsProgram *new_program);

Add new_program sorted to program

Parameters

program	the GList containing AgsProgram.	[element-type AgsAudio.Program][transfer none]
new_program	the AgsProgram to add

Returns

the new beginning of program .

[element-type AgsAudio.Program][transfer none]

Since: 5.1.0

ags_program_remove_all_empty ()

GList *
ags_program_remove_all_empty (GList *program);

Remove all empty program .

Parameters

program

the GList containing AgsProgram.

[element-type AgsAudio.Program][transfer none]

Returns

the new beginning of program .

[element-type AgsAudio.Program][transfer none]

Since: 5.4.1

ags_program_get_audio ()

GObject *
ags_program_get_audio (AgsProgram *program);

ags_program_set_audio ()

void
ags_program_set_audio (AgsProgram *program,
                       GObject *audio);

ags_program_get_timestamp ()

AgsTimestamp *
ags_program_get_timestamp (AgsProgram *program);

Get timestamp.

Parameters

program

the AgsProgram

Returns

the AgsTimestamp.

[transfer full]

Since: 5.1.0

ags_program_set_timestamp ()

void
ags_program_set_timestamp (AgsProgram *program,
                           AgsTimestamp *timestamp);

Set timestamp.

Parameters

program	the AgsProgram
timestamp	the AgsTimestamp

Since: 5.1.0

ags_program_get_control_key ()

gpointer
ags_program_get_control_key (AgsProgram *program);

Get control key.

Parameters

program

the AgsProgram

Returns

the control key.

[transfer full]

Since: 5.4.0

ags_program_set_control_key ()

void
ags_program_set_control_key (AgsProgram *program,
                             gpointer control_key);

Set control key.

Parameters

program	the AgsProgram
control_key	the control key

Since: 5.4.0

ags_program_get_control_name ()

gchar *
ags_program_get_control_name (AgsProgram *program);

Get control name.

Parameters

program

the AgsProgram

Returns

the control name.

[transfer full]

Since: 5.3.9

ags_program_set_control_name ()

void
ags_program_set_control_name (AgsProgram *program,
                              gchar *control_name);

Set control name.

Parameters

program	the AgsProgram
control_name	the control name

Since: 5.3.9

ags_program_get_port ()

GObject *
ags_program_get_port (AgsProgram *program);

ags_program_set_port ()

void
ags_program_set_port (AgsProgram *program,
                      GObject *port);

ags_program_get_marker ()

GList *
ags_program_get_marker (AgsProgram *program);

Get marker.

Parameters

program

the AgsProgram

Returns

the GList containig AgsMarker.

[element-type AgsAudio.Marker][transfer full]

Since: 5.1.0

ags_program_set_marker ()

void
ags_program_set_marker (AgsProgram *program,
                        GList *marker);

Set marker by replacing existing.

Parameters

program	the AgsProgram
marker	the GList containing AgsMarker.	[element-type AgsAudio.Marker][transfer full]

Since: 5.1.0

ags_program_add_marker ()

void
ags_program_add_marker (AgsProgram *program,
                        AgsMarker *marker,
                        gboolean use_selection_list);

Add marker to program .

Parameters

program	the AgsProgram
marker	the AgsMarker to add
use_selection_list	if `TRUE` add to selection, else to default program

Since: 5.1.0

ags_program_remove_marker ()

void
ags_program_remove_marker (AgsProgram *program,
                           AgsMarker *marker,
                           gboolean use_selection_list);

Removes marker from program .

Parameters

program	the AgsProgram
marker	the AgsMarker to remove
use_selection_list	if `TRUE` remove from selection, else from default program

Since: 5.1.0

ags_program_remove_marker_at_position ()

gboolean
ags_program_remove_marker_at_position (AgsProgram *program,
                                       guint x);

Removes one AgsMarker of program.

Parameters

program	the AgsProgram
x	x offset

Returns

TRUE if successfully removed marker, else FALSE

Since: 5.1.0

ags_program_get_selection ()

GList *
ags_program_get_selection (AgsProgram *program);

Retrieve selection.

Parameters

program

the AgsProgram

Returns

the selection.

[element-type AgsAudio.Marker][transfer none]

Since: 5.1.0

ags_program_is_marker_selected ()

gboolean
ags_program_is_marker_selected (AgsProgram *program,
                                AgsMarker *marker);

Check selection for marker.

Parameters

program	the AgsProgram
marker	the AgsMarker to check for

Returns

TRUE if selected otherwise FALSE

Since: 5.1.0

ags_program_find_point ()

AgsMarker *
ags_program_find_point (AgsProgram *program,
                        guint x,
                        gboolean use_selection_list);

Find markers by offset.

Parameters

program	the AgsProgram
x	offset
use_selection_list	if `TRUE` selection is searched

Returns

the matching marker as AgsMarker.

[transfer none]

Since: 5.1.0

ags_program_find_region ()

GList *
ags_program_find_region (AgsProgram *program,
                         guint x0,
                         guint x1,
                         gboolean use_selection_list);

Find markers by offset and region.

Parameters

program	the AgsProgram
x0	x start offset
x1	x end offset
use_selection_list	if `TRUE` selection is searched

Returns

the matching markers as GList.

[element-type AgsAudio.Marker][transfer container]

Since: 5.1.0

ags_program_free_selection ()

void
ags_program_free_selection (AgsProgram *program);

Clear selection.

Parameters

program

the AgsProgram

Since: 5.1.0

ags_program_free_all_selection ()

void
ags_program_free_all_selection (GList *program);

Clear all selection of program .

Parameters

program

the GList containing AgsProgram.

[element-type AgsAudio.Program][transfer none]

Since: 3.14.10

ags_program_add_point_to_selection ()

void
ags_program_add_point_to_selection (AgsProgram *program,
                                    guint x,
                                    gboolean replace_current_selection);

ags_program_remove_point_from_selection ()

void
ags_program_remove_point_from_selection
                               (AgsProgram *program,
                                guint x);

ags_program_add_region_to_selection ()

void
ags_program_add_region_to_selection (AgsProgram *program,
                                     guint x0,
                                     guint x1,
                                     gboolean replace_current_selection);

Add marker within region to selection.

Parameters

program	the AgsProgram
x0	x start offset
x1	x end offset
replace_current_selection	if `TRUE` selection is replaced

Since: 5.1.0

ags_program_remove_region_from_selection ()

void
ags_program_remove_region_from_selection
                               (AgsProgram *program,
                                guint x0,
                                guint x1);

Remove markers within region of selection.

Parameters

program	the AgsProgram
x0	x start offset
x1	x end offset

Since: 5.1.0

ags_program_add_all_to_selection ()

void
ags_program_add_all_to_selection (AgsProgram *program);

Select all marker to selection.

Parameters

program

the AgsProgram

Since: 5.1.0

ags_program_copy_selection ()

xmlNode *
ags_program_copy_selection (AgsProgram *program);

Copy selection to clipboard.

Parameters

program

the AgsProgram

Returns

the selection as XML.

[transfer none]

Since: 5.1.0

ags_program_cut_selection ()

xmlNode *
ags_program_cut_selection (AgsProgram *program);

Cut selection to clipboard.

Parameters

program

the AgsProgram

Returns

the selection as xmlNode.

[transfer none]

Since: 5.1.0

ags_program_insert_from_clipboard ()

void
ags_program_insert_from_clipboard (AgsProgram *program,
                                   xmlNode *program_node,
                                   gboolean reset_x_offset,
                                   guint x_offset);

Paste previously copied markers.

Parameters

program	the AgsProgram
program_node	the clipboard XML data
reset_x_offset	if `TRUE` `x_offset` used as cursor
x_offset	region start cursor offset

Since: 5.1.0

ags_program_insert_from_clipboard_extended ()

void
ags_program_insert_from_clipboard_extended
                               (AgsProgram *program,
                                xmlNode *program_node,
                                gboolean reset_x_offset,
                                guint x_offset,
                                gboolean do_replace);

Paste previously copied markers.

Parameters

program	the AgsProgram
program_node	the clipboard XML data
reset_x_offset	if `TRUE` `x_offset` used as cursor
x_offset	region start cursor offset
do_replace	if `TRUE` current data is replaced, otherwise combined

Since: 5.1.0

ags_program_get_control_name_unique ()

gchar **
ags_program_get_control_name_unique (GList *program);

Retrieve program port control_name.

Parameters

program

the GList containing AgsProgram.

[element-type AgsAudio.Program][transfer none]

Returns

a NULL terminated string array.

[element-type utf8][array zero-terminated=1][transfer full]

Since: 5.1.0

ags_program_find_control_name ()

GList *
ags_program_find_control_name (GList *program,
                               gchar *control_name);

Find port control_name.

Parameters

program	the GList containing AgsProgram.	[element-type AgsAudio.Program][transfer none]
control_name	the string control_name to find

Returns

Next matching GList.

[element-type AgsAudio.Program][transfer none]

Since: 5.1.0

ags_program_get_value ()

guint
ags_program_get_value (AgsProgram *program,
                       guint x,
                       guint x_end,
                       gboolean use_prev_on_failure,
                       GValue *value);

ags_program_filter ()

GList *
ags_program_filter (GList *program,
                    gchar *specifier);

Filter program by specifier .

Parameters

program	the GList containing AgsProgram.	[element-type AgsAudio.Program][transfer none]
specifier	the string specifier to find

Returns

the copied and filtered list.

[element-type AgsAudio.Program][transfer full]

Since: 5.4.0

ags_program_new ()

AgsProgram *
ags_program_new (gchar *control_name);

Creates a new instance of AgsProgram.

Parameters

control_name

the control name

Returns

a new AgsProgram

Since: 5.1.0

Types and Values

AGS_PROGRAM_DEFAULT_BPM

#define AGS_PROGRAM_DEFAULT_BPM (120.0)

AGS_PROGRAM_TICS_PER_BEAT

#define AGS_PROGRAM_TICS_PER_BEAT (1.0)

AGS_PROGRAM_MINIMUM_MARKER_LENGTH

#define AGS_PROGRAM_MINIMUM_MARKER_LENGTH (1.0 / 16.0 / 64.0)

AGS_PROGRAM_MAXIMUM_MARKER_LENGTH

#define AGS_PROGRAM_MAXIMUM_MARKER_LENGTH (16.0)

AGS_PROGRAM_DEFAULT_LENGTH

#define AGS_PROGRAM_DEFAULT_LENGTH (64 * 16 * 16 * 1200 / AGS_PROGRAM_TICS_PER_BEAT)

AGS_PROGRAM_DEFAULT_JIFFIE

#define AGS_PROGRAM_DEFAULT_JIFFIE (60.0 / AGS_PROGRAM_DEFAULT_BPM / AGS_PROGRAM_TICS_PER_BEAT)

AGS_PROGRAM_DEFAULT_DURATION

#define AGS_PROGRAM_DEFAULT_DURATION (AGS_PROGRAM_DEFAULT_LENGTH * AGS_PROGRAM_DEFAULT_JIFFIE * AGS_USEC_PER_SEC)

AGS_PROGRAM_DEFAULT_OFFSET

#define AGS_PROGRAM_DEFAULT_OFFSET (64 * (1 / AGS_PROGRAM_MINIMUM_MARKER_LENGTH))

AGS_PROGRAM_DEFAULT_PRECISION

#define AGS_PROGRAM_DEFAULT_PRECISION (8)

AGS_PROGRAM_MAXIMUM_STEPS

#define AGS_PROGRAM_MAXIMUM_STEPS (128)

AGS_PROGRAM_CLIPBOARD_VERSION

#define AGS_PROGRAM_CLIPBOARD_VERSION "5.1.0"

AGS_PROGRAM_CLIPBOARD_TYPE

#define AGS_PROGRAM_CLIPBOARD_TYPE "AgsProgramClipboardXml"

AGS_PROGRAM_CLIPBOARD_FORMAT

#define AGS_PROGRAM_CLIPBOARD_FORMAT "AgsProgramNativeScale"

AGS_PROGRAM_CLIPBOARD_LEGACY_FORMAT

#define AGS_PROGRAM_CLIPBOARD_LEGACY_FORMAT "AgsProgramNativePiano"

enum AgsProgramFlags

Enum values to control the behavior or indicate internal state of AgsProgram by enable/disable as flags.

Members

AGS_PROGRAM_BYPASS

ignore any program data

Property Details

The `“control-key”` property

  “control-key”              gpointer

The effect's assigned control key.

Owner: AgsProgram

Flags: Read / Write

Since: 5.4.0

The `“control-name”` property

  “control-name”             char *

The program's control-name.

Owner: AgsProgram

Flags: Read / Write

Default value: NULL

Since: 5.1.0

The `“marker”` property

  “marker”                   gpointer

The assigned AgsMarker

[transfer full]

Owner: AgsProgram

Flags: Read / Write

Since: 5.1.0

The `“timestamp”` property

  “timestamp”                AgsTimestamp *

The program's timestamp.

Owner: AgsProgram

Flags: Read / Write

Since: 5.1.0