GNOME.org
 

totem r5350 - in trunk: . bindings/python src src/plugins

Author: pwithnall
Date: Tue Apr  8 22:15:00 2008
New Revision: 5350
URL: http://svn.gnome.org/viewvc/totem?rev=5350&view=rev

Log:
2008-04-08  Philip Withnall  <pwithnall svn gnome org>

	* bindings/python/totem.defs: Remove set_mrl_* functions from 
the
	bindings, as they bypass the playlist.
	* src/plugins/totem-plugin.c:
	* src/totem-cell-renderer-video.c:
	* src/totem-object.c:
	* src/totem.c: Add API documentation for most of the 
plugin-visible
	API. (Helps: #524119)



Modified:
   trunk/ChangeLog
   trunk/bindings/python/totem.defs
   trunk/src/plugins/totem-plugin.c
   trunk/src/totem-cell-renderer-video.c
   trunk/src/totem-object.c
   trunk/src/totem.c

Modified: trunk/bindings/python/totem.defs
==============================================================================
--- trunk/bindings/python/totem.defs	(original)
+++ trunk/bindings/python/totem.defs	Tue Apr  8 22:15:00 2008
@@ -269,37 +269,6 @@
   )
 )
 
-(define-method action_set_mrl
-  (of-object "TotemObject")
-  (c-name "totem_action_set_mrl")
-  (return-type "gboolean")
-  (parameters
-    '("const-char*" "mrl")
-    '("const-char*" "subtitle")
-  )
-)
-
-(define-method action_set_mrl_and_play
-  (of-object "TotemObject")
-  (c-name "totem_action_set_mrl_and_play")
-  (return-type "none")
-  (parameters
-    '("const-char*" "mrl")
-    '("const-char*" "subtitle")
-  )
-)
-
-(define-method action_set_mrl_with_warning
-  (of-object "TotemObject")
-  (c-name "totem_action_set_mrl_with_warning")
-  (return-type "gboolean")
-  (parameters
-    '("const-char*" "mrl")
-    '("const-char*" "subtitle")
-    '("gboolean" "warn")
-  )
-)
-
 (define-method action_play_media
   (of-object "TotemObject")
   (c-name "totem_action_play_media")

Modified: trunk/src/plugins/totem-plugin.c
==============================================================================
--- trunk/src/plugins/totem-plugin.c	(original)
+++ trunk/src/plugins/totem-plugin.c	Tue Apr  8 22:15:00 2008
@@ -158,6 +158,16 @@
 	}
 }
 
+/**
+ * totem_plugin_activate:
+ * @plugin: a #TotemPlugin
+ * @totem: a #TotemObject
+ * @error: return location for a #GError, or %NULL
+ *
+ * Activates the passed @plugin by calling its activate method.
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_plugin_activate (TotemPlugin *plugin,
 		       TotemObject *totem,
@@ -172,6 +182,13 @@
 	return TRUE;
 }
 
+/**
+ * totem_plugin_deactivate:
+ * @plugin: a #TotemPlugin
+ * @totem: a #TotemObject
+ *
+ * Deactivates @plugin by calling its deactivate method.
+ **/
 void
 totem_plugin_deactivate	(TotemPlugin *plugin,
 			 TotemObject *totem)
@@ -183,6 +200,16 @@
 		TOTEM_PLUGIN_GET_CLASS (plugin)->deactivate (plugin, totem);
 }
 
+/**
+ * totem_plugin_is_configurable:
+ * @plugin: a #TotemPlugin
+ *
+ * Returns %TRUE if the plugin is configurable and has a
+ * configuration dialog. It calls the plugin's
+ * is_configurable method.
+ *
+ * Return value: %TRUE if the plugin is configurable
+ **/
 gboolean
 totem_plugin_is_configurable (TotemPlugin *plugin)
 {
@@ -191,6 +218,15 @@
 	return TOTEM_PLUGIN_GET_CLASS (plugin)->is_configurable (plugin);
 }
 
+/**
+ * totem_plugin_create_configure_dialog:
+ * @plugin: a #TotemPlugin
+ *
+ * Returns the plugin's configuration dialog, as created by
+ * the plugin's create_configure_dialog method.
+ *
+ * Return value: the configuration dialog, or %NULL
+ **/
 GtkWidget *
 totem_plugin_create_configure_dialog (TotemPlugin *plugin)
 {
@@ -232,7 +268,20 @@
 	return paths;
 }
 
