rhythmbox r5637 - in trunk: . doc/reference widgets

[jmatthew svn gnome org]

Author: jmatthew
Date: Fri Mar 21 11:20:12 2008
New Revision: 5637
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5637&view=rev

Log:
2008-03-21  Jonathan Matthew  <jonathan d14n org>

	* doc/reference/rhythmbox-sections.txt:
	* widgets/rb-dialog.c:
	* widgets/rb-dialog.h:
	* widgets/rb-rating-helper.c:
	* widgets/rb-rating.c: (rb_rating_class_init):
	* widgets/rb-rating.h:
	* widgets/rb-cell-renderer-rating.c:
	* widgets/rb-cell-renderer-rating.h:
	More gtk-doc additions (15%!).
	Remove declaration of rb_error_dialog_full, which never existed.
	Fix declaration of 'rated' signal on RBCellRendererRating.


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/widgets/rb-cell-renderer-rating.c
   trunk/widgets/rb-cell-renderer-rating.h
   trunk/widgets/rb-dialog.c
   trunk/widgets/rb-dialog.h
   trunk/widgets/rb-rating-helper.c
   trunk/widgets/rb-rating.c
   trunk/widgets/rb-rating.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Fri Mar 21 11:20:12 2008
@@ -963,6 +963,9 @@
 
 <SECTION>
 <FILE>rb-rating</FILE>
+<TITLE>RBRating</TITLE>
+RBRating
+RBRatingClass
 RBRatingPrivate
 rb_rating_new
 <SUBSECTION Standard>
@@ -976,8 +979,9 @@
 
 <SECTION>
 <FILE>rb-cell-renderer-rating</FILE>
-RBCellRendererRatingPrivate
-RBCellRendererRatingClassPrivate
+<TITLE>RBCellRendererRating</TITLE>
+RBCellRendererRating
+RBCellRendererRatingClass
 rb_cell_renderer_rating_new
 <SUBSECTION Standard>
 RB_CELL_RENDERER_RATING
@@ -987,6 +991,8 @@
 RB_CELL_RENDERER_RATING_CLASS
 RB_IS_CELL_RENDERER_RATING_CLASS
 RB_CELL_RENDERER_RATING_GET_CLASS
+RBCellRendererRatingPrivate
+RBCellRendererRatingClassPrivate
 </SECTION>
 
 <SECTION>
@@ -1386,7 +1392,6 @@
 
 <SECTION>
 <FILE>rb-dialog</FILE>
-rb_error_dialog_full
 rb_error_dialog
 rb_file_chooser_new
 </SECTION>

Modified: trunk/widgets/rb-cell-renderer-rating.c
==============================================================================
--- trunk/widgets/rb-cell-renderer-rating.c	(original)
+++ trunk/widgets/rb-cell-renderer-rating.c	Fri Mar 21 11:20:12 2008
@@ -82,6 +82,15 @@
 						RB_TYPE_CELL_RENDERER_RATING, \
 						RBCellRendererRatingPrivate))
 
