TotemObject: Totem Reference Manual

## TotemObject TotemObject — main Totem object |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | totem_object_show_error ()
void | totem_object_exit ()
void | totem_object_play ()
void | totem_object_play_pause ()
void | totem_object_stop ()
void | totem_object_seek_next ()
void | totem_object_seek_previous ()
gboolean | totem_object_can_seek_next ()
gboolean | totem_object_can_seek_previous ()
gboolean | totem_object_remote_get_setting ()
void | totem_object_remote_set_setting ()
void | totem_object_seek_time ()
void | totem_object_seek_relative ()
void | totem_object_set_volume ()
void | totem_object_remote_command ()
gboolean | totem_object_is_playing ()
gboolean | totem_object_is_paused ()
gboolean | totem_object_is_seekable ()
GtkWindow * | totem_object_get_main_window ()
char * | totem_object_get_current_mrl ()
GtkWidget * | totem_object_get_video_widget ()
void | totem_object_set_current_subtitle ()
guint | totem_object_get_playlist_length ()
int | totem_object_get_playlist_pos ()
char * | totem_object_get_title_at_playlist_pos ()
double | totem_object_get_volume ()
const gchar * const * | totem_object_get_supported_content_types ()
const gchar * const * | totem_object_get_supported_uri_schemes ()
float | totem_object_get_rate ()
gboolean | totem_object_set_rate ()
void | totem_object_add_to_playlist ()
void | totem_object_add_to_view ()
void | totem_object_clear_playlist ()
void | totem_object_empty_menu_section ()
gint64 | totem_object_get_current_time ()
GMenu * | totem_object_get_menu_section ()
char * | totem_object_get_short_title ()
gboolean | totem_object_is_fullscreen ()
void | totem_object_next_angle ()
void | totem_object_pause ()

## Properties

char * | current-content-type | Read
char * | current-display-name | Read
char * | current-mrl | Read
gint64 | current-time | Read
gboolean | fullscreen | Read
char * | main-page | Read
gboolean | playing | Read
gboolean | seekable | Read
gint64 | stream-length | Read

## Signals

void | file-closed | Run Last
void | file-has-played | Run Last
void | file-opened | Run Last
char* | get-text-subtitle | Run Last
char* | get-user-agent | Run Last
void | metadata-updated | Run Last

## Types and Values

typedef | Totem
| TotemObject
enum | TotemRemoteCommand
enum | TotemRemoteSetting
#define | TOTEM_GSETTINGS_SCHEMA

## Object Hierarchy

        GObject
        ╰── GApplication
            ╰── GtkApplication
                ╰── TotemObject

## Implemented Interfaces

TotemObject implements GActionGroup and GActionMap.

## Includes

    #include <totem.h>

## Description

TotemObject is the core object of Totem; a singleton which controls all Totem's main functions.

## Functions

### totem_object_show_error ()

    void
    totem_object_show_error (TotemObject *totem,
                             const char *title,
                             const char *reason);

Displays a non-blocking error dialog with the given `title` and `reason` .

#### Parameters

totem | a TotemObject |
title | the error dialog title |
reason | the error dialog text |

### totem_object_exit ()

    void
    totem_object_exit (TotemObject *totem);

Closes Totem.

#### Parameters

totem | a TotemObject |

### totem_object_play ()

    void
    totem_object_play (TotemObject *totem);

Plays the current stream. If Totem is already playing, it continues to play. If the stream cannot be played, and error dialog is displayed.

#### Parameters

totem | a TotemObject |

### totem_object_play_pause ()

    void
    totem_object_play_pause (TotemObject *totem);

Gets the current MRL from the playlist and attempts to play it. If the stream is already playing, playback is paused.

#### Parameters

totem | a TotemObject |

### totem_object_stop ()

    void
    totem_object_stop (TotemObject *totem);

Stops playback, and sets the playlist back at the start.

#### Parameters

totem | a TotemObject |

### totem_object_seek_next ()

    void
    totem_object_seek_next (TotemObject *totem);

If a DVD is being played, goes to the next chapter. If a normal stream is being played, plays the next entry in the playlist.

#### Parameters

totem | a TotemObject |

### totem_object_seek_previous ()

    void
    totem_object_seek_previous (TotemObject *totem);