-
+/**
+ * totem_plugin_find_file:
+ * @plugin: a #TotemPlugin
+ * @file: the file to find
+ *
+ * Finds the specified @file by looking in the plugin paths
+ * listed by totem_get_plugin_paths() and then in the system
+ * Totem data directory.
+ *
+ * This should be used by plugins to find plugin-specific
+ * resource files.
+ *
+ * Return value: a newly-allocated absolute path for the file, or %NULL
+ **/
 char *
 totem_plugin_find_file (TotemPlugin *plugin,
 			const char *file)
@@ -276,6 +325,21 @@
 	return ret;
 }
 
+/**
+ * totem_plugin_load_interface:
+ * @plugin: a #TotemPlugin
+ * @name: interface filename
+ * @fatal: %TRUE if it's a fatal error if the interface can't be loaded
+ * @parent: the interface's parent #GtkWindow
+ * @user_data: a pointer to be passed to each signal handler in the interface when they're called
+ *
+ * Loads an interface file (GtkBuilder UI file) for a plugin, given its filename and
+ * assuming it's installed in the plugin's data directory.
+ *
+ * This should be used instead of attempting to load interfaces manually in plugins.
+ *
+ * Return value: the #GtkBuilder instance for the interface
+ **/
 GtkBuilder *
 totem_plugin_load_interface (TotemPlugin *plugin, const char *name,
 			     gboolean fatal, GtkWindow *parent,

Modified: trunk/src/totem-cell-renderer-video.c
==============================================================================
--- trunk/src/totem-cell-renderer-video.c	(original)
+++ trunk/src/totem-cell-renderer-video.c	Tue Apr  8 22:15:00 2008
@@ -61,6 +61,17 @@
 
 G_DEFINE_TYPE (TotemCellRendererVideo, totem_cell_renderer_video, GTK_TYPE_CELL_RENDERER)
 
+/**
+ * totem_cell_renderer_video_new:
+ * @use_placeholder: if %TRUE, use a placeholder thumbnail
+ *
+ * Creates a new #TotemCellRendererVideo with its :use-placeholder
+ * property set to @use_placeholder. If @use_placeholder is %TRUE,
+ * the renderer will display a generic placeholder thumbnail if a
+ * proper one is not available.
+ *
+ * Return value: a new #TotemCellRendererVideo
+ **/
 TotemCellRendererVideo *
 totem_cell_renderer_video_new (gboolean use_placeholder)
 {

Modified: trunk/src/totem-object.c
==============================================================================
--- trunk/src/totem-object.c	(original)
+++ trunk/src/totem-object.c	Tue Apr  8 22:15:00 2008
@@ -194,18 +194,39 @@
 	}
 }
 
+/**
+ * totem_object_plugins_init:
+ * @totem: a #TotemObject
+ *
+ * Initialises the plugin engine and activates all the
+ * enabled plugins.
+ **/
 void
 totem_object_plugins_init (TotemObject *totem)
 {
 	totem_plugins_engine_init (totem);
 }
 
+/**
+ * totem_object_plugins_shutdown:
+ *
+ * Shuts down the plugin engine and deactivates all the
+ * plugins.
+ **/
 void
 totem_object_plugins_shutdown (void)
 {
 	totem_plugins_engine_shutdown ();
 }
 
+/**
+ * totem_get_main_window:
+ * @totem: a #TotemObject
+ *
+ * Gets Totem's main window and increments its reference count.
+ *
+ * Return value: Totem's main window
+ **/
 GtkWindow *
 totem_get_main_window (Totem *totem)
 {
@@ -216,6 +237,14 @@
 	return GTK_WINDOW (totem->win);
 }
 
+/**
+ * totem_get_ui_manager:
+ * @totem: a #TotemObject
+ *
+ * Gets Totem's UI manager, but does not change its reference count.
+ *
+ * Return value: Totem's UI manager
+ **/
 GtkUIManager *
 totem_get_ui_manager (Totem *totem)
 {
@@ -224,6 +253,14 @@
 	return totem->ui_manager;
 }
 
+/**
+ * totem_get_video_widget:
+ * @totem: a #TotemObject
+ *
+ * Gets Totem's video widget and increments its reference count.
+ *
+ * Return value: Totem's video widget
+ **/
 GtkWidget *
 totem_get_video_widget (Totem *totem)
 {
@@ -240,6 +277,14 @@
 	return bacon_video_widget_get_backend_name (totem->bvw);
 }
 