+
+/**
+ * SECTION:rb-cell-renderer-rating
+ * @short_description: a #GtkCellRenderer for displaying song ratings
+ *
+ * This cell renderer is used to display song ratings in the #RBEntryView,
+ * and allows the user to modify ratings directly in the track listing.
+ */
+
 enum
 {
 	PROP_0,
@@ -126,8 +135,21 @@
 	class->priv = g_new0 (RBCellRendererRatingClassPrivate, 1);
 	class->priv->pixbufs = rb_rating_pixbufs_new ();
 
+	/**
+	 * RBCellRendererRating:rating:
+	 *
+	 * The rating displayed by the renderer, as a floating point value
+	 * between 0.0 and 5.0.
+	 */
 	rb_rating_install_rating_property (object_class, PROP_RATING);
 
+	/**
+	 * RBCellRendererRating::rated:
+	 * @score: the new rating
+	 * @path: string form of the #GtkTreePath to the row that was changed
+	 *
+	 * Emitted when the user changes the rating.
+	 */
 	rb_cell_renderer_rating_signals[RATED] =
 		g_signal_new ("rated",
 			      G_OBJECT_CLASS_TYPE (object_class),

Modified: trunk/widgets/rb-cell-renderer-rating.h
==============================================================================
--- trunk/widgets/rb-cell-renderer-rating.h	(original)
+++ trunk/widgets/rb-cell-renderer-rating.h	Fri Mar 21 11:20:12 2008
@@ -51,7 +51,7 @@
 {
 	GtkCellRendererClass parent_class;
 
-	void (*rated) (RBCellRendererRating *renderer, GtkTreePath *path, double rating);
+	void (*rated) (RBCellRendererRating *renderer, const char *path, double rating);
 
 	RBCellRendererRatingClassPrivate *priv;
 

Modified: trunk/widgets/rb-dialog.c
==============================================================================
--- trunk/widgets/rb-dialog.c	(original)
+++ trunk/widgets/rb-dialog.c	Fri Mar 21 11:20:12 2008
@@ -36,6 +36,27 @@
 #include "rb-file-helpers.h"
 #include "rb-stock-icons.h"
 
+/**
+ * SECTION:rb-dialog
+ * @short_description: helper functions for creating gtk+ dialog windows
+ */
+
+/**
+ * rb_error_dialog:
+ * @parent: parent #GtkWindow for the dialog
+ * @primary: main error message
+ * @secondary: secondary error message (printf-style format string)
+ * @...: any substitution values for the secondary message
+ *
+ * Creates and displays a simple error dialog box containing a primary
+ * message in bold, larger type and a secondary message in the regular
+ * font.  Both the primary and secondary message strings should be
+ * translated.
+ *
+ * Care should be taken to avoid opening multiple error dialog boxes
+ * when a single error message (such as 'out of disk space') affects
+ * multiple items.
+ */
 void
 rb_error_dialog (GtkWindow *parent,
 		 const char *primary,
@@ -70,6 +91,24 @@
 	g_free (text);
 }
 
+/**
+ * rb_file_chooser_new:
+ * @title: title for the file chooser
+ * @parent: parent #GtkWindow for the file chooser
+ * @action: the #GtkFileChooserAction
+ * @local_only: if TRUE, don't show network locations
+ *
+ * Creates and shows a regular gtk+ file chooser dialog with
+ * a given title.  The user's music directory (typically ~/Music) is
+ * added as a shortcut.
+ * 
+ * For consistency, this should be used anywhere a file chooser is required.
+ *
+ * After creating the dialog, the caller should connect a handler to its 
+ * 'response' signal to process the user's selected files or folders.
+ *
+ * Return value: the file chooser #GtkWidget
+ */
 GtkWidget *
 rb_file_chooser_new (const char *title,
 		     GtkWindow *parent,

Modified: trunk/widgets/rb-dialog.h
==============================================================================
--- trunk/widgets/rb-dialog.h	(original)
+++ trunk/widgets/rb-dialog.h	Fri Mar 21 11:20:12 2008
@@ -29,13 +29,6 @@
 
 G_BEGIN_DECLS
 
-void		rb_error_dialog_full	(GtkWindow *parent,
-					 gboolean modal,
-					 const char *primary,
-					 const char *secondary,
-					 const char *first_button,
-					 ...) G_GNUC_PRINTF (4, 6);
-
 void		rb_error_dialog		(GtkWindow *parent,
 					 const char *primary,
 					 const char *secondary,

Modified: trunk/widgets/rb-rating-helper.c
==============================================================================
--- trunk/widgets/rb-rating-helper.c	(original)
+++ trunk/widgets/rb-rating-helper.c	Fri Mar 21 11:20:12 2008
@@ -26,12 +26,26 @@
 #include "rb-rating-helper.h"
 #include "rb-stock-icons.h"
 
+/**
+ * SECTION:rb-rating-helper
+ * @short_description: helper functions for displaying song ratings
+ *
+ * A few helper functions for dealing with ratings.  These are shared
+ * between #RBRating and #RBCellRendererRating.
+ */
+
 struct _RBRatingPixbufs {
 	GdkPixbuf *pix_star;
 	GdkPixbuf *pix_dot;
 	GdkPixbuf *pix_blank;
 };
 
+/**
+ * rb_rating_pixbufs_free:
+ * @pixbufs: #RBRatingPixbufs instance
+ *
+ * Frees a set of rating pixbufs.
+ */
 void
 rb_rating_pixbufs_free (RBRatingPixbufs *pixbufs)
 {
@@ -43,6 +57,13 @@
 		g_object_unref (pixbufs->pix_blank);
 }
 
+/**
+ * rb_rating_install_rating_property:
+ * @klass: a #GObjectClass to add the property to
+ * @prop: property index to use
+ *
+ * Installs a 'rating' property in the specified class.
+ */
 void
 rb_rating_install_rating_property (GObjectClass *klass, gulong prop)
 {
@@ -56,6 +77,15 @@
 
 }
 
+/**
+ * rb_rating_pixbufs_new:
+ *
+ * Creates and returns a structure holding a set of pixbufs
+ * to use to display ratings.
+ *
+ * Return value: #RBRatingPixbufs structure, or NULL if not all of
+ * the pixbufs could be loaded.
+ */
 RBRatingPixbufs *
 rb_rating_pixbufs_new (void)
 {
@@ -97,6 +127,23 @@
 	return NULL;
 }
 
+/**
+ * rb_rating_render_stars:
+ * @widget: a #GtkWidget to render on behalf of
+ * @window: the #GdkWindow being rendered to
+ * @pixbufs: a #RBRatingPixbufs structure
+ * @x: source X coordinate within the rating pixbufs (usually 0)
+ * @y: source Y coordinate within the rating pixbufs (usually 0)
+ * @x_offset: destination X coordinate within the window
+ * @y_offset: destination Y coordinate within the window
+ * @rating: the rating to display (between 0.0 and 5.0)
+ * @selected: TRUE if the widget is currently selected for input
+ *
+ * Renders a rating as a row of stars.  floor(@rating) large stars
+ * are drawn, followed by 5-floor(@rating) small stars.
+ *
+ * Return value: TRUE if the stars were drawn successfully
+ */
 gboolean
 rb_rating_render_stars (GtkWidget *widget,
 			GdkWindow *window,
@@ -176,6 +223,20 @@
 	return TRUE;
 }
 
+/**
+ * rb_rating_get_rating_from_widget:
+ * @widget: the #GtkWidget displaying the rating
+ * @widget_x: 
+ * @widget_width: width of the widget
+ * @current_rating: the current rating displayed in the widget
+ *
+ * Updates the rating for a widget after the user clicks on the
+ * rating.  If the user clicks on the Nth star, the rating is set
+ * to N, unless the rating is already N, in which case the rating is
+ * set to N-1.  This allows the user to set the rating to 0.
+ *
+ * Return value: the updated rating
+ */
 double
 rb_rating_get_rating_from_widget (GtkWidget *widget,
 				  gint widget_x,

Modified: trunk/widgets/rb-rating.c
==============================================================================
--- trunk/widgets/rb-rating.c	(original)
+++ trunk/widgets/rb-rating.c	Fri Mar 21 11:20:12 2008
@@ -60,7 +60,7 @@
 					   GdkEventButton *event,
 					   RBRating *rating);
 
-struct RBRatingPrivate
+struct _RBRatingPrivate
 {
 	double rating;
 	RBRatingPixbufs *pixbufs;
@@ -69,6 +69,14 @@
 G_DEFINE_TYPE (RBRating, rb_rating, GTK_TYPE_EVENT_BOX)
 #define RB_RATING_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), RB_TYPE_RATING, RBRatingPrivate))
 
+/**
+ * SECTION:rb-rating
+ * @short_description: widget for displaying song ratings
+ *
+ * This widget displays a rating (0-5 stars) and allows the user to
+ * alter the rating by clicking.
+ */
+
 enum
 {
 	PROP_0,
@@ -98,8 +106,20 @@
 	widget_class->expose_event = rb_rating_expose;
 	widget_class->size_request = rb_rating_size_request;
 
+	/**
+	 * RBRating:rating:
+	 *
+	 * The rating displayed in the widget, as a floating point value
+	 * between 0.0 and 5.0.
+	 */
 	rb_rating_install_rating_property (object_class, PROP_RATING);
 
+	/**
+	 * RBRating::rated:
+	 * @score: the new rating
+	 *
+	 * Emitted when the user changes the rating.
+	 */
 	rb_rating_signals[RATED] =
 		g_signal_new ("rated",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -180,6 +200,11 @@
 	}
 }
 
+/**
+ * rb_rating_new:
+ *
+ * Return value: a new #RBRating widget.
+ */
 RBRating *
 rb_rating_new ()
 {

Modified: trunk/widgets/rb-rating.h
==============================================================================
--- trunk/widgets/rb-rating.h	(original)
+++ trunk/widgets/rb-rating.h	Fri Mar 21 11:20:12 2008
@@ -32,21 +32,23 @@
 #define RB_IS_RATING(obj)         (GTK_CHECK_TYPE ((obj), RB_TYPE_RATING))
 #define RB_IS_RATING_CLASS(klass) (GTK_CHECK_CLASS_TYPE ((klass), RB_TYPE_RATING))
 
-typedef struct RBRatingPrivate RBRatingPrivate;
+typedef struct _RBRating RBRating;
+typedef struct _RBRatingClass RBRatingClass;
+typedef struct _RBRatingPrivate RBRatingPrivate;
 
-typedef struct
+struct _RBRating
 {
 	GtkEventBox parent;
 
 	RBRatingPrivate *priv;
-} RBRating;
+};
 
-typedef struct
+struct _RBRatingClass
 {
 	GtkEventBoxClass parent;
 
 	void (*rated) (RBRating *rating, double score);
-} RBRatingClass;
+};
 
 GtkType    rb_rating_get_type (void);