## AgsNotation

AgsNotation — Notation class supporting selection and clipboard

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | AGS_NOTATION_GET_OBJ_MUTEX()
GRecMutex * | ags_notation_get_obj_mutex ()
gboolean | ags_notation_test_flags ()
void | ags_notation_set_flags ()
void | ags_notation_unset_flags ()
GList * | ags_notation_find_near_timestamp ()
GList * | ags_notation_add ()
gint | ags_notation_sort_func ()
GObject * | ags_notation_get_audio ()
void | ags_notation_set_audio ()
guint | ags_notation_get_audio_channel ()
void | ags_notation_set_audio_channel ()
gboolean | ags_notation_get_is_minor ()
void | ags_notation_set_is_minor ()
guint | ags_notation_get_sharp_flats ()
void | ags_notation_set_sharp_flats ()
AgsTimestamp * | ags_notation_get_timestamp ()
void | ags_notation_set_timestamp ()
GList * | ags_notation_get_note ()
void | ags_notation_set_note ()
void | ags_notation_add_note ()
void | ags_notation_remove_note ()
gboolean | ags_notation_remove_note_at_position ()
GList * | ags_notation_get_selection ()
gboolean | ags_notation_is_note_selected ()
AgsNote * | ags_notation_find_point ()
AgsNote * | ags_notation_find_exact_256th_point ()
GList * | ags_notation_find_region ()
GList * | ags_notation_find_offset ()
GList * | ags_notation_find_note_256th_range ()
void | ags_notation_free_selection ()
void | ags_notation_free_all_selection ()
void | ags_notation_add_point_to_selection ()
void | ags_notation_remove_point_from_selection ()
void | ags_notation_add_region_to_selection ()
void | ags_notation_remove_region_from_selection ()
void | ags_notation_add_all_to_selection ()
xmlNode * | ags_notation_copy_selection ()
xmlNode * | ags_notation_cut_selection ()
void | ags_notation_insert_from_clipboard ()
void | ags_notation_insert_from_clipboard_extended ()
guchar * | ags_notation_to_raw_midi ()
AgsNotation * | ags_notation_from_raw_midi ()
AgsNotation * | ags_notation_new ()

## Properties

AgsAudio * | audio | Read / Write
guint | audio-channel | Read / Write
gpointer | note | Read / Write
AgsTimestamp * | timestamp | Read / Write

## Types and Values

#define | AGS_NOTATION_DEFAULT_BPM
#define | AGS_NOTATION_TICS_PER_BEAT
#define | AGS_NOTATION_MINIMUM_NOTE_LENGTH
#define | AGS_NOTATION_MAXIMUM_NOTE_LENGTH
#define | AGS_NOTATION_DEFAULT_LENGTH
#define | AGS_NOTATION_DEFAULT_JIFFIE
#define | AGS_NOTATION_DEFAULT_DURATION
#define | AGS_NOTATION_DEFAULT_OFFSET
#define | AGS_NOTATION_DEFAULT_END
#define | AGS_NOTATION_DEFAULT_DIVISION
#define | AGS_NOTATION_CLIPBOARD_VERSION
#define | AGS_NOTATION_CLIPBOARD_TYPE
#define | AGS_NOTATION_CLIPBOARD_FORMAT
enum | AgsNotationFlags

## Object Hierarchy

        GFlags
        ╰── AgsNotationFlags
        GObject
        ╰── AgsNotation

## Includes

    #include <ags/audio/ags_notation.h>

## Description

AgsNotation acts as a container of AgsNote. The `timestamp` property tells the engine what the first x offset of AgsNote applies.

You can lookup AgsNotation by start x offset with `ags_notation_find_near_timestamp()`. The next x offset is calculated as following:

next_x_offset = x_offset + AGS_NOTATION_DEFAULT_OFFSET;

Use `ags_notation_add_note()` to add AgsNote to AgsNotation and `ags_notation_remove_note()` to remove it again.

In order to copy or cut notes you select them first by calling `ags_notation_add_region_to_selection()`.

## Functions

### AGS_NOTATION_GET_OBJ_MUTEX()

    #define AGS_NOTATION_GET_OBJ_MUTEX(obj) (&(((AgsNotation *) obj)->obj_mutex))

### ags_notation_get_obj_mutex ()

    GRecMutex *
    ags_notation_get_obj_mutex (AgsNotation *notation);

Get object mutex.

#### Parameters

notation | the AgsNotation |

#### Returns

the GRecMutex to lock `notation`

Since: 3.1.0

