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_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 ()

## Types and Values

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

## 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 the current stream.

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

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.