rhythmbox r5772 - in trunk: . doc/reference shell sources

[jmatthew svn gnome org]

Author: jmatthew
Date: Mon Jun 23 08:26:49 2008
New Revision: 5772
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5772&view=rev

Log:
2008-06-23  Jonathan Matthew  <jonathan d14n org>

	* doc/reference/rhythmbox-sections.txt:
	* shell/rb-playlist-manager.c: (rb_playlist_manager_class_init):
	* shell/rb-playlist-manager.h:
	* sources/rb-library-source.c:
	* sources/rb-library-source.h:
	gtk-doc for RBPlaylistManager and RBLibrarySource.
	also remove rb_library_source_add_location, as it was unused.


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/shell/rb-playlist-manager.c
   trunk/shell/rb-playlist-manager.h
   trunk/sources/rb-library-source.c
   trunk/sources/rb-library-source.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Mon Jun 23 08:26:49 2008
@@ -171,10 +171,10 @@
 
 <SECTION>
 <FILE>rb-playlist-manager</FILE>
+<TITLE>RBPlaylistManager</TITLE>
 RBPlaylistManager
 RBPlaylistManagerClass
 RBPlaylistManagerError
-RBPlaylistManagerPrivate
 rb_playlist_manager_new
 rb_playlist_manager_shutdown
 rb_playlist_manager_parse_file
@@ -190,6 +190,7 @@
 rb_playlist_manager_remove_from_playlist
 rb_playlist_manager_export_playlist
 <SUBSECTION Standard>
+RBPlaylistManagerPrivate
 RB_PLAYLIST_MANAGER
 RB_IS_PLAYLIST_MANAGER
 RB_TYPE_PLAYLIST_MANAGER
@@ -493,10 +494,12 @@
 
 <SECTION>
 <FILE>rb-library-source</FILE>
-RBLibrarySourcePrivate
+<TITLE>RBLibrarySource</TITLE>
+RBLibrarySource
+RBLibrarySourceClass
 rb_library_source_new
-rb_library_source_add_location
 <SUBSECTION Standard>
+RBLibrarySourcePrivate
 RB_LIBRARY_SOURCE
 RB_IS_LIBRARY_SOURCE
 RB_TYPE_LIBRARY_SOURCE

Modified: trunk/shell/rb-playlist-manager.c
==============================================================================
--- trunk/shell/rb-playlist-manager.c	(original)
+++ trunk/shell/rb-playlist-manager.c	Mon Jun 23 08:26:49 2008
@@ -28,6 +28,15 @@
  *
  */
 
+/**
+ * SECTION:rb-playlist-manager
+ * @short_description: Playlist management object
+ *
+ * The playlist manager loads and saves the on-disk playlist file, provides
+ * UI actions and a DBus interface for dealing with playlists, and internal
+ * interfaces for creating playlists.
+ */
+
 #include "config.h"
 
 #include <string.h>
@@ -214,6 +223,14 @@
 							      "RBSourceList",
 							      RB_TYPE_SOURCELIST,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+	/**
+	 * RBPlaylistManager::playlist-added:
+	 * @manager: the #RBPlaylistManager
+	 * @source: the new #RBSource
+	 *
+	 * Emitted when a playlist is added, including when being loaded
+	 * from the user's playlist file.
+	 */
 	rb_playlist_manager_signals[PLAYLIST_ADDED] =
 		g_signal_new ("playlist_added",
 			      RB_TYPE_PLAYLIST_MANAGER,
@@ -224,6 +241,13 @@
 			      G_TYPE_NONE,
 			      1, G_TYPE_OBJECT);
 
+	/**
+	 * RBPlaylistManager::playlist-created:
+	 * @manager: the #RBPlaylistManager
+	 * @source: the newly created playlist #RBSource
+	 *
+	 * Emitted when a new playlist is created.
+	 */
 	rb_playlist_manager_signals[PLAYLIST_CREATED] =
 		g_signal_new ("playlist_created",
 			      RB_TYPE_PLAYLIST_MANAGER,
@@ -234,6 +258,13 @@
 			      G_TYPE_NONE,
 			      1, G_TYPE_OBJECT);
 