### ags_notation_test_flags ()

    gboolean
    ags_notation_test_flags (AgsNotation *notation,
                             AgsNotationFlags flags);

Test `flags` to be set on `notation` .

#### Parameters

notation | the AgsNotation |
flags | the flags |

#### Returns

`TRUE` if flags are set, else `FALSE`

Since: 3.0.0

### ags_notation_set_flags ()

    void
    ags_notation_set_flags (AgsNotation *notation,
                            AgsNotationFlags flags);

Set `flags` on `notation` .

#### Parameters

notation | the AgsNotation |
flags | the flags |

Since: 3.0.0

### ags_notation_unset_flags ()

    void
    ags_notation_unset_flags (AgsNotation *notation,
                              AgsNotationFlags flags);

Unset `flags` on `notation` .

#### Parameters

notation | the AgsNotation |
flags | the flags |

Since: 3.0.0

### ags_notation_find_near_timestamp ()

    GList *
    ags_notation_find_near_timestamp (GList *notation,
                                      guint audio_channel,
                                      AgsTimestamp *timestamp);

Retrieve appropriate notation for timestamp.

#### Parameters

notation | the GList containing AgsNotation. | [element-type AgsAudio.Notation][transfer none]
audio_channel | the matching audio channel |
timestamp | the matching timestamp, or `NULL` to match any timestamp. | [allow-none]

#### Returns

Next matching GList or `NULL` if not found.

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

Since: 3.0.0

### ags_notation_add ()

    GList *
    ags_notation_add (GList *notation,
                      AgsNotation *new_notation);

Add `new_notation` sorted to `notation`

#### Parameters

notation | the GList containing AgsNotation. | [element-type AgsAudio.Notation][transfer none]
new_notation | the AgsNotation to add |

#### Returns

the new beginning of `notation` .

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

Since: 3.0.0

### ags_notation_sort_func ()

    gint
    ags_notation_sort_func (gconstpointer a,
                            gconstpointer b);

Compare `a` and `b` .

#### Parameters

a | the AgsNotation |
b | another AgsNotation |

#### Returns

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

Since: 3.0.0

### ags_notation_get_audio ()

    GObject *
    ags_notation_get_audio (AgsNotation *notation);

Get audio.

#### Parameters

notation | the AgsNotation |

#### Returns

the AgsAudio.

[transfer full]

Since: 3.1.0

### ags_notation_set_audio ()

    void
    ags_notation_set_audio (AgsNotation *notation,
                            GObject *audio);

Set audio.

#### Parameters

notation | the AgsNotation |
audio | the AgsAudio |

Since: 3.1.0

### ags_notation_get_audio_channel ()

    guint
    ags_notation_get_audio_channel (AgsNotation *notation);

Gets audio channel.

#### Parameters

notation | the AgsNotation |

#### Returns

the audio channel

Since: 3.1.0

### ags_notation_set_audio_channel ()

    void
    ags_notation_set_audio_channel (AgsNotation *notation,
                                    guint audio_channel);

Sets audio channel.

#### Parameters

notation | the AgsNotation |
audio_channel | the audio channel |

Since: 3.1.0

### ags_notation_get_is_minor ()

    gboolean
    ags_notation_get_is_minor (AgsNotation *notation);

Gets is minor.

#### Parameters

notation | the AgsNotation |

#### Returns

is minor

Since: 3.1.0

### ags_notation_set_is_minor ()

    void
    ags_notation_set_is_minor (AgsNotation *notation,
                               gboolean is_minor);

Sets is minor.

#### Parameters

notation | the AgsNotation |
is_minor | is minor |

Since: 3.1.0

### ags_notation_get_sharp_flats ()

    guint
    ags_notation_get_sharp_flats (AgsNotation *notation);

Gets sharp flats.

#### Parameters

notation | the AgsNotation |

#### Returns

the sharp flats

Since: 3.1.0

### ags_notation_set_sharp_flats ()

    void
    ags_notation_set_sharp_flats (AgsNotation *notation,
                                  guint sharp_flats);

Sets sharp flats.

#### Parameters

notation | the AgsNotation |
sharp_flats | the sharp flats |

Since: 3.1.0

### ags_notation_get_timestamp ()

    AgsTimestamp *
    ags_notation_get_timestamp (AgsNotation *notation);

Get timestamp.

#### Parameters

notation | the AgsNotation |

#### Returns

the AgsTimestamp.

[transfer full]

Since: 3.1.0

