PtWaveviewer: Parlatype Reference Manual

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	Write
int	pps	Write / Construct
gint64	selection-end	Read
gint64	selection-start	Read
gboolean	show-ruler	Read / Write / Construct

Signals

void	cursor-changed	Run First
void	follow-cursor-changed	Run First
void	load-progress	Run First
void	play-toggled	Run First
void	selection-changed	Run First
void	zoom-in	Run First
void	zoom-out	Run First

Types and Values

struct

PtWaveviewer

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBin
                    ╰── GtkScrolledWindow
                        ╰── PtWaveviewer

Implemented Interfaces

PtWaveviewer implements AtkImplementorIface and GtkBuildable.

Includes

#include <parlatype/pt-waveviewer.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]
user_data	user data for callback.	[closure]

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

Types and Values

struct PtWaveviewer

struct PtWaveviewer;

The PtWaveviewer contains only private fields and should not be directly accessed.

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: Write

Allowed values: >= -1

Default value: 0

The `“pps”` property

  “pps”                      int

Current/requested resolution of waveform in pixels per second.

Owner: PtWaveviewer

Flags: 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 *viewer,
               gint64        position,
               gpointer      user_data)

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

Parameters

viewer	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 `“follow-cursor-changed”` signal

void
user_function (PtWaveviewer *viewer,
               gboolean      follow,
               gpointer      user_data)

Signals that the “follow-cursor” property has changed.

Parameters

viewer	the waveviewer emitting the signal
follow	the new value
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“load-progress”` signal

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

Indicates progress on a scale from 0.0 to 1.0, however it does not emit the value 0.0 nor 1.0. Wait for a TRUE player-state-changed signal or an error signal to dismiss a gui element showing progress.

Parameters

viewer	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 *viewer,
               gpointer      user_data)

Signals that the user requested to toggle play/pause.

Parameters

viewer	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 *viewer,
               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

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

Flags: Run First

The `“zoom-in”` signal

void
user_function (PtWaveviewer *viewer,
               gpointer      user_data)

Signals that the user requested to zoom into the waveform.

Parameters

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

Flags: Run First

The `“zoom-out”` signal

void
user_function (PtWaveviewer *viewer,
               gpointer      user_data)

Signals that the user requested to zoom out of the waveform.

Parameters

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

Flags: Run First

PtWaveviewer

Stability Level

Functions

Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

Functions

pt_waveviewer_new ()

Returns

pt_waveviewer_load_wave_async ()

Parameters

pt_waveviewer_load_wave_finish ()

Parameters

Returns

pt_waveviewer_set_follow_cursor ()

Parameters

pt_waveviewer_get_follow_cursor ()

Parameters

Returns

Types and Values

struct PtWaveviewer

Property Details

The “fixed-cursor” property

The “follow-cursor” property

The “has-selection” property

The “playback-cursor” property

The “pps” property

The “selection-end” property

The “selection-start” property

The “show-ruler” property

Signal Details

The “cursor-changed” signal

Parameters

The “follow-cursor-changed” signal

Parameters

The “load-progress” signal

Parameters

The “play-toggled” signal

Parameters

The “selection-changed” signal

Parameters

The “zoom-in” signal

Parameters

The “zoom-out” signal

Parameters

The `“fixed-cursor”` property

The `“follow-cursor”` property

The `“has-selection”` property

The `“playback-cursor”` property

The `“pps”` property

The `“selection-end”` property

The `“selection-start”` property

The `“show-ruler”` property

The `“cursor-changed”` signal

The `“follow-cursor-changed”` signal

The `“load-progress”` signal

The `“play-toggled”` signal

The `“selection-changed”` signal

The `“zoom-in”` signal

The `“zoom-out”` signal