If a DVD is being played, goes to the previous chapter. If a normal stream is being played, goes to the start of the stream if possible. If seeking is not possible, plays the previous entry in the playlist.

#### Parameters

totem | a TotemObject |

### totem_object_can_seek_next ()

    gboolean
    totem_object_can_seek_next (TotemObject *totem);

Returns true if `totem_object_seek_next()` would have an effect.

#### Parameters

totem | a TotemObject |

### totem_object_can_seek_previous ()

    gboolean
    totem_object_can_seek_previous (TotemObject *totem);

Returns true if `totem_object_seek_previous()` would have an effect.

#### Parameters

totem | a TotemObject |

### totem_object_remote_get_setting ()

    gboolean
    totem_object_remote_get_setting (TotemObject *totem,
                                     TotemRemoteSetting setting);

Returns the value of `setting` for this instance of Totem.

#### Parameters

totem | a TotemObject |
setting | a TotemRemoteSetting |

#### Returns

`TRUE` if the setting is enabled, `FALSE` otherwise

### totem_object_remote_set_setting ()

    void
    totem_object_remote_set_setting (TotemObject *totem,
                                     TotemRemoteSetting setting,
                                     gboolean value);

Sets `setting` to `value` on this instance of Totem.

#### Parameters

totem | a TotemObject |
setting | a TotemRemoteSetting |
value | the new value for the setting |

### totem_object_seek_time ()

    void
    totem_object_seek_time (TotemObject *totem,
                            gint64 msec,
                            gboolean accurate);

Seeks to an absolute time in the stream, or displays an error dialog if that's not possible.

#### Parameters

totem | a TotemObject |
msec | the time to seek to |
accurate | whether to use accurate seek, an accurate seek might be slower for some formats (see GStreamer docs) |

### totem_object_seek_relative ()

    void
    totem_object_seek_relative (TotemObject *totem,
                                gint64 offset,
                                gboolean accurate);

Seeks to an `offset` from the current position in the stream, or displays an error dialog if that's not possible.

#### Parameters

totem | a TotemObject |
offset | the time offset to seek to |
accurate | whether to use accurate seek, an accurate seek might be slower for some formats (see GStreamer docs) |

### totem_object_set_volume ()

    void
    totem_object_set_volume (TotemObject *totem,
                             double volume);

Sets the volume, with `1.0` being the maximum, and `0.0` being the minimum level.

#### Parameters

totem | a TotemObject |
volume | the new absolute volume value |

### totem_object_remote_command ()

    void
    totem_object_remote_command (TotemObject *totem,
                                 TotemRemoteCommand cmd,
                                 const char *url);

Executes the specified `cmd` on this instance of Totem. If `cmd` is an operation requiring an MRL, `url` is required; it can be `NULL` otherwise.

If Totem's fullscreened and the operation is executed correctly, the controls will appear as if the user had moved the mouse.

#### Parameters

totem | a TotemObject |
cmd | a TotemRemoteCommand |
url | an MRL to play, or `NULL` |

### totem_object_is_playing ()

    gboolean
    totem_object_is_playing (TotemObject *totem);

Returns `TRUE` if Totem is playing a stream.

#### Parameters

totem | a TotemObject |

#### Returns

`TRUE` if Totem is playing a stream

### totem_object_is_paused ()

    gboolean
    totem_object_is_paused (TotemObject *totem);

Returns `TRUE` if playback is paused.

#### Parameters

totem | a TotemObject |

#### Returns

`TRUE` if playback is paused, `FALSE` otherwise

### totem_object_is_seekable ()

    gboolean
    totem_object_is_seekable (TotemObject *totem);

Returns `TRUE` if the current stream is seekable.

#### Parameters

totem | a TotemObject |

#### Returns

`TRUE` if the current stream is seekable

### totem_object_get_main_window ()

    GtkWindow *
    totem_object_get_main_window (TotemObject *totem);

Gets Totem's main window and increments its reference count.

#### Parameters

totem | a TotemObject |

#### Returns

Totem's main window.

[transfer full]

### totem_object_get_current_mrl ()

    char *
    totem_object_get_current_mrl (TotemObject *totem);

Get the MRL of the current stream, or `NULL` if nothing's playing. Free with `g_free()`.

#### Parameters

totem | a TotemObject |

#### Returns

a newly-allocated string containing the MRL of the current stream

