TotemObject
3
TOTEM Library

# TotemObject

main Totem object

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <totem.h>

    typedef             TotemObject;
                        TotemObjectClass;
    enum                TotemRemoteCommand;
    void                totem_object_plugins_init           (TotemObject *totem);
    void                totem_object_plugins_shutdown       (void);
    void                totem_file_opened                   (TotemObject *totem,
                                                             const char *mrl);
    void                totem_file_closed                   (TotemObject *totem);
    void                totem_metadata_updated              (TotemObject *totem,
                                                             const char *artist,
                                                             const char *title,
                                                             const char *album,
                                                             guint track_num);
    void                totem_action_error                  (const char *title,
                                                             const char *reason,
                                                             Totem *totem);
    void                totem_action_exit                   (Totem *totem);
    void                totem_add_to_playlist_and_play      (Totem *totem,
                                                             const char *uri,
                                                             const char *display_name,
                                                             gboolean add_to_recent);
    void                totem_action_play                   (Totem *totem);
    void                totem_action_play_media             (Totem *totem,
                                                             TotemDiscMediaType type,
                                                             const char *device);
    void                totem_action_play_media_device      (Totem *totem,
                                                             const char *device);
    void                totem_action_play_pause             (Totem *totem);
    void                totem_action_pause                  (Totem *totem);
    void                totem_action_stop                   (Totem *totem);
    void                totem_action_fullscreen             (Totem *totem,
                                                             gboolean state);
    void                totem_action_fullscreen_toggle      (Totem *totem);
    void                totem_action_next                   (Totem *totem);
    void                totem_action_previous               (Totem *totem);
    void                totem_action_seek_time              (Totem *totem,
                                                             gint64 sec);
    void                totem_action_seek_relative          (Totem *totem,
                                                             gint64 offset);
    void                totem_action_volume_relative        (Totem *totem,
                                                             double off_pct);
    void                totem_action_toggle_aspect_ratio    (Totem *totem);
    int                 totem_action_get_aspect_ratio       (Totem *totem);
    void                totem_action_set_aspect_ratio       (Totem *totem,
                                                             int ratio);
    void                totem_action_toggle_controls        (Totem *totem);
    void                totem_action_set_scale_ratio        (Totem *totem,
                                                             gfloat ratio);
    void                totem_action_remote                 (Totem *totem,
                                                             TotemRemoteCommand cmd,
                                                             const char *url);
    gboolean            totem_is_fullscreen                 (Totem *totem);
    gboolean            totem_is_playing                    (Totem *totem);
    gboolean            totem_is_seekable                   (Totem *totem);
    GtkWindow *         totem_get_main_window               (Totem *totem);
    GtkUIManager *      totem_get_ui_manager                (Totem *totem);
    GtkWidget *         totem_get_video_widget              (Totem *totem);
    char *              totem_get_video_widget_backend_name (Totem *totem);
    char *              totem_get_current_mrl               (Totem *totem);
    gint64              totem_get_current_time              (Totem *totem);
    void                totem_set_current_subtitle          (Totem *totem,
                                                             const char *subtitle_uri);
    void                totem_add_sidebar_page              (Totem *totem,
                                                             const char *page_id,
                                                             const char *title,
                                                             GtkWidget *main_widget);
    void                totem_remove_sidebar_page           (Totem *totem,
                                                             const char *page_id);

## Object Hierarchy

      GObject
       +----TotemObject

## Properties

      "current-mrl"              gchar*                : Read
      "current-time"             gint64                : Read
      "fullscreen"               gboolean              : Read
      "playing"                  gboolean              : Read
      "seekable"                 gboolean              : Read
      "stream-length"            gint64                : Read

## Signals

      "file-closed"                                    : Run Last
      "file-opened"                                    : Run Last
      "metadata-updated"                               : Run Last

## Description

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

## Details

### TotemObject

    typedef struct TotemObject TotemObject;

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

### TotemObjectClass

    typedef struct {
    	GObjectClass parent_class;

    	void (*file_opened)			(Totem *totem, const char *mrl);
    	void (*file_closed)			(Totem *totem);
    	void (*metadata_updated)		(Totem *totem,
    						 const char *artist,
    						 const char *title,
    						 const char *album,
    						 guint track_num);
    } TotemObjectClass;

The class structure for the TotemPlParser type.

GObjectClass parent_class;

  the parent class

file_opened ()

  the generic signal handler for the "file-opened" signal, which can be overridden by inheriting classes

file_closed ()

  the generic signal handler for the "file-closed" signal, which can be overridden by inheriting classes

