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