### totem_object_get_video_widget ()

    GtkWidget *
    totem_object_get_video_widget (TotemObject *totem);

Gets Totem's video widget and increments its reference count.

#### Parameters

totem | a TotemObject |

#### Returns

Totem's video widget.

[transfer full]

### totem_object_set_current_subtitle ()

    void
    totem_object_set_current_subtitle (TotemObject *totem,
                                       const char *subtitle_uri);

Add the `subtitle_uri` subtitle file to the playlist, setting it as the subtitle for the current playlist entry.

#### Parameters

totem | a TotemObject |
subtitle_uri | the URI of the subtitle file to add |

### totem_object_get_playlist_length ()

    guint
    totem_object_get_playlist_length (TotemObject *totem);

Returns the length of the current playlist.

#### Parameters

totem | a TotemObject |

#### Returns

the playlist length

### totem_object_get_playlist_pos ()

    int
    totem_object_get_playlist_pos (TotemObject *totem);

Returns the `0`-based index of the current entry in the playlist. If there is no current entry in the playlist, `-1` is returned.

#### Parameters

totem | a TotemObject |

#### Returns

the index of the current playlist entry, or `-1`

### totem_object_get_title_at_playlist_pos ()

    char *
    totem_object_get_title_at_playlist_pos
                                   (TotemObject *totem,
                                    guint playlist_index);

Gets the title of the playlist entry at `index` .

#### Parameters

totem | a TotemObject |
playlist_index | the `0`-based entry index |

#### Returns

the entry title at `index` , or `NULL`; free with `g_free()`

### totem_object_get_volume ()

    double
    totem_object_get_volume (TotemObject *totem);

Gets the current volume level, as a value between `0.0` and `1.0`.

#### Parameters

totem | a TotemObject |

#### Returns

the volume level

### totem_object_get_supported_content_types ()

    const gchar * const *
    totem_object_get_supported_content_types
                                   (void);

Get the full list of file content types which Totem supports playing.

#### Returns

a `NULL`-terminated array of the content types Totem supports.

[array zero-terminated=1][transfer none]

Since: 3.1.5

### totem_object_get_supported_uri_schemes ()

    const gchar * const *
    totem_object_get_supported_uri_schemes
                                   (void);

Get the full list of URI schemes which Totem supports accessing.

#### Returns

a `NULL`-terminated array of the URI schemes Totem supports.

[array zero-terminated=1][transfer none]

Since: 3.1.5

### totem_object_get_rate ()

    float
    totem_object_get_rate (TotemObject *totem);

Gets the current playback rate, with `1.0` being the normal playback rate.

#### Parameters

totem | a TotemObject |

#### Returns

the volume level

### totem_object_set_rate ()

    gboolean
    totem_object_set_rate (TotemObject *totem,
                           float rate);

Sets the playback rate, with `1.0` being the normal playback rate.

#### Parameters

totem | a TotemObject |
rate | the new absolute playback rate |

#### Returns

`TRUE` on success, `FALSE` on failure.

### totem_object_add_to_playlist ()

    void
    totem_object_add_to_playlist (TotemObject *totem,
                                  const char *uri,
                                  const char *display_name,
                                  gboolean play);

Add `uri` to the playlist and play it immediately.

#### Parameters

totem | a TotemObject |
uri | the URI to add to the playlist |
display_name | the display name of the URI. | [allow-none]
play | whether to play the added item |

### totem_object_add_to_view ()

    void
    totem_object_add_to_view (TotemObject *totem,
                              GFile *file,
                              const char *title);

Adds a local media file to the main view.

#### Parameters

totem | a TotemObject |
file | a GFile representing a media |
title | a title for the media, or `NULL` |

### totem_object_clear_playlist ()

    void
    totem_object_clear_playlist (TotemObject *totem);

Empties the current playlist.

#### Parameters

totem | a TotemObject |

### totem_object_empty_menu_section ()

    void
    totem_object_empty_menu_section (TotemObject *totem,
                                     const char *id);

Empty the GMenu section pointed to by `id` , and remove any related actions. Note that menu items with specific target will not have the associated action removed.

#### Parameters

totem | a TotemObject |
id | the ID for the menu section to empty |

### totem_object_get_current_time ()

    gint64
    totem_object_get_current_time (TotemObject *totem);

Gets the current position's time in the stream as a gint64.