### ags_notation_set_timestamp ()

    void
    ags_notation_set_timestamp (AgsNotation *notation,
                                AgsTimestamp *timestamp);

Set timestamp.

#### Parameters

notation | the AgsNotation |
timestamp | the AgsTimestamp |

Since: 3.1.0

### ags_notation_get_note ()

    GList *
    ags_notation_get_note (AgsNotation *notation);

Get note.

#### Parameters

notation | the AgsNotation |

#### Returns

the GList containig AgsNote.

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

Since: 3.1.0

### ags_notation_set_note ()

    void
    ags_notation_set_note (AgsNotation *notation,
                           GList *note);

Set note by replacing existing.

#### Parameters

notation | the AgsNotation |
note | the GList containing AgsNote. | [element-type AgsAudio.Note][transfer full]

Since: 3.1.0

### ags_notation_add_note ()

    void
    ags_notation_add_note (AgsNotation *notation,
                           AgsNote *note,
                           gboolean use_selection_list);

Adds `note` to `notation` .

#### Parameters

notation | the AgsNotation |
note | the AgsNote to add |
use_selection_list | if `TRUE` add to selection, else to default notation |

Since: 3.0.0

### ags_notation_remove_note ()

    void
    ags_notation_remove_note (AgsNotation *notation,
                              AgsNote *note,
                              gboolean use_selection_list);

Removes `note` from `notation` .

#### Parameters

notation | the AgsNotation |
note | the AgsNote to remove |
use_selection_list | if `TRUE` remove from selection, else from default notation |

Since: 3.0.0

### ags_notation_remove_note_at_position ()

    gboolean
    ags_notation_remove_note_at_position (AgsNotation *notation,
                                          guint x,
                                          guint y);

Removes one AgsNote of notation.

#### Parameters

notation | the AgsNotation |
x | offset |
y | note |

#### Returns

`TRUE` if successfully removed note.

Since: 3.0.0

### ags_notation_get_selection ()

    GList *
    ags_notation_get_selection (AgsNotation *notation);

Retrieve selection.

#### Parameters

notation | the AgsNotation |

#### Returns

the selection.

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

Since: 3.0.0

### ags_notation_is_note_selected ()

    gboolean
    ags_notation_is_note_selected (AgsNotation *notation,
                                   AgsNote *note);

Check selection for note.

#### Parameters

notation | the AgsNotation |
note | the AgsNote to check for |

#### Returns

`TRUE` if selected otherwise `FALSE`

Since: 3.0.0

### ags_notation_find_point ()

    AgsNote *
    ags_notation_find_point (AgsNotation *notation,
                             guint x,
                             guint y,
                             gboolean use_selection_list);

Find note by offset and tone.

#### Parameters

notation | the AgsNotation |
x | offset |
y | note |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the matching note.

[transfer none]

Since: 3.0.0

### ags_notation_find_exact_256th_point ()

    AgsNote *
    ags_notation_find_exact_256th_point (AgsNotation *notation,
                                         guint x_256th,
                                         guint y,
                                         gboolean use_selection_list);

### ags_notation_find_region ()

    GList *
    ags_notation_find_region (AgsNotation *notation,
                              guint x0,
                              guint y0,
                              guint x1,
                              guint y1,
                              gboolean use_selection_list);

Find note by offset and tone region.

#### Parameters

notation | the AgsNotation |
x0 | start offset |
y0 | start tone |
x1 | end offset |
y1 | end tone |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the matching notes as GList.

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

Since: 3.0.0

### ags_notation_find_offset ()

    GList *
    ags_notation_find_offset (AgsNotation *notation,
                              guint x,
                              gboolean use_selection_list);

Find all notes by offset `x` .

#### Parameters

notation | the AgsNotation |
x | offset |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the GList containing matching AgsNote.

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

Since: 3.0.0

### ags_notation_find_note_256th_range ()

    GList *
    ags_notation_find_note_256th_range (AgsNotation *notation,
                                        guint x_256th_lower,
                                        guint x_256th_upper,
                                        gboolean use_selection_list);

Find all notes by range `x_256th_lower` to `x_256th_upper` .

#### Parameters

notation | the AgsNotation |
x_256th_lower | offset lower |
x_256th_upper | offset upper |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the GList containing matching AgsNote.

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

Since: 6.9.0

### ags_notation_free_selection ()

    void
    ags_notation_free_selection (AgsNotation *notation);

Clear selection.

#### Parameters

notation | the AgsNotation |

Since: 3.0.0

### ags_notation_free_all_selection ()

    void
    ags_notation_free_all_selection (GList *notation);

