## PtWaveviewer

PtWaveviewer — A GtkWidget to display a waveform.

## Stability Level

Stable, unless otherwise indicated

## Functions

GtkWidget * | pt_waveviewer_new ()
void | pt_waveviewer_load_wave_async ()
gboolean | pt_waveviewer_load_wave_finish ()
void | pt_waveviewer_set_follow_cursor ()
gboolean | pt_waveviewer_get_follow_cursor ()

## Properties

gboolean | fixed-cursor | Read / Write / Construct
gboolean | follow-cursor | Read / Write / Construct
gboolean | has-selection | Read
gint64 | playback-cursor | Read / Write
int | pps | Read / Write / Construct
gint64 | selection-end | Read
gint64 | selection-start | Read
gboolean | show-ruler | Read / Write / Construct

## Signals

void | cursor-changed | Run First
void | load-progress | Run First
void | play-toggled | Run First
void | selection-changed | Run First

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── PtWaveviewer

## Includes

    #include <parlatype/parlatype.h>

## Description

Displays a waveform and lets the user interact with it: jumping to a position, make selections and so on.

## Functions

### pt_waveviewer_new ()

    GtkWidget *
    pt_waveviewer_new (void);

Create a new, initially blank waveform viewer widget.

After use `gtk_widget_destroy()` it.

#### Returns

the widget

Since: 1.5

### pt_waveviewer_load_wave_async ()

    void
    pt_waveviewer_load_wave_async (PtWaveviewer *self,
                                   gchar *uri,
                                   GCancellable *cancel,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Load wave form for the given URI. The initial resolution is set to “pps”. While loading, a “load-progress” signal is emitted. A previous waveform is discarded.

#### Parameters

self | the widget |
uri | the URI of the file |
cancel | a GCancellable or NULL. | [nullable]
callback | a GAsyncReadyCallback to call when the operation is complete. | [scope async][closure user_data]
user_data | user data for `callback` |

Since: 2.0

### pt_waveviewer_load_wave_finish ()

    gboolean
    pt_waveviewer_load_wave_finish (PtWaveviewer *self,
                                    GAsyncResult *result,
                                    GError **error);

Gives the result of the async load operation. A cancelled operation results in an error, too.

#### Parameters

self | the widget |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a NULL GError, or NULL. | [nullable]

#### Returns

TRUE if successful, or FALSE with error set

Since: 2.0

### pt_waveviewer_set_follow_cursor ()

    void
    pt_waveviewer_set_follow_cursor (PtWaveviewer *self,
                                     gboolean follow);

Set follow-cursor option to TRUE or FALSE. See also “follow-cursor”.

#### Parameters

self | the widget |
follow | new value |

Since: 1.5

### pt_waveviewer_get_follow_cursor ()

    gboolean
    pt_waveviewer_get_follow_cursor (PtWaveviewer *self);

Get follow-cursor option.

#### Parameters

self | the widget |

#### Returns

TRUE if cursor is followed, else FALSE

Since: 1.5

## Property Details

### The `“fixed-cursor”` property

      “fixed-cursor”             gboolean

If TRUE, in follow-cursor mode the cursor is at a fixed position and the waveform is scrolling. If FALSE the cursor is moving.

If “follow-cursor” is FALSE, this has no effect.

Owner: PtWaveviewer

Flags: Read / Write / Construct

Default value: TRUE

### The `“follow-cursor”` property

      “follow-cursor”            gboolean

If the widget follows the cursor, it scrolls automatically to the cursor’s position. Note that the widget will change this property to FALSE if the user scrolls the widget manually.

Owner: PtWaveviewer

Flags: Read / Write / Construct

Default value: TRUE

### The `“has-selection”` property

      “has-selection”            gboolean

Whether something is selected (TRUE) or not (FALSE).

Owner: PtWaveviewer

Flags: Read

Default value: FALSE

### The `“playback-cursor”` property

      “playback-cursor”          gint64

Current playback position in milliseconds. A value of -1 means an invalid or unknown position that will not be rendered.

Owner: PtWaveviewer

Flags: Read / Write

Allowed values: >= -1

Default value: 0

### The `“pps”` property

      “pps”                      int

Current/requested resolution of waveform in pixels per second.

Owner: PtWaveviewer

Flags: Read / Write / Construct

Allowed values: [25,200]

Default value: 100

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

      “selection-end”            gint64

End time of selection in milliseconds. If it’s equal to the start time, there is no selection. See also “has-selection”.

Owner: PtWaveviewer

Flags: Read

Allowed values: >= 0

Default value: 0

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

      “selection-start”          gint64

Start time of selection in milliseconds. If it’s equal to the end time, there is no selection. See also “has-selection”.

Owner: PtWaveviewer

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“show-ruler”` property

      “show-ruler”               gboolean

Whether the ruler is shown (TRUE) or not (FALSE).

Owner: PtWaveviewer

Flags: Read / Write / Construct

Default value: TRUE

## Signal Details

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

    void
    user_function (PtWaveviewer *self,
                   gint64        position,
                   gpointer      user_data)

Signals that the cursor’s position was changed by the user.

#### Parameters

self | the waveviewer emitting the signal |
position | the new position in stream in milliseconds |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“load-progress”` signal

    void
    user_function (PtWaveviewer *self,
                   double        progress,
                   gpointer      user_data)

Indicates progress on a scale from 0.0 to 1.0. The value 0.0 is not emitted, the last signal (on success) is 1.0.

#### Parameters

self | the waveviewer emitting the signal |
progress | the new progress state, ranging from 0.0 to 1.0 |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“play-toggled”` signal

    void
    user_function (PtWaveviewer *self,
                   gpointer      user_data)

Signals that the user requested to toggle play/pause.

#### Parameters

self | the waveviewer emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

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

    void
    user_function (PtWaveviewer *self,
                   gpointer      user_data)

Signals that the selection was changed (or unselected) by the user. To query the new selection see “has-selection”, “selection-start” and “selection-end”.

#### Parameters

self | the waveviewer emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First