#### Parameters

totem | a TotemObject |

#### Returns

the current position in the stream

### totem_object_get_menu_section ()

    GMenu *
    totem_object_get_menu_section (TotemObject *totem,
                                   const char *id);

Get the GMenu of the given `id` from the main Totem GtkBuilder file.

#### Parameters

totem | a TotemObject |
id | the ID for the menu section to look up |

#### Returns

a GMenu or `NULL` on failure.

[transfer none][nullable]

### totem_object_get_short_title ()

    char *
    totem_object_get_short_title (TotemObject *totem);

Gets the title of the current entry in the playlist.

#### Parameters

totem | a TotemObject |

#### Returns

the current entry's title, or `NULL`; free with `g_free()`

### totem_object_is_fullscreen ()

    gboolean
    totem_object_is_fullscreen (TotemObject *totem);

Returns `TRUE` if Totem is fullscreened.

#### Parameters

totem | a TotemObject |

#### Returns

`TRUE` if Totem is fullscreened

### totem_object_next_angle ()

    void
    totem_object_next_angle (TotemObject *totem);

Switches to the next angle, if watching a DVD. If not watching a DVD, this is a no-op.

#### Parameters

totem | a TotemObject |

### totem_object_pause ()

    void
    totem_object_pause (TotemObject *totem);

Pauses the current stream. If Totem is already paused, it continues to be paused.

#### Parameters

totem | a TotemObject |

## Types and Values

### Totem

    typedef struct _TotemObject Totem;

The Totem object is a handy synonym for TotemObject, and the two can be used interchangably.

### TotemObject

    typedef struct _TotemObject TotemObject;

All the fields in the TotemObject structure are private and should never be accessed directly.

### enum TotemRemoteCommand

Represents a command which can be sent to a running Totem instance remotely.

#### Members

TOTEM_REMOTE_COMMAND_UNKNOWN | unknown command |
TOTEM_REMOTE_COMMAND_PLAY | play the current stream |
TOTEM_REMOTE_COMMAND_PAUSE | pause the current stream |
TOTEM_REMOTE_COMMAND_STOP | stop playing the current stream |
TOTEM_REMOTE_COMMAND_PLAYPAUSE | toggle play/pause on the current stream |
TOTEM_REMOTE_COMMAND_NEXT | play the next playlist item |
TOTEM_REMOTE_COMMAND_PREVIOUS | play the previous playlist item |
TOTEM_REMOTE_COMMAND_SEEK_FORWARD | seek forwards in the current stream |
TOTEM_REMOTE_COMMAND_SEEK_BACKWARD | seek backwards in the current stream |
TOTEM_REMOTE_COMMAND_VOLUME_UP | increase the volume |
TOTEM_REMOTE_COMMAND_VOLUME_DOWN | decrease the volume |
TOTEM_REMOTE_COMMAND_FULLSCREEN | toggle fullscreen mode |
TOTEM_REMOTE_COMMAND_QUIT | quit the instance of Totem |
TOTEM_REMOTE_COMMAND_ENQUEUE | enqueue a new playlist item |
TOTEM_REMOTE_COMMAND_REPLACE | replace an item in the playlist |
TOTEM_REMOTE_COMMAND_SHOW | show the Totem instance |
TOTEM_REMOTE_COMMAND_UP | go up (DVD controls) |
TOTEM_REMOTE_COMMAND_DOWN | go down (DVD controls) |
TOTEM_REMOTE_COMMAND_LEFT | go left (DVD controls) |
TOTEM_REMOTE_COMMAND_RIGHT | go right (DVD controls) |
TOTEM_REMOTE_COMMAND_SELECT | select the current item (DVD controls) |
TOTEM_REMOTE_COMMAND_DVD_MENU | go to the DVD menu |
TOTEM_REMOTE_COMMAND_ZOOM_UP | increase the zoom level |
TOTEM_REMOTE_COMMAND_ZOOM_DOWN | decrease the zoom level |
TOTEM_REMOTE_COMMAND_EJECT | eject the current disc |
TOTEM_REMOTE_COMMAND_PLAY_DVD | play a DVD in a drive |
TOTEM_REMOTE_COMMAND_MUTE | toggle mute |
TOTEM_REMOTE_COMMAND_TOGGLE_ASPECT | toggle the aspect ratio |