+/**
+ * totem_get_current_time:
+ * @totem: a #TotemObject
+ *
+ * Gets the current position's time in the stream as a gint64.
+ *
+ * Return value: the current position in the stream
+ **/
 gint64
 totem_get_current_time (Totem *totem)
 {
@@ -304,6 +349,17 @@
 	return totem_playlist_get_current_title (totem->playlist, &custom);
 }
 
+/**
+ * totem_add_sidebar_page:
+ * @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
+ *
+ * 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.
+ **/
 void
 totem_add_sidebar_page (Totem *totem,
 			const char *page_id,
@@ -316,6 +372,15 @@
 			     main_widget);
 }
 
+/**
+ * totem_remove_sidebar_page:
+ * @totem: a #TotemObject
+ * @page_id: a string used to identify the page
+ *
+ * Removes the page identified by @page_id from Totem's sidebar.
+ * If @page_id doesn't exist in the sidebar, this function does
+ * nothing.
+ **/
 void
 totem_remove_sidebar_page (Totem *totem,
 			   const char *page_id)
@@ -324,6 +389,14 @@
 				page_id);
 }
 
+/**
+ * totem_file_opened:
+ * @totem: a #TotemObject
+ * @mrl: the MRL opened
+ *
+ * Emits the ::file-opened signal on @totem, with the
+ * specified @mrl.
+ **/
 void
 totem_file_opened (TotemObject *totem,
 		   const char *mrl)
@@ -333,6 +406,12 @@
 		       0, mrl);
 }
 
+/**
+ * totem_file_closed:
+ * @totem: a #TotemObject
+ *
+ * Emits the ::file-closed signal on @totem.
+ **/
 void
 totem_file_closed (TotemObject *totem)
 {
@@ -342,6 +421,16 @@
 
 }
 
+/**
+ * totem_metadata_updated:
+ * @totem: a #TotemObject
+ * @artist: the stream's artist
+ * @title: the stream's title
+ * @album: the stream's album
+ *
+ * Emits the ::metadata-updated signal on @totem,
+ * with the specified stream data.
+ **/
 void
 totem_metadata_updated (TotemObject *totem,
 			const char *artist,

Modified: trunk/src/totem.c
==============================================================================
--- trunk/src/totem.c	(original)
+++ trunk/src/totem.c	Tue Apr  8 22:15:00 2008
@@ -121,6 +121,15 @@
 		gtk_main_iteration ();
 }
 
+/**
+ * totem_action_error:
+ * @title: the error dialog title
+ * @reason: the error dialog text
+ * @totem: a #TotemObject
+ *
+ * Displays a non-blocking error dialog with the
+ * given @title and @reason.
+ **/
 void
 totem_action_error (const char *title, const char *reason, Totem *totem)
 {
@@ -199,6 +208,12 @@
 	exit (1);
 }
 
+/**
+ * totem_action_exit:
+ * @totem: a #TotemObject
+ *
+ * Closes Totem.
+ **/
 void
 totem_action_exit (Totem *totem)
 {
@@ -367,6 +382,13 @@
 		totem_sidebar_set_current_page (totem, "properties", TRUE);
 }
 
+/**
+ * totem_action_play:
+ * @totem: a #TotemObject
+ *
+ * Plays the current stream. If Totem is already playing, it continues
+ * to play. If the stream cannot be played, and error dialog is displayed.
+ **/
 void
 totem_action_play (Totem *totem)
 {
@@ -431,6 +453,16 @@
 	}
 }
 
+/**
+ * totem_action_set_mrl_and_play:
+ * @totem: a #TotemObject
+ * @mrl: the MRL to play
+ * @subtitle: a subtitle file to load, or %NULL
+ *
+ * Loads the specified @mrl and plays it, if possible.
+ * Calls totem_action_set_mrl() then totem_action_play().
+ * For more information, see the documentation for totem_action_set_mrl_with_warning().
+ **/
 void
 totem_action_set_mrl_and_play (Totem *totem, const char *mrl, const char *subtitle)
 {
@@ -578,6 +610,18 @@
 	return retval;
 }
 
+/**
+ * totem_action_play_media_device:
+ * @totem: a #TotemObject
+ * @device: the media device's path
+ *
+ * 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.
+ **/
 void
 totem_action_play_media_device (Totem *totem, const char *device)
 {
@@ -590,6 +634,17 @@
 	}
 }
 