Clear all selection of `notation` .

#### Parameters

notation | the GList containing AgsNotation. | [element-type AgsAudio.Notation]

Since: 3.14.10

### ags_notation_add_point_to_selection ()

    void
    ags_notation_add_point_to_selection (AgsNotation *notation,
                                         guint x,
                                         guint y,
                                         gboolean replace_current_selection);

Select notes at position.

#### Parameters

notation | the AgsNotation |
x | x offset |
y | y note tone |
replace_current_selection | if `TRUE` selection is replaced |

Since: 3.0.0

### ags_notation_remove_point_from_selection ()

    void
    ags_notation_remove_point_from_selection
                                   (AgsNotation *notation,
                                    guint x,
                                    guint y);

Remove notes at position of selection.

#### Parameters

notation | the AgsNotation |
x | x offset |
y | y note tone |

Since: 3.0.0

### ags_notation_add_region_to_selection ()

    void
    ags_notation_add_region_to_selection (AgsNotation *notation,
                                          guint x0,
                                          guint y0,
                                          guint x1,
                                          guint y1,
                                          gboolean replace_current_selection);

Add note within region to selection.

#### Parameters

notation | the AgsNotation |
x0 | x start offset |
y0 | y start tone |
x1 | x end offset |
y1 | y end tone |
replace_current_selection | if `TRUE` selection is replaced |

Since: 3.0.0

### ags_notation_remove_region_from_selection ()

    void
    ags_notation_remove_region_from_selection
                                   (AgsNotation *notation,
                                    guint x0,
                                    guint y0,
                                    guint x1,
                                    guint y1);

Remove note within region of selection.

#### Parameters

notation | the AgsNotation |
x0 | x start offset |
y0 | y start tone |
x1 | x end offset |
y1 | y end tone |

Since: 3.0.0

### ags_notation_add_all_to_selection ()

    void
    ags_notation_add_all_to_selection (AgsNotation *notation);

Add all note to selection.

#### Parameters

notation | the AgsNotation |

Since: 3.0.0

### ags_notation_copy_selection ()

    xmlNode *
    ags_notation_copy_selection (AgsNotation *notation);

Copy selection to clipboard.

#### Parameters

notation | the AgsNotation |

#### Returns

the selection as XML.

[transfer none]

Since: 3.0.0

### ags_notation_cut_selection ()

    xmlNode *
    ags_notation_cut_selection (AgsNotation *notation);

Cut selection to clipboard.

#### Parameters

notation | the AgsNotation |

#### Returns

the selection as xmlNode.

[transfer none]

Since: 3.0.0

### ags_notation_insert_from_clipboard ()

    void
    ags_notation_insert_from_clipboard (AgsNotation *notation,
                                        xmlNode *notation_node,
                                        gboolean reset_x_offset,
                                        guint x_offset,
                                        gboolean reset_y_offset,
                                        guint y_offset);

Paste previously copied notes.

#### Parameters

notation | the AgsNotation |
notation_node | the clipboard XML data |
reset_x_offset | if `TRUE` `x_offset` used as cursor |
x_offset | region start cursor offset |
reset_y_offset | if `TRUE` `y_offset` used as cursor |
y_offset | region start cursor tone |

Since: 3.0.0

### ags_notation_insert_from_clipboard_extended ()

    void
    ags_notation_insert_from_clipboard_extended
                                   (AgsNotation *notation,
                                    xmlNode *notation_node,
                                    gboolean reset_x_offset,
                                    guint x_offset,
                                    gboolean reset_y_offset,
                                    guint y_offset,
                                    gboolean match_channel,
                                    gboolean no_duplicates);

Paste previously copied notes.

#### Parameters

notation | the AgsNotation |
notation_node | the clipboard XML data |
reset_x_offset | if `TRUE` `x_offset` used as cursor |
x_offset | region start cursor offset |
reset_y_offset | if `TRUE` `y_offset` used as cursor |
y_offset | region start cursor tone |
match_channel | only paste if channel matches |
no_duplicates | only paste if current note doesn't exist |

Since: 3.0.0

### ags_notation_to_raw_midi ()

    guchar *
    ags_notation_to_raw_midi (AgsNotation *notation,
                              gdouble bpm,
                              gdouble delay_factor,
                              glong nn,
                              glong dd,
                              glong cc,
                              glong bb,
                              glong tempo,
                              guint *buffer_length);

Convert `notation` to raw-midi.

#### Parameters

