rhythmbox r5686 - in trunk: . doc/reference shell

[jmatthew svn gnome org]

Author: jmatthew
Date: Wed Apr 23 13:07:11 2008
New Revision: 5686
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5686&view=rev

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

	* doc/reference/rhythmbox.types:
	Remove some types we don't need to document

	* shell/rb-play-order.c: (rb_play_order_class_init):
	* shell/rb-play-order.h:
	gtk-doc for RBPlayOrder


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox.types
   trunk/shell/rb-play-order.c
   trunk/shell/rb-play-order.h

Modified: trunk/doc/reference/rhythmbox.types
==============================================================================
--- trunk/doc/reference/rhythmbox.types	(original)
+++ trunk/doc/reference/rhythmbox.types	Wed Apr 23 13:07:11 2008
@@ -28,15 +28,7 @@
 #include "rb-playlist-manager.h"
 #include "rb-playlist-source.h"
 #include "rb-play-order.h"
-#include "rb-play-order-linear.h"
-#include "rb-play-order-linear-loop.h"
-#include "rb-play-order-queue.h"
-#include "rb-play-order-random-by-age-and-rating.h"
-#include "rb-play-order-random-by-age.h"
-#include "rb-play-order-random-by-rating.h"
-#include "rb-play-order-random-equal-weights.h"
 #include "rb-play-order-random.h"
-#include "rb-play-order-shuffle.h"
 #include "rb-play-queue-source.h"
 #include "rb-preferences.h"
 #include "rb-property-view.h"
@@ -85,8 +77,6 @@
 rb_import_errors_source_get_type
 rb_library_browser_get_type
 rb_library_source_get_type
-rb_linear_play_order_get_type
-rb_linear_play_order_loop_get_type
 rb_metadata_get_type
 rb_missing_files_source_get_type
 rb_player_error_get_type
@@ -101,11 +91,6 @@
 rb_property_view_get_type
 rb_proxy_config_get_type
 rb_query_creator_get_type
-rb_queue_play_order_get_type
-rb_random_play_order_by_age_and_rating_get_type
-rb_random_play_order_by_age_get_type
-rb_random_play_order_by_rating_get_type
-rb_random_play_order_equal_weights_get_type
 rb_random_play_order_get_type
 rb_rating_get_type
 rb_refstring_get_type
@@ -118,7 +103,6 @@
 rb_shell_player_get_type
 rb_shell_preferences_get_type
 rb_shell_ui_location_get_type
-rb_shuffle_play_order_get_type
 rb_song_info_get_type
 rb_source_eof_type_get_type
 rb_source_get_type

Modified: trunk/shell/rb-play-order.c
==============================================================================
--- trunk/shell/rb-play-order.c	(original)
+++ trunk/shell/rb-play-order.c	Wed Apr 23 13:07:11 2008
@@ -41,6 +41,26 @@
 #include "rb-preferences.h"
 #include "rb-marshal.h"
 
+/**
+ * SECTION:rb-play-order
+ * @short_description: base class for play order implementations
+ *
+ * A play order defines an ordering of the entries from a #RhythmDBQueryModel that
+ * the #RBShellPlayer uses to get the next or previous entry to play.
+ *
+ * Play order methods are invoked when changes are made to the query model, when
+ * the query model is replaced, the playing source is changed, or a new playing
+ * entry is selected.
+ *
+ * The play order must implement methods to check for, retrieve, and move to the
+ * next and previous entries in the play order.  Only the go_next and go_previous
+ * methods actually change anything.
+ *
+ * The play order should also emit the have-next-previous-changed signal to hint that
+ * the availability of either a next or previous entry in the order may have changed.
+ * This information is used to update the sensitivity of the next and previous buttons.
+ */
+
 static void rb_play_order_class_init (RBPlayOrderClass *klass);
 static void rb_play_order_init (RBPlayOrder *porder);
 static GObject *rb_play_order_constructor (GType type, guint n_construct_properties,
@@ -119,6 +139,11 @@
 	klass->has_previous = default_has_previous;
 	klass->playing_entry_removed = default_playing_entry_removed;
 
+	/**
+	 * RBPlayOrder:player:
+	 *
+	 * The #RBShellPlayer instance
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_PLAYER,
 					 g_param_spec_object ("player",
@@ -127,6 +152,11 @@
 						 	      RB_TYPE_SHELL_PLAYER,
 						 	      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RBPlayOrder:playing-entry:
+	 *
+	 * The current playing #RhythmDBEntry
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_PLAYING_ENTRY,
 					 g_param_spec_boxed ("playing-entry",
@@ -135,6 +165,16 @@
 							     RHYTHMDB_TYPE_ENTRY,
 						 	     G_PARAM_READWRITE));
 
+	/**
+	 * RBPlayOrder::have-next-previous-changed:
+	 * @porder: the #RBPlayOrder
+	 * @have_next: if %TRUE, the play order has at least one more entry
+	 * @have_previous: if %TRUE, the play order has at least one entry
+	 *    before the current entry
+	 *
+	 * Emitted as a hint to suggest that the sensitivity of next/previous
+	 * buttons may need to be updated.
+	 */
 	rb_play_order_signals[HAVE_NEXT_PREVIOUS_CHANGED] =
 		g_signal_new ("have_next_previous_changed",
 			      G_OBJECT_CLASS_TYPE (object_class),

Modified: trunk/shell/rb-play-order.h
==============================================================================
--- trunk/shell/rb-play-order.h	(original)
+++ trunk/shell/rb-play-order.h	Wed Apr 23 13:07:11 2008
@@ -60,18 +60,21 @@
 #define RB_IS_PLAY_ORDER_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_PLAY_ORDER))
 #define RB_PLAY_ORDER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_PLAY_ORDER, RBPlayOrderClass))
 
+typedef struct _RBPlayOrder RBPlayOrder;
+typedef struct _RBPlayOrderClass RBPlayOrderClass;
+
 typedef struct RBPlayOrderPrivate RBPlayOrderPrivate;
 
-typedef struct
+struct _RBPlayOrder
 {
 	GObject parent;
 
 	RBPlayOrderPrivate *priv;
-} RBPlayOrder;
+};
 
 typedef gboolean (*RBPlayOrderQueryFunc) (RBPlayOrder *porder);
 
-typedef struct
+struct _RBPlayOrderClass
 {
 	GObjectClass parent_class;
 
@@ -137,7 +140,7 @@
 
 	/* SIGNALS */
 	void (*have_next_previous_changed) (RBPlayOrder *porder, gboolean have_next, gboolean have_previous);
-} RBPlayOrderClass;
+};
 
 GType			rb_play_order_get_type		(void);
 
@@ -165,13 +168,8 @@
 RhythmDBQueryModel *    rb_play_order_get_query_model   (RBPlayOrder *porder);
 gboolean		rb_play_order_model_not_empty	(RBPlayOrder *porder);
 
-void			rb_play_order_have_next_changed (RBPlayOrder *porder, gboolean have_next);
-void			rb_play_order_have_previous_changed (RBPlayOrder *porder, gboolean have_previous);
-
 gboolean		rb_play_order_player_is_playing	(RBPlayOrder *porder);
 
-void			rb_play_order_check_if_empty (RBPlayOrder *porder, RhythmDBEntry *entry);
-
 G_END_DECLS
 
 #endif /* __RB_PLAY_ORDER_H */