+/**
+ * totem_action_play_media:
+ * @totem: a #TotemObject
+ * @type: the type of disc media
+ * @device: the media's device path
+ *
+ * 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.
+ **/
 void
 totem_action_play_media (Totem *totem, TotemDiscMediaType type, const char *device)
 {
@@ -602,6 +657,12 @@
 	}
 }
 
+/**
+ * totem_action_stop:
+ * @totem: a #TotemObject
+ *
+ * Stops the current stream.
+ **/
 void
 totem_action_stop (Totem *totem)
 {
@@ -609,6 +670,13 @@
 	play_pause_set_label (totem, STATE_STOPPED);
 }
 
+/**
+ * totem_action_play_pause:
+ * @totem: a #TotemObject
+ *
+ * Gets the current MRL from the playlist and attempts to play it.
+ * If the stream is already playing, playback is paused.
+ **/
 void
 totem_action_play_pause (Totem *totem)
 {
@@ -639,6 +707,13 @@
 	}
 }
 
+/**
+ * totem_action_pause:
+ * @totem: a #TotemObject
+ *
+ * Pauses the current stream. If Totem is already paused, it continues
+ * to be paused.
+ **/
 void
 totem_action_pause (Totem *totem)
 {
@@ -697,6 +772,13 @@
 	return FALSE;
 }
 
+/**
+ * totem_action_fullscreen_toggle:
+ * @totem: a #TotemObject
+ *
+ * Toggles Totem's fullscreen state; if Totem is fullscreened, calling
+ * this makes it unfullscreened and vice-versa.
+ **/
 void
 totem_action_fullscreen_toggle (Totem *totem)
 {
@@ -706,6 +788,13 @@
 		gtk_window_fullscreen (GTK_WINDOW (totem->win));
 }
 
+/**
+ * totem_action_fullscreen:
+ * @totem: a #TotemObject
+ * @state: %TRUE if Totem should be fullscreened
+ *
+ * Sets Totem's fullscreen state according to @state.
+ **/
 void
 totem_action_fullscreen (Totem *totem, gboolean state)
 {
@@ -903,6 +992,24 @@
 	}
 }
 
+/**
+ * totem_action_set_mrl_with_warning:
+ * @totem: a #TotemObject
+ * @mrl: the MRL to play
+ * @subtitle: a subtitle file to load, or %NULL
+ * @warn: %TRUE if error dialogs should be displayed
+ *
+ * Loads the specified @mrl and optionally the specified subtitle
+ * file. If @subtitle is %NULL Totem will attempt to auto-locate
+ * any subtitle files for @mrl.
+ *
+ * If a stream is already playing, it will be stopped and closed.
+ *
+ * If any errors are encountered, error dialogs will only be displayed
+ * if @warn is %TRUE.
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_action_set_mrl_with_warning (Totem *totem,
 				   const char *mrl, 
@@ -1022,6 +1129,17 @@
 	return retval;
 }
 
+/**
+ * totem_action_set_mrl:
+ * @totem: a #TotemObject
+ * @mrl: the MRL to load
+ * @subtitle: a subtitle file to load, or %NULL
+ *
+ * Calls totem_action_set_mrl_with_warning() with warnings enabled.
+ * For more information, see the documentation for totem_action_set_mrl_with_warning().
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_action_set_mrl (Totem *totem, const char *mrl, const char *subtitle)
 {
@@ -1072,12 +1190,27 @@
 	}
 }
 
+/**
+ * totem_action_previous:
+ * @totem: a #TotemObject
+ *
+ * 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.
+ **/
 void
 totem_action_previous (Totem *totem)
 {
 	totem_action_direction (totem, TOTEM_PLAYLIST_DIRECTION_PREVIOUS);
 }
 
+/**
+ * totem_action_next:
+ * @totem: a #TotemObject
+ *
+ * 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.
+ **/
 void
 totem_action_next (Totem *totem)
 {
@@ -1126,12 +1259,28 @@
 	}
 }
 
+/**
+ * totem_action_seek_relative:
+ * @totem: a #TotemObject
+ * @offset: the time offset to seek to
+ *
+ * Seeks to an @offset from the current position in the stream,
+ * or displays an error dialog if that's not possible.
+ **/
 void
 totem_action_seek_relative (Totem *totem, gint64 offset)
 {
 	totem_seek_time_rel (totem, offset, TRUE);
 }
 