notation | the AgsNotation |
bpm | the source bpm |
delay_factor | the source delay factor |
nn | numerator |
dd | denominator |
cc | clocks |
bb | beats |
tempo | tempo |
buffer_length | the return location of buffer length |

#### Returns

the raw-midi buffer

Since: 3.0.0

### ags_notation_from_raw_midi ()

    AgsNotation *
    ags_notation_from_raw_midi (guchar *raw_midi,
                                glong nn,
                                glong dd,
                                glong cc,
                                glong bb,
                                glong tempo,
                                gdouble bpm,
                                gdouble delay_factor,
                                guint buffer_length);

Parse `raw_midi` data and convert to AgsNotation.

#### Parameters

raw_midi | the data array |
nn | numerator |
dd | denominator |
cc | clocks |
bb | beats |
tempo | tempo |
bpm | the bpm to use |
delay_factor | the segmentation delay factor |
buffer_length | the buffer length |

#### Returns

the AgsNotation.

[transfer full]

Since: 3.0.0

### ags_notation_new ()

    AgsNotation *
    ags_notation_new (GObject *audio,
                      guint audio_channel);

Creates a new instance of AgsNotation.

#### Parameters

audio | the assigned AgsAudio |
audio_channel | the audio channel to apply |

#### Returns

the new AgsNotation

Since: 3.0.0

## Types and Values

### AGS_NOTATION_DEFAULT_BPM

    #define AGS_NOTATION_DEFAULT_BPM (120.0)

### AGS_NOTATION_TICS_PER_BEAT

    #define AGS_NOTATION_TICS_PER_BEAT (1.0)

### AGS_NOTATION_MINIMUM_NOTE_LENGTH

    #define AGS_NOTATION_MINIMUM_NOTE_LENGTH (1.0 / 16.0)

### AGS_NOTATION_MAXIMUM_NOTE_LENGTH

    #define AGS_NOTATION_MAXIMUM_NOTE_LENGTH (16.0)

### AGS_NOTATION_DEFAULT_LENGTH

    #define AGS_NOTATION_DEFAULT_LENGTH (16.0 * 16.0 * 1200.0 / AGS_NOTATION_TICS_PER_BEAT)

### AGS_NOTATION_DEFAULT_JIFFIE

    #define AGS_NOTATION_DEFAULT_JIFFIE (60.0 / AGS_NOTATION_DEFAULT_BPM / AGS_NOTATION_TICS_PER_BEAT)

### AGS_NOTATION_DEFAULT_DURATION

    #define AGS_NOTATION_DEFAULT_DURATION (AGS_NOTATION_DEFAULT_LENGTH * AGS_NOTATION_DEFAULT_JIFFIE * AGS_USEC_PER_SEC)

### AGS_NOTATION_DEFAULT_OFFSET

    #define AGS_NOTATION_DEFAULT_OFFSET (64.0 * (1.0 / AGS_NOTATION_MINIMUM_NOTE_LENGTH))

### AGS_NOTATION_DEFAULT_END

    #define AGS_NOTATION_DEFAULT_END (64 * 64 * 1200)

### AGS_NOTATION_DEFAULT_DIVISION

    #define AGS_NOTATION_DEFAULT_DIVISION (96)

### AGS_NOTATION_CLIPBOARD_VERSION

    #define AGS_NOTATION_CLIPBOARD_VERSION "6.1.0"

### AGS_NOTATION_CLIPBOARD_TYPE

    #define AGS_NOTATION_CLIPBOARD_TYPE "AgsNotationClipboardXml"

### AGS_NOTATION_CLIPBOARD_FORMAT

    #define AGS_NOTATION_CLIPBOARD_FORMAT "AgsNotationNativePiano"

### enum AgsNotationFlags

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

#### Members

AGS_NOTATION_PATTERN_MODE | pattern mode |
AGS_NOTATION_BYPASS | ignore any notation data |

## Property Details

### The `“audio”` property

      “audio”                    AgsAudio *

The assigned AgsAudio

Owner: AgsNotation

Flags: Read / Write

Since: 3.0.0

### The `“audio-channel”` property

      “audio-channel”            guint

The effect's audio-channel.

Owner: AgsNotation

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

Since: 3.0.0

### The `“note”` property

      “note”                     gpointer

The assigned AgsNote

[transfer full]

Owner: AgsNotation

Flags: Read / Write

Since: 3.0.0

### The `“timestamp”` property

      “timestamp”                AgsTimestamp *

The notation's timestamp.

Owner: AgsNotation

Flags: Read / Write

Since: 3.0.0