+	/**
+	 * RBPlaylistManager::load-start:
+	 * @manager: the #RBPlaylistManager
+	 *
+	 * Emitted when the playlist manager starts loading the user's
+	 * playlist file.
+	 */
 	rb_playlist_manager_signals[PLAYLIST_LOAD_START] =
 		g_signal_new ("load_start",
 			      RB_TYPE_PLAYLIST_MANAGER,
@@ -243,6 +274,13 @@
 			      g_cclosure_marshal_VOID__VOID,
 			      G_TYPE_NONE,
 			      0, G_TYPE_NONE);
+	/**
+	 * RBPlaylistManager::load-finish
+	 * @manager: the #RBPlaylistManager
+	 *
+	 * Emitted when the playlist manager finishes loading the user's
+	 * playlist file.
+	 */
 	rb_playlist_manager_signals[PLAYLIST_LOAD_FINISH] =
 		g_signal_new ("load_finish",
 			      RB_TYPE_PLAYLIST_MANAGER,
@@ -268,6 +306,13 @@
 	mgr->priv->saving = 0;
 }
 
+/**
+ * rb_playlist_manager_shutdown:
+ * @mgr: the #RBPlaylistManager
+ *
+ * Shuts down the playlist manager, making sure any outstanding playlist save
+ * operation finishes.
+ */
 void
 rb_playlist_manager_shutdown (RBPlaylistManager *mgr)
 {
@@ -499,6 +544,16 @@
 	}
 }
 
+/**
+ * rb_playlist_manager_new:
+ * @shell: the #RBShell
+ * @sourcelist: the #RBSourceList
+ * @playlists_file: the full path to the playlist file to load
+ *
+ * Creates the #RBPlaylistManager instance
+ *
+ * Return value: the #RBPlaylistManager
+ */
 RBPlaylistManager *
 rb_playlist_manager_new (RBShell *shell,
 			 RBSourceList *sourcelist,
@@ -1686,7 +1741,7 @@
  * Deletes the specified playlist.  Will fail if no playlist with
  * that name exists. This is part of the playlist manager dbus interface.
  *
- * Return vaule: TRUE if successful.
+ * Return value: TRUE if successful.
  */
 gboolean
 rb_playlist_manager_delete_playlist (RBPlaylistManager *mgr,

Modified: trunk/shell/rb-playlist-manager.h
==============================================================================
--- trunk/shell/rb-playlist-manager.h	(original)
+++ trunk/shell/rb-playlist-manager.h	Mon Jun 23 08:26:49 2008
@@ -54,16 +54,19 @@
 
 GQuark rb_playlist_manager_error_quark (void);
 
+typedef struct _RBPlaylistManager RBPlaylistManager;
+typedef struct _RBPlaylistManagerClass RBPlaylistManagerClass;
+
 typedef struct RBPlaylistManagerPrivate RBPlaylistManagerPrivate;
 
-typedef struct
+struct _RBPlaylistManager
 {
 	GObject parent;
 
 	RBPlaylistManagerPrivate *priv;
-} RBPlaylistManager;
+};
 
-typedef struct
+struct _RBPlaylistManagerClass
 {
 	GObjectClass parent_class;
 
@@ -72,7 +75,7 @@
 	void	(*playlist_created) (RBPlaylistManager *manager, RBSource *source);
 	void	(*load_start) (RBPlaylistManager *manager);
 	void	(*load_finish) (RBPlaylistManager *manager);
-} RBPlaylistManagerClass;
+};
 
 typedef enum
 {

Modified: trunk/sources/rb-library-source.c
==============================================================================
--- trunk/sources/rb-library-source.c	(original)
+++ trunk/sources/rb-library-source.c	Mon Jun 23 08:26:49 2008
@@ -29,6 +29,23 @@
  *
  */
 
+/**
+ * SECTION:rb-library-source
+ * @short_description: main library source, containing all local songs
+ *
+ * The library source contains all local songs that have been imported
+ * into the database.
+ *
+ * It provides a preferences page for configuring the library location,
+ * the directory structure to use when transferring new files into
+ * the library from another source, and the preferred audio encoding
+ * to use.
+ *
+ * If multiple library locations are set in GConf, the library source
+ * creates a child source for each location, which will only show
+ * files found under that location.
+ */
+
 #include "config.h"
 
 #include <string.h>
@@ -333,6 +350,14 @@
 	return G_OBJECT (source);
 }
 
+/**
+ * rb_library_source_new:
+ * @shell: the #RBShell
+ *
+ * Creates and returns the #RBLibrarySource instance
+ *
+ * Return value: the #RBLibrarySource
+ */
 RBSource *
 rb_library_source_new (RBShell *shell)
 {
@@ -654,75 +679,6 @@
 	return g_strdup (CONF_STATE_PANED_POSITION);
 }
 