+/**
+ * totem_action_seek_time:
+ * @totem: a #TotemObject
+ * @sec: the time to seek to
+ *
+ * Seeks to an absolute time in the stream, or displays an
+ * error dialog if that's not possible.
+ **/
 void
 totem_action_seek_time (Totem *totem, gint64 sec)
 {
@@ -1186,6 +1335,13 @@
 	totem_action_zoom (totem, 100);
 }
 
+/**
+ * totem_action_volume_relative:
+ * @totem: a #TotemObject
+ * @off_pct: the percentage by which to increase or decrease the volume
+ *
+ * Sets the volume relative to its current level.
+ **/
 void
 totem_action_volume_relative (Totem *totem, double off_pct)
 {
@@ -1198,6 +1354,13 @@
 	bacon_video_widget_set_volume (totem->bvw, vol + off_pct);
 }
 
+/**
+ * totem_action_toggle_aspect_ratio:
+ * @totem: a #TotemObject
+ *
+ * Toggles the aspect ratio selected in the menu to the
+ * next one in the list.
+ **/
 void
 totem_action_toggle_aspect_ratio (Totem *totem)
 {
@@ -1213,18 +1376,42 @@
 	gtk_radio_action_set_current_value (GTK_RADIO_ACTION (action), tmp);
 }
 
+/**
+ * totem_action_set_aspect_ratio:
+ * @totem: a #TotemObject
+ * @ratio: the aspect ratio to use
+ *
+ * Sets the aspect ratio selected in the menu to @ratio,
+ * as defined in #BaconVideoWidgetAspectRatio.
+ **/
 void
-totem_action_set_aspect_ratio (Totem *totem, int  ratio)
+totem_action_set_aspect_ratio (Totem *totem, int ratio)
 {
 	bacon_video_widget_set_aspect_ratio (totem->bvw, ratio);
 }
 
+/**
+ * totem_action_get_aspect_ratio:
+ * @totem: a #TotemObject
+ *
+ * Gets the current aspect ratio as defined in #BaconVideoWidgetAspectRatio.
+ *
+ * Return value: the current aspect ratio
+ **/
 int
 totem_action_get_aspect_ratio (Totem *totem)
 {
 	return (bacon_video_widget_get_aspect_ratio (totem->bvw));
 }
 
+/**
+ * totem_action_set_scale_ratio:
+ * @totem: a #TotemObject
+ * @ratio: the scale ratio to use
+ *
+ * Sets the video scale ratio, as a float where, for example,
+ * 1.0 is 1:1 and 2.0 is 2:1.
+ **/
 void
 totem_action_set_scale_ratio (Totem *totem, gfloat ratio)
 {
@@ -1865,6 +2052,13 @@
 	}
 }
 
+/**
+ * totem_action_toggle_controls:
+ * @totem: a #TotemObject
+ *
+ * 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.
+ **/
 void
 totem_action_toggle_controls (Totem *totem)
 {
@@ -1899,6 +2093,19 @@
 	g_free (subtitle);
 }
 
+/**
+ * totem_action_remote:
+ * @totem: a #TotemObject
+ * @cmd: a #TotemRemoteCommand
+ * @url: an MRL to play, or %NULL
+ *
+ * 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.
+ **/
 void
 totem_action_remote (Totem *totem, TotemRemoteCommand cmd, const char *url)
 {
@@ -2196,6 +2403,14 @@
 			NULL, NULL, totem);
 }
 
+/**
+ * totem_is_fullscreen:
+ * @totem: a #TotemObject
+ *
+ * Returns %TRUE if Totem is fullscreened.
+ *
+ * Return value: %TRUE if Totem is fullscreened
+ **/
 gboolean
 totem_is_fullscreen (Totem *totem)
 {
@@ -2204,6 +2419,14 @@
 	return (totem->controls_visibility == TOTEM_CONTROLS_FULLSCREEN);
 }
 
+/**
+ * totem_is_playing:
+ * @totem: a #TotemObject
+ *
+ * Returns %TRUE if Totem is playing a stream.
+ *
+ * Return value: %TRUE if Totem is playing a stream
+ **/
 gboolean
 totem_is_playing (Totem *totem)
 {
@@ -2223,6 +2446,14 @@
 	return totem->state == STATE_PAUSED;
 }
 
+/**
+ * totem_is_seekable:
+ * @totem: a #TotemObject
+ *
+ * Returns %TRUE if the current stream is seekable.
+ *
+ * Return value: %TRUE if the current stream is seekable
+ **/
 gboolean
 totem_is_seekable (Totem *totem)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]