metadata_updated ()

  the generic signal handler for the "metadata-updated" signal, which can be overridden by inheriting classes

### enum TotemRemoteCommand

    typedef enum {
    	TOTEM_REMOTE_COMMAND_UNKNOWN,
    	TOTEM_REMOTE_COMMAND_PLAY,
    	TOTEM_REMOTE_COMMAND_PAUSE,
    	TOTEM_REMOTE_COMMAND_STOP,
    	TOTEM_REMOTE_COMMAND_PLAYPAUSE,
    	TOTEM_REMOTE_COMMAND_NEXT,
    	TOTEM_REMOTE_COMMAND_PREVIOUS,
    	TOTEM_REMOTE_COMMAND_SEEK_FORWARD,
    	TOTEM_REMOTE_COMMAND_SEEK_BACKWARD,
    	TOTEM_REMOTE_COMMAND_VOLUME_UP,
    	TOTEM_REMOTE_COMMAND_VOLUME_DOWN,
    	TOTEM_REMOTE_COMMAND_FULLSCREEN,
    	TOTEM_REMOTE_COMMAND_QUIT,
    	TOTEM_REMOTE_COMMAND_ENQUEUE,
    	TOTEM_REMOTE_COMMAND_REPLACE,
    	TOTEM_REMOTE_COMMAND_SHOW,
    	TOTEM_REMOTE_COMMAND_TOGGLE_CONTROLS,
    	TOTEM_REMOTE_COMMAND_SHOW_PLAYING,
    	TOTEM_REMOTE_COMMAND_SHOW_VOLUME,
    	TOTEM_REMOTE_COMMAND_UP,
    	TOTEM_REMOTE_COMMAND_DOWN,
    	TOTEM_REMOTE_COMMAND_LEFT,
    	TOTEM_REMOTE_COMMAND_RIGHT,
    	TOTEM_REMOTE_COMMAND_SELECT,
    	TOTEM_REMOTE_COMMAND_DVD_MENU,
    	TOTEM_REMOTE_COMMAND_ZOOM_UP,
    	TOTEM_REMOTE_COMMAND_ZOOM_DOWN,
    	TOTEM_REMOTE_COMMAND_EJECT,
    	TOTEM_REMOTE_COMMAND_PLAY_DVD,
    	TOTEM_REMOTE_COMMAND_MUTE,
    	TOTEM_REMOTE_COMMAND_TOGGLE_ASPECT
    } TotemRemoteCommand;

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

`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_TOGGLE_CONTROLS`

  toggle the control visibility

`TOTEM_REMOTE_COMMAND_SHOW_PLAYING`

  return the current stream's metadata

`TOTEM_REMOTE_COMMAND_SHOW_VOLUME`

  return the current volume

