totem r5947 - in trunk: . src src/plugins

From: pwithnall svn gnome org
To: svn-commits-list gnome org
Subject: totem r5947 - in trunk: . src src/plugins
Date: Fri, 6 Feb 2009 21:06:09 +0000 (UTC)
Author: pwithnall
Date: Fri Feb  6 21:06:09 2009
New Revision: 5947
URL: http://svn.gnome.org/viewvc/totem?rev=5947&view=rev

Log:
2009-02-06  Philip Withnall  <philip tecnocode co uk>

	* src/totem-object.c (totem_object_class_init),
	(totem_object_get_property): Remove unused and broken 
error-shown
	property.
	* src/plugins/totem-plugin.c (totem_plugin_class_init):
	* src/plugins/totem-plugin.h:
	* src/totem-cell-renderer-video.c
	(totem_cell_renderer_video_class_init):
	* src/totem-interface.c:
	* src/totem-video-list.c (totem_video_list_class_init):
	* src/totem.h: Add the rest of the plugin-visible API 
documentation.
	(Closes: #524119)



Modified:
   trunk/ChangeLog
   trunk/src/plugins/totem-plugin.c
   trunk/src/plugins/totem-plugin.h
   trunk/src/totem-cell-renderer-video.c
   trunk/src/totem-interface.c
   trunk/src/totem-object.c
   trunk/src/totem-video-list.c
   trunk/src/totem.h

Modified: trunk/src/plugins/totem-plugin.c
==============================================================================
--- trunk/src/plugins/totem-plugin.c	(original)
+++ trunk/src/plugins/totem-plugin.c	Fri Feb  6 21:06:09 2009
@@ -25,6 +25,16 @@
  *
  */
 
+/**
+ * SECTION:totem-plugin
+ * @short_description: plugin
+ * @stability: Unstable
+ * @include: totem-plugin.h
+ *
+ * #TotemPlugin is a general-purpose architecture for adding plugins to Totem, with
+ * derived support for different programming languages.
+ **/
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -91,7 +101,14 @@
 	klass->create_configure_dialog = NULL;
 	klass->is_configurable = is_configurable;
 
-	/* this should be a construction property, but due to the python plugin hack can't be */
+	/* FIXME: this should be a construction property, but due to the python plugin hack can't be */
+	/**
+	 * TotemPlugin:name:
+	 *
+	 * The plugin's name. It should be a construction property, but due to the Python plugin hack, it
+	 * can't be: do not change the name after construction. Should be the same as used for naming plugin-
+	 * specific resources.
+	 **/
 	g_object_class_install_property (object_class,
 					 PROP_NAME,
 					 g_param_spec_string ("name",

Modified: trunk/src/plugins/totem-plugin.h
==============================================================================
--- trunk/src/plugins/totem-plugin.h	(original)
+++ trunk/src/plugins/totem-plugin.h	Fri Feb  6 21:06:09 2009
@@ -78,8 +78,13 @@
 	TotemPluginBooleanFunc		is_configurable;
 } TotemPluginClass;
 
-typedef enum
-{
+/**
+ * TotemPluginError:
+ * @TOTEM_PLUGIN_ERROR_ACTIVATION: there was an error activating the plugin
+ *
+ * Error codes returned by #TotemPlugin operations.
+ **/
+typedef enum {
 	TOTEM_PLUGIN_ERROR_ACTIVATION
 } TotemPluginError;
 

Modified: trunk/src/totem-cell-renderer-video.c
==============================================================================
--- trunk/src/totem-cell-renderer-video.c	(original)
+++ trunk/src/totem-cell-renderer-video.c	Fri Feb  6 21:06:09 2009
@@ -26,6 +26,16 @@
  *
  */
 
+/**
+ * SECTION:totem-cell-renderer-video
+ * @short_description: video cell renderer
+ * @stability: Unstable
+ * @include: totem-cell-renderer-video.h
+ *
+ * #TotemCellRendererVideo is a #GtkCellRenderer for rendering video thumbnails, typically in a #TotemVideoList.
+ * It supports drawing a video thumbnail, and the video's title underneath.
+ **/
+
 #include "config.h"
 
 #include <glib.h>
@@ -94,17 +104,41 @@
 	renderer_class->get_size = totem_cell_renderer_video_get_size;
 	renderer_class->render = totem_cell_renderer_video_render;
 
+	/**
+	 * TotemCellRendererVideo:thumbnail:
+	 *
+	 * A #GdkPixbuf of a thumbnail of the video to display. When rendered, it will scale to the width of the parent #GtkTreeView,
+	 * so can be as large as reasonable.
+	 **/
 	g_object_class_install_property (object_class, PROP_THUMBNAIL,
 				g_param_spec_object ("thumbnail", NULL, NULL,
 					GDK_TYPE_PIXBUF, G_PARAM_READWRITE));
+
+	/**
+	 * TotemCellRendererVideo:title:
+	 *
+	 * The title of the video, as it should be displayed. The default title is "Unknown video".
+	 **/
 	g_object_class_install_property (object_class, PROP_TITLE,
 				g_param_spec_string ("title", NULL, NULL,
 					_("Unknown video"), G_PARAM_READWRITE));
+
+	/**
+	 * TotemCellRendererVideo:alignment:
+	 *
+	 * A #PangoAlignment giving the text alignment for the video title. The default is %PANGO_ALIGN_CENTER.
+	 **/
 	g_object_class_install_property (object_class, PROP_ALIGNMENT,
 				g_param_spec_enum ("alignment", NULL, NULL,
 					PANGO_TYPE_ALIGNMENT,
 					PANGO_ALIGN_CENTER,
 					G_PARAM_READWRITE));
+
+	/**
+	 * TotemCellRendererVideo:use-placeholder:
+	 *
+	 * If %TRUE, a placeholder image should be used for the video thumbnail if a :thumbnail isn't provided.
+	 **/
 	g_object_class_install_property (object_class, PROP_USE_PLACEHOLDER,
 				g_param_spec_boolean ("use-placeholder", NULL, NULL,
 					FALSE, G_PARAM_READWRITE));

Modified: trunk/src/totem-interface.c
==============================================================================
--- trunk/src/totem-interface.c	(original)
+++ trunk/src/totem-interface.c	Fri Feb  6 21:06:09 2009
@@ -129,6 +129,18 @@
 	g_free (browser);
 }
 
+/**
+ * totem_interface_error_with_link:
+ * @title: the error title
+ * @reason: the error reason (secondary text)
+ * @uri: the URI to open
+ * @label: a label for the URI's button, or %NULL to use @uri as the label
+ * @parent: the error dialogue's parent #GtkWindow
+ * @totem: a #TotemObject
+ *
+ * Display a modal error dialogue like totem_interface_error_dialog(),
+ * but add a button which will open @uri in a browser window.
+ **/
 void
 totem_interface_error_with_link (const char *title, const char *reason,
 				 const char *uri, const char *label, GtkWindow *parent, Totem *totem)

Modified: trunk/src/totem-object.c
==============================================================================
--- trunk/src/totem-object.c	(original)
+++ trunk/src/totem-object.c	Fri Feb  6 21:06:09 2009
@@ -26,6 +26,15 @@
  *
  */
 
+/**
+ * SECTION:totem-object
+ * @short_description: main object
+ * @stability: Unstable
+ * @include: totem-object.h
+ *
+ * #TotemObject is the core object of Totem; a singleton which controls all Totem's main functions.
+ **/
+
 #include "config.h"
 
 #include <glib-object.h>
@@ -46,7 +55,6 @@
 	PROP_STREAM_LENGTH,
 	PROP_SEEKABLE,
 	PROP_CURRENT_TIME,
-	PROP_ERROR_SHOWN,
 	PROP_CURRENT_MRL
 };
 
@@ -82,30 +90,69 @@
 	object_class->get_property = totem_object_get_property;
 	object_class->finalize = totem_object_finalize;
 
+	/**
+	 * TotemObject:fullscreen:
+	 *
+	 * If %TRUE, Totem is in fullscreen mode.
+	 **/
 	g_object_class_install_property (object_class, PROP_FULLSCREEN,
 					 g_param_spec_boolean ("fullscreen", NULL, NULL,
 							       FALSE, G_PARAM_READABLE));
+
+	/**
+	 * TotemObject:playing:
+	 *
+	 * If %TRUE, Totem is playing an audio or video file.
+	 **/
 	g_object_class_install_property (object_class, PROP_PLAYING,
 					 g_param_spec_boolean ("playing", NULL, NULL,
 							       FALSE, G_PARAM_READABLE));
+
+	/**
+	 * TotemObject:stream-length:
+	 *
+	 * The length of the current stream, in milliseconds.
+	 **/
 	g_object_class_install_property (object_class, PROP_STREAM_LENGTH,
 					 g_param_spec_int64 ("stream-length", NULL, NULL,
 							     G_MININT64, G_MAXINT64, 0,
 							     G_PARAM_READABLE));
+
+	/**
+	 * TotemObject:current-time:
+	 *
+	 * The player's position (time) in the current stream, in milliseconds.
+	 **/
 	g_object_class_install_property (object_class, PROP_CURRENT_TIME,
 					 g_param_spec_int64 ("current-time", NULL, NULL,
 							     G_MININT64, G_MAXINT64, 0,
 							     G_PARAM_READABLE));
+
+	/**
+	 * TotemObject:seekable:
+	 *
+	 * If %TRUE, the current stream is seekable.
+	 **/
 	g_object_class_install_property (object_class, PROP_SEEKABLE,
 					 g_param_spec_boolean ("seekable", NULL, NULL,
 							       FALSE, G_PARAM_READABLE));
-	g_object_class_install_property (object_class, PROP_ERROR_SHOWN,
-					 g_param_spec_boolean ("error-shown", NULL, NULL,
-							       FALSE, G_PARAM_READABLE));
+
+	/**
+	 * TotemObject:current-mrl:
+	 *
+	 * The MRL of the current stream.
+	 **/
 	g_object_class_install_property (object_class, PROP_CURRENT_MRL,
 					 g_param_spec_string ("current-mrl", NULL, NULL,
 							      NULL, G_PARAM_READABLE));
 
+	/**
+	 * TotemObject::file-opened:
+	 * @totem: the #TotemObject which received the signal
+	 * @mrl: the MRL of the opened stream
+	 *
+	 * The ::file-opened signal is emitted when a new stream is opened by Totem.
+	 */
 	totem_table_signals[FILE_OPENED] =
 		g_signal_new ("file-opened",
 				G_TYPE_FROM_CLASS (object_class),
@@ -115,6 +162,12 @@
 				g_cclosure_marshal_VOID__STRING,
 				G_TYPE_NONE, 1, G_TYPE_STRING);
 
+	/**
+	 * TotemObject::file-closed:
+	 * @totem: the #TotemObject which received the signal
+	 *
+	 * The ::file-closed signal is emitted when Totem closes a stream.
+	 */
 	totem_table_signals[FILE_CLOSED] =
 		g_signal_new ("file-closed",
 				G_TYPE_FROM_CLASS (object_class),
@@ -124,6 +177,17 @@
 				g_cclosure_marshal_VOID__VOID,
 				G_TYPE_NONE, 0, G_TYPE_NONE);
 
+	/**
+	 * TotemObject::metadata-updated:
+	 * @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
+	 *
+	 * The ::metadata-updated signal is emitted when the metadata of a stream is updated, typically
+	 * when it's being loaded.
+	 */
 	totem_table_signals[METADATA_UPDATED] =
 		g_signal_new ("metadata-updated",
 				G_TYPE_FROM_CLASS (object_class),
@@ -183,9 +247,6 @@
 	case PROP_SEEKABLE:
 		g_value_set_boolean (value, totem_is_seekable (totem));
 		break;
-	case PROP_ERROR_SHOWN:
-		//g_value_set_boolean (value, XXX);
-		break;
 	case PROP_CURRENT_MRL:
 		g_value_set_string (value, totem->mrl);
 		break;
@@ -271,6 +332,15 @@
 	return GTK_WIDGET (totem->bvw);
 }
 
+/**
+ * totem_get_video_widget_backend_name:
+ * @totem: a #TotemObject
+ *
+ * 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()).
+ *
+ * Return value: the name string of the backend video widget
+ **/
 char *
 totem_get_video_widget_backend_name (Totem *totem)
 {
@@ -293,6 +363,15 @@
 	return bacon_video_widget_get_current_time (totem->bvw);
 }
 
+/**
+ * totem_add_to_playlist_and_play:
+ * @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
+ *
+ * Add @uri to the playlist and play it immediately.
+ **/
 void
 totem_add_to_playlist_and_play (Totem *totem,
 				const char *uri,
@@ -323,6 +402,14 @@
 	}
 }
 