### enum TotemRemoteSetting

Represents a boolean setting or preference on a remote Totem instance.

#### Members

TOTEM_REMOTE_SETTING_REPEAT | whether repeat is enabled |

### TOTEM_GSETTINGS_SCHEMA

    #define TOTEM_GSETTINGS_SCHEMA "org.gnome.totem"

The GSettings schema under which all Totem settings are stored.

## Property Details

### The `“current-content-type”` property

      “current-content-type”     char *

The content-type of the current stream.

Owner: TotemObject

Flags: Read

Default value: NULL

### The `“current-display-name”` property

      “current-display-name”     char *

The display name of the current stream.

Owner: TotemObject

Flags: Read

Default value: NULL

### The `“current-mrl”` property

      “current-mrl”              char *

The MRL of the current stream.

Owner: TotemObject

Flags: Read

Default value: NULL

### The `“current-time”` property

      “current-time”             gint64

The player's position (time) in the current stream, in milliseconds.

Owner: TotemObject

Flags: Read

Default value: 0

### The `“fullscreen”` property

      “fullscreen”               gboolean

If `TRUE`, Totem is in fullscreen mode.

Owner: TotemObject

Flags: Read

Default value: FALSE

### The `“main-page”` property

      “main-page”                char *

The name of the current main page (usually "grilo", or "player").

Owner: TotemObject

Flags: Read

Default value: NULL

### The `“playing”` property

      “playing”                  gboolean

If `TRUE`, Totem is playing an audio or video file.

Owner: TotemObject

Flags: Read

Default value: FALSE

### The `“seekable”` property

      “seekable”                 gboolean

If `TRUE`, the current stream is seekable.

Owner: TotemObject

Flags: Read

Default value: FALSE

### The `“stream-length”` property

      “stream-length”            gint64

The length of the current stream, in milliseconds.

Owner: TotemObject

Flags: Read

Default value: 0

## Signal Details

### The `“file-closed”` signal

    void
    user_function (TotemObject *totem,
                   gpointer     user_data)

The “file-closed” signal is emitted when Totem closes a stream.

#### Parameters

totem | the TotemObject which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“file-has-played”` signal

    void
    user_function (TotemObject *totem,
                   char        *mrl,
                   gpointer     user_data)

The “file-has-played” signal is emitted when a new stream has started playing in Totem.

#### Parameters

totem | the TotemObject which received the signal |
mrl | the MRL of the opened stream |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“file-opened”` signal

    void
    user_function (TotemObject *totem,
                   char        *mrl,
                   gpointer     user_data)

The “file-opened” signal is emitted when a new stream is opened by Totem.

#### Parameters

totem | the TotemObject which received the signal |
mrl | the MRL of the opened stream |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“get-text-subtitle”` signal

    char*
    user_function (TotemObject *totem,
                   char        *mrl,
                   gpointer     user_data)

The “get-text-subtitle” signal is emitted before opening a stream, so that plugins have the opportunity to detect or download text subtitles for the stream if necessary.

#### Parameters

totem | the TotemObject which received the signal |
mrl | the MRL of the opened stream |
user_data | user data set when the signal handler was connected. |

#### Returns

allocated string representing the URI of the subtitle to use for `mrl`

Flags: Run Last

### The `“get-user-agent”` signal

    char*
    user_function (TotemObject *totem,
                   char        *mrl,
                   gpointer     user_data)

The “get-user-agent” signal is emitted before opening a stream, so that plugins have the opportunity to return the user-agent to be set.

#### Parameters

totem | the TotemObject which received the signal |
mrl | the MRL of the opened stream |
user_data | user data set when the signal handler was connected. |

#### Returns

allocated string representing the user-agent to use for `mrl`

Flags: Run Last

### The `“metadata-updated”` signal

    void
    user_function (TotemObject *totem,
                   char        *artist,
                   char        *title,
                   char        *album,
                   guint        track_number,
                   gpointer     user_data)

The “metadata-updated” signal is emitted when the metadata of a stream is updated, typically when it's being loaded.

#### Parameters

totem | the TotemObject which received the signal |
artist | the name of the artist, or `NULL` |
title | the stream title, or `NULL` |
album | the name of the stream's album, or `NULL` |
track_number | the stream's track number |
user_data | user data set when the signal handler was connected. |

Flags: Run Last