`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

### totem_object_plugins_init ()

    void                totem_object_plugins_init           (TotemObject *totem);

Initialises the plugin engine and activates all the enabled plugins.

`totem` :

  a TotemObject

### totem_object_plugins_shutdown ()

    void                totem_object_plugins_shutdown       (void);

Shuts down the plugin engine and deactivates all the plugins.

### totem_file_opened ()

    void                totem_file_opened                   (TotemObject *totem,
                                                             const char *mrl);

Emits the "file-opened" signal on `totem`, with the specified `mrl`.

`totem` :

  a TotemObject

`mrl` :

  the MRL opened

### totem_file_closed ()

    void                totem_file_closed                   (TotemObject *totem);

Emits the "file-closed" signal on `totem`.

`totem` :

  a TotemObject

### totem_metadata_updated ()

    void                totem_metadata_updated              (TotemObject *totem,
                                                             const char *artist,
                                                             const char *title,
                                                             const char *album,
                                                             guint track_num);

Emits the "metadata-updated" signal on `totem`, with the specified stream data.

`totem` :

  a TotemObject

`artist` :

  the stream's artist, or `NULL`

`title` :

  the stream's title, or `NULL`

`album` :

  the stream's album, or `NULL`

`track_num` :

  the track number of the stream

### totem_action_error ()

    void                totem_action_error                  (const char *title,
                                                             const char *reason,
                                                             Totem *totem);

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

`title` :

  the error dialog title

`reason` :

  the error dialog text

`totem` :

  a TotemObject

### totem_action_exit ()

    void                totem_action_exit                   (Totem *totem);

Closes Totem.

`totem` :

  a TotemObject

### totem_add_to_playlist_and_play ()

    void                totem_add_to_playlist_and_play      (Totem *totem,
                                                             const char *uri,
                                                             const char *display_name,
                                                             gboolean add_to_recent);

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

`totem` :

  a TotemObject

`uri` :

  the URI to add to the playlist

`display_name` :

  the display name of the URI

`add_to_recent` :

  if `TRUE`, add the URI to the recent items list

### totem_action_play ()

    void                totem_action_play                   (Totem *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.

`totem` :

  a TotemObject

### totem_action_play_media ()

    void                totem_action_play_media             (Totem *totem,
                                                             TotemDiscMediaType type,
                                                             const char *device);

Attempts to play the media found on `device` (for example, a DVD in a drive or a DVB tuner) by first adding it to the playlist, then playing it.

An error dialog will be displayed if Totem cannot support media of `type`.

`totem` :

  a TotemObject

`type` :

  the type of disc media

`device` :

  the media's device path

### totem_action_play_media_device ()

    void                totem_action_play_media_device      (Totem *totem,
                                                             const char *device);

Attempts to play the media device (for example, a DVD drive or CD drive) with the given `device` path by first adding it to the playlist, then playing it.

An error dialog will be displayed if Totem cannot read or play what's on the media device.

`totem` :

  a TotemObject

`device` :

  the media device's path

### totem_action_play_pause ()

    void                totem_action_play_pause             (Totem *totem);

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

`totem` :

  a TotemObject

### totem_action_pause ()

    void                totem_action_pause                  (Totem *totem);

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

`totem` :

  a TotemObject

### totem_action_stop ()

    void                totem_action_stop                   (Totem *totem);

Stops the current stream.

`totem` :

  a TotemObject

### totem_action_fullscreen ()

    void                totem_action_fullscreen             (Totem *totem,
                                                             gboolean state);

Sets Totem's fullscreen state according to `state`.

`totem` :

  a TotemObject

`state` :

  `TRUE` if Totem should be fullscreened

### totem_action_fullscreen_toggle ()

    void                totem_action_fullscreen_toggle      (Totem *totem);

Toggles Totem's fullscreen state; if Totem is fullscreened, calling this makes it unfullscreened and vice-versa.

`totem` :

  a TotemObject

### totem_action_next ()

    void                totem_action_next                   (Totem *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.

`totem` :

  a TotemObject

### totem_action_previous ()

    void                totem_action_previous               (Totem *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.

`totem` :

  a TotemObject

### totem_action_seek_time ()

    void                totem_action_seek_time              (Totem *totem,
                                                             gint64 sec);

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

`totem` :

  a TotemObject

`sec` :

  the time to seek to

### totem_action_seek_relative ()

    void                totem_action_seek_relative          (Totem *totem,
                                                             gint64 offset);

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

`totem` :

  a TotemObject

`offset` :

  the time offset to seek to

### totem_action_volume_relative ()

    void                totem_action_volume_relative        (Totem *totem,
                                                             double off_pct);

Sets the volume relative to its current level, with 1.0 being the maximum, and 0.0 being the minimum level.

`totem` :

  a TotemObject

`off_pct` :

  the value by which to increase or decrease the volume

### totem_action_toggle_aspect_ratio ()

    void                totem_action_toggle_aspect_ratio    (Totem *totem);

Toggles the aspect ratio selected in the menu to the next one in the list.

`totem` :

  a TotemObject

### totem_action_get_aspect_ratio ()

    int                 totem_action_get_aspect_ratio       (Totem *totem);

Gets the current aspect ratio as defined in BaconVideoWidgetAspectRatio.

`totem` :

  a TotemObject

Returns :

  the current aspect ratio

### totem_action_set_aspect_ratio ()

    void                totem_action_set_aspect_ratio       (Totem *totem,
                                                             int ratio);

Sets the aspect ratio selected in the menu to `ratio`, as defined in BaconVideoWidgetAspectRatio.

`totem` :

  a TotemObject

`ratio` :

  the aspect ratio to use

### totem_action_toggle_controls ()

    void                totem_action_toggle_controls        (Totem *totem);

If Totem's not fullscreened, this toggles the state of the "Show Controls" menu entry, and consequently shows or hides the controls in the UI.

`totem` :

  a TotemObject

### totem_action_set_scale_ratio ()

    void                totem_action_set_scale_ratio        (Totem *totem,
                                                             gfloat ratio);

Sets the video scale ratio, as a float where, for example, 1.0 is 1:1 and 2.0 is 2:1.

`totem` :

  a TotemObject

`ratio` :

  the scale ratio to use

### totem_action_remote ()

    void                totem_action_remote                 (Totem *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.

`totem` :

  a TotemObject

`cmd` :

  a TotemRemoteCommand

`url` :

  an MRL to play, or `NULL`

### totem_is_fullscreen ()

    gboolean            totem_is_fullscreen                 (Totem *totem);

Returns `TRUE` if Totem is fullscreened.

`totem` :

  a TotemObject

Returns :

  `TRUE` if Totem is fullscreened

### totem_is_playing ()

    gboolean            totem_is_playing                    (Totem *totem);

Returns `TRUE` if Totem is playing a stream.

`totem` :

  a TotemObject

Returns :

  `TRUE` if Totem is playing a stream

### totem_is_seekable ()

    gboolean            totem_is_seekable                   (Totem *totem);

Returns `TRUE` if the current stream is seekable.

`totem` :

  a TotemObject

Returns :

  `TRUE` if the current stream is seekable

### totem_get_main_window ()

    GtkWindow *         totem_get_main_window               (Totem *totem);

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

`totem` :

  a TotemObject

Returns :

  Totem's main window

### totem_get_ui_manager ()

    GtkUIManager *      totem_get_ui_manager                (Totem *totem);

Gets Totem's UI manager, but does not change its reference count.

`totem` :

  a TotemObject

Returns :

  Totem's UI manager

### totem_get_video_widget ()

    GtkWidget *         totem_get_video_widget              (Totem *totem);

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

`totem` :

  a TotemObject

Returns :

  Totem's video widget

### totem_get_video_widget_backend_name ()

    char *              totem_get_video_widget_backend_name (Totem *totem);

Gets the name string of the backend video widget, typically the video library's version string (e.g. what's returned by `gst_version_string()`). Free with `g_free()`.

`totem` :

  a TotemObject

Returns :

  a newly-allocated string of the name of the backend video widget

### totem_get_current_mrl ()

    char *              totem_get_current_mrl               (Totem *totem);

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

`totem` :

  a TotemObject

Returns :

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

### totem_get_current_time ()

    gint64              totem_get_current_time              (Totem *totem);

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

`totem` :

  a TotemObject

Returns :

  the current position in the stream

### totem_set_current_subtitle ()

    void                totem_set_current_subtitle          (Totem *totem,
                                                             const char *subtitle_uri);

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

`totem` :

  a TotemObject

`subtitle_uri` :

  the URI of the subtitle file to add

### totem_add_sidebar_page ()

    void                totem_add_sidebar_page              (Totem *totem,
                                                             const char *page_id,
                                                             const char *title,
                                                             GtkWidget *main_widget);

Adds a sidebar page to Totem's sidebar with the given `page_id`. `main_widget` is added into the page and shown automatically, while `title` is displayed as the page's title in the tab bar.

`totem` :

  a TotemObject

`page_id` :

  a string used to identify the page

`title` :

  the page's title

`main_widget` :

  the main widget for the page

### totem_remove_sidebar_page ()

    void                totem_remove_sidebar_page           (Totem *totem,
                                                             const char *page_id);

Removes the page identified by `page_id` from Totem's sidebar. If `page_id` doesn't exist in the sidebar, this function does nothing.

`totem` :

  a TotemObject

`page_id` :

  a string used to identify the page

## Property Details

### The `"current-mrl"` property

      "current-mrl"              gchar*                : Read

The MRL of the current stream.

Default value: NULL

### The `"current-time"` property

      "current-time"             gint64                : Read

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

Default value: 0

### The `"fullscreen"` property

      "fullscreen"               gboolean              : Read

If `TRUE`, Totem is in fullscreen mode.

Default value: FALSE

### The `"playing"` property

      "playing"                  gboolean              : Read

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

Default value: FALSE

### The `"seekable"` property

      "seekable"                 gboolean              : Read

If `TRUE`, the current stream is seekable.

Default value: FALSE

### The `"stream-length"` property

      "stream-length"            gint64                : Read

The length of the current stream, in milliseconds.

Default value: 0

## Signal Details

### The `"file-closed"` signal

    void                user_function                      (TotemObject *totem,
                                                            gpointer     user_data)      : Run Last

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

`totem` :

  the TotemObject which received the signal

`user_data` :

  user data set when the signal handler was connected.

### The `"file-opened"` signal

    void                user_function                      (TotemObject *totem,
                                                            gchar       *mrl,
                                                            gpointer     user_data)      : Run Last

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

`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.

### The `"metadata-updated"` signal

    void                user_function                      (TotemObject *totem,
                                                            gchar       *artist,
                                                            gchar       *title,
                                                            gchar       *album,
                                                            guint        track_number,
                                                            gpointer     user_data)         : Run Last

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

`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.