+/**
+ * totem_get_current_mrl:
+ * @totem: a #TotemObject
+ *
+ * Get the MRL of the current stream, or %NULL if nothing's playing.
+ *
+ * Return value: the MRL of the current stream
+ **/
 char *
 totem_get_current_mrl (Totem *totem)
 {
@@ -359,6 +446,14 @@
 	return totem_playlist_get_current_title (totem->playlist, &custom);
 }
 
+/**
+ * totem_set_current_subtitle:
+ * @totem: a #TotemObject
+ * @subtitle_uri: the URI of the subtitle file to add
+ *
+ * Add the @subtitle_uri subtitle file to the playlist, setting it as the subtitle for the current
+ * playlist entry.
+ **/
 void
 totem_set_current_subtitle (Totem *totem, const char *subtitle_uri)
 {

Modified: trunk/src/totem-video-list.c
==============================================================================
--- trunk/src/totem-video-list.c	(original)
+++ trunk/src/totem-video-list.c	Fri Feb  6 21:06:09 2009
@@ -26,6 +26,16 @@
  *
  */
 
+/**
+ * SECTION:totem-video-list
+ * @short_description: video list
+ * @stability: Unstable
+ * @include: totem-video-list.h
+ *
+ * #TotemVideoList is a #GtkTreeView designed for listing videos by their thumbnails using #TotemCellRendererVideo.
+ * It supports tooltips, loading the videos by activating tree view rows, and #GtkUIManager actions in the popup menu.
+ **/
+
 #include "config.h"
 
 #include <glib.h>
@@ -79,6 +89,13 @@
 
 G_DEFINE_TYPE (TotemVideoList, totem_video_list, GTK_TYPE_TREE_VIEW)
 
+/**
+ * totem_video_list_new:
+ *
+ * Creates a new #TotemVideoList with default properties.
+ *
+ * Return value: a new #TotemVideoList
+ **/
 TotemVideoList *
 totem_video_list_new (void)
 {
@@ -103,18 +120,48 @@
 	object_class->set_property = totem_video_list_set_property;
 	object_class->get_property = totem_video_list_get_property;
 	object_class->dispose = totem_video_list_dispose;
+	klass->starting_video = default_starting_video_cb;
 
+	/**
+	 * TotemVideoList:tooltip-column:
+	 *
+	 * The column number of the #GtkTreeModel column containing tooltips to be displayed by the video list.
+	 * If it's set to -1, no tooltips shall be displayed.
+	 **/
 	g_object_class_install_property (object_class, PROP_TOOLTIP_COLUMN,
 				g_param_spec_int ("tooltip-column", NULL, NULL,
 					-1, G_MAXINT, -1, G_PARAM_READWRITE));
+
+	/**
+	 * TotemVideoList:mrl-column:
+	 *
+	 * The column number of the #GtkTreeModel column containing MRLs of the videos in the video list.
+	 * If it's set to -1, video rows will not be activatable (e.g. by double-clicking them).
+	 **/
 	g_object_class_install_property (object_class, PROP_MRL_COLUMN,
 				g_param_spec_int ("mrl-column", NULL, NULL,
 					-1, G_MAXINT, -1, G_PARAM_READWRITE));
+
+	/**
+	 * TotemVideoList:totem:
+	 *
+	 * A #TotemObject for integration purposes.
+	 **/
+	/* FIXME: Is there no better way to do this? */
 	g_object_class_install_property (object_class, PROP_TOTEM,
 				g_param_spec_object ("totem", NULL, NULL,
 					TOTEM_TYPE_OBJECT, G_PARAM_READWRITE));
 
-	klass->starting_video = default_starting_video_cb;
+	/**
+	 * TotemVideoList::starting-video:
+	 * @video_list: the #TotemVideoList which received the signal
+	 * @tree_path: the #GtkTreePath of the video row about to be played
+	 *
+	 * The ::starting-video signal is emitted when a video row is activated, just before the video is
+	 * added to the playlist. It allows for the video's MRL in the #GtkTreeModel to be modified, for example.
+	 *
+	 * If this returns %TRUE, the video will be played; otherwise, it will not.
+	 */
 	totem_video_list_table_signals[STARTING_VIDEO] = g_signal_new ("starting-video",
 				G_TYPE_FROM_CLASS (object_class),
 				G_SIGNAL_RUN_LAST,
@@ -434,6 +481,14 @@
 	g_list_free (l);
 }
 
+/**
+ * totem_video_list_get_ui_manager:
+ * @self: a #TotemVideoList
+ *
+ * Returns the #GtkUIManager in use by @self.
+ *
+ * Return value: @self's #GtkUIManager
+ **/
 GtkUIManager *
 totem_video_list_get_ui_manager (TotemVideoList *self)
 {

Modified: trunk/src/totem.h
==============================================================================
--- trunk/src/totem.h	(original)
+++ trunk/src/totem.h	Fri Feb  6 21:06:09 2009
@@ -37,6 +37,42 @@
 
 G_BEGIN_DECLS
 
+/**
+ * TotemRemoteCommand:
+ * @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
+ *
+ * Represents a command which can be sent to a running Totem instance remotely.
+ **/
 typedef enum {
 	TOTEM_REMOTE_COMMAND_UNKNOWN,
 	TOTEM_REMOTE_COMMAND_PLAY,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]