-static void
-rb_library_source_add_location_entry_changed_cb (GtkEntry *entry,
-						 GtkWidget *target)
-{
-	gtk_widget_set_sensitive (target, g_utf8_strlen (gtk_entry_get_text (GTK_ENTRY (entry)), -1) > 0);
-}
-
-void
-rb_library_source_add_location (RBLibrarySource *source, GtkWindow *win)
-{
-	GladeXML *xml = rb_glade_xml_new ("uri.glade",
-					  "open_uri_dialog_content",
-					  source);
-	GtkWidget *content, *uri_widget, *open_button;
-	GtkWidget *dialog = gtk_dialog_new_with_buttons (_("Add Location"),
-							 win,
-							 GTK_DIALOG_MODAL | GTK_DIALOG_NO_SEPARATOR,
-							 GTK_STOCK_CANCEL,
-							 GTK_RESPONSE_CANCEL,
-							 NULL);
-
-	g_return_if_fail (dialog != NULL);
-
-	open_button = gtk_dialog_add_button (GTK_DIALOG (dialog),
-					     GTK_STOCK_OPEN,
-					     GTK_RESPONSE_OK);
-	gtk_widget_set_sensitive (open_button, FALSE);
-
-	gtk_dialog_set_default_response (GTK_DIALOG (dialog),
-					 GTK_RESPONSE_OK);
-	gtk_container_set_border_width (GTK_CONTAINER (dialog), 5);
-	gtk_box_set_spacing (GTK_BOX (GTK_DIALOG (dialog)->vbox), 2);
-
-	gtk_window_set_resizable (GTK_WINDOW (dialog), FALSE);
-
-	content = glade_xml_get_widget (xml, "open_uri_dialog_content");
-
-	g_return_if_fail (content != NULL);
-
-	gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->vbox),
-			    content, FALSE, FALSE, 0);
-	gtk_container_set_border_width (GTK_CONTAINER (content), 5);
-
-	uri_widget = glade_xml_get_widget (xml, "uri");
-
-	g_return_if_fail (uri_widget != NULL);
-
-	g_signal_connect_object (G_OBJECT (uri_widget),
-				 "changed",
-				 G_CALLBACK (rb_library_source_add_location_entry_changed_cb),
-				 open_button, 0);
-
-	if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_OK) {
-		char *uri = gtk_editable_get_chars (GTK_EDITABLE (uri_widget), 0, -1);
-		if (uri != NULL) {
-			GnomeVFSURI *vfsuri = gnome_vfs_uri_new (uri);
-			if (vfsuri != NULL) {
-				rhythmdb_add_uri (source->priv->db, uri);
-				gnome_vfs_uri_unref (vfsuri);
-			} else {
-				rb_debug ("invalid uri: \"%s\"", uri);
-			}
-
-		}
-	}
-	gtk_widget_destroy (GTK_WIDGET (dialog));
-
-}
-
 static gboolean
 impl_receive_drag (RBSource *asource, GtkSelectionData *data)
 {

Modified: trunk/sources/rb-library-source.h
==============================================================================
--- trunk/sources/rb-library-source.h	(original)
+++ trunk/sources/rb-library-source.h	Mon Jun 23 08:26:49 2008
@@ -46,26 +46,27 @@
 #define RB_IS_LIBRARY_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_LIBRARY_SOURCE))
 #define RB_LIBRARY_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_LIBRARY_SOURCE, RBLibrarySourceClass))
 
+typedef struct _RBLibrarySource RBLibrarySource;
+typedef struct _RBLibrarySourceClass RBLibrarySourceClass;
+
 typedef struct RBLibrarySourcePrivate RBLibrarySourcePrivate;
 
-typedef struct
+struct _RBLibrarySource
 {
 	RBBrowserSource parent;
 
 	RBLibrarySourcePrivate *priv;
-} RBLibrarySource;
+};
 
-typedef struct
+struct _RBLibrarySourceClass
 {
 	RBBrowserSourceClass parent;
-} RBLibrarySourceClass;
+};
 
 GType		rb_library_source_get_type		(void);
 
 RBSource *      rb_library_source_new			(RBShell *shell);
 
-void		rb_library_source_add_location		(RBLibrarySource *source, GtkWindow *win);
-
 G_END_DECLS
 
 #endif /* __RB_LIBRARY_SOURCE_H */