GNOME.org
 

rhythmbox r5632 - in trunk: . doc/reference widgets

Author: jmatthew
Date: Thu Mar 20 12:29:26 2008
New Revision: 5632
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5632&view=rev

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

	* doc/reference/rhythmbox-sections.txt:
	* widgets/rb-library-browser.c: (rb_library_browser_class_init):
	* widgets/rb-library-browser.h:
	* widgets/rb-search-entry.c: (rb_search_entry_class_init),
	(rb_search_entry_searching):
	* widgets/rb-search-entry.h:
	Add gtk-doc for RBLibraryBrowser and RBSearchEntry.

	* widgets/rb-uri-dialog.c: (rb_uri_dialog_class_init):
	Fix signal identifiers so they actually show up.


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/widgets/rb-library-browser.c
   trunk/widgets/rb-library-browser.h
   trunk/widgets/rb-search-entry.c
   trunk/widgets/rb-search-entry.h
   trunk/widgets/rb-uri-dialog.c

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Thu Mar 20 12:29:26 2008
@@ -774,11 +774,15 @@
 
 <SECTION>
 <FILE>rb-search-entry</FILE>
+<TITLE>RBSearchEntry</TITLE>
+RBSearchEntry
+RBSearchEntryClass
 RBSearchEntryPrivate
 rb_search_entry_new
 rb_search_entry_clear
 rb_search_entry_set_text
 rb_search_entry_searching
+rb_search_entry_grab_focus
 <SUBSECTION Standard>
 RB_SEARCH_ENTRY
 RB_IS_SEARCH_ENTRY
@@ -1334,3 +1338,28 @@
 RB_IS_URI_DIALOG_CLASS
 RB_URI_DIALOG_GET_CLASS
 </SECTION>
+
+<SECTION>
+<FILE>rb-library-browser</FILE>
+<TITLE>RBLibraryBrowser</TITLE>
+RBLibraryBrowser
+RBLibraryBrowserClass
+rb_library_browser_new
+rb_library_browser_set_model
+rb_library_browser_reset
+rb_library_browser_construct_query
+rb_library_browser_get_property_views
+rb_library_browser_get_property_view
+rb_library_browser_has_selection
+rb_library_browser_set_selection
+<SUBSECTION Standard>
+RB_LIBRARY_BROWSER
+RB_IS_LIBRARY_BROWSER
+RB_TYPE_LIBRARY_BROWSER
+rb_library_browser_get_type
+RB_LIBRARY_BROWSER_CLASS
+RB_IS_LIBRARY_BROWSER_CLASS
+RB_LIBRARY_BROWSER_GET_CLASS
+</SECTION>
+
+

Modified: trunk/widgets/rb-library-browser.c
==============================================================================
--- trunk/widgets/rb-library-browser.c	(original)
+++ trunk/widgets/rb-library-browser.c	Thu Mar 20 12:29:26 2008
@@ -67,6 +67,27 @@
 G_DEFINE_TYPE (RBLibraryBrowser, rb_library_browser, GTK_TYPE_HBOX)
 #define RB_LIBRARY_BROWSER_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), RB_TYPE_LIBRARY_BROWSER, RBLibraryBrowserPrivate))
 
+/**
+ * SECTION:rb-library-browser
+ * @short_description: album/artist/genre browser widget
+ * @include: rb-library-browser.h
+ *
+ * This widget contains a set of #RBPropertyView<!-- -->s backed by
+ * #RhythmDBPropertyModel<!-- -->s and constructs a chain of
+ * #RhythmDBQueryModel<!-- -->s to perform filtering of the entries
+ * in a source.
+ *
+ * It operates on an input query model, containing the full set of
+ * entries that may be displayed in the source, and produces an
+ * output query model containing those entries that match the current
+ * selection.
+ *
+ * When the selection in any of the property views changes, or when
+ * #rb_library_browser_reset or #rb_library_browser_set_selection are
+ * called to manipulate the selection, the query chain is rebuilt
+ * asynchronously to update the property views.
+ */
+
 typedef struct
 {
 	RBLibraryBrowser *widget;
@@ -121,6 +142,11 @@
 	object_class->set_property = rb_library_browser_set_property;
 	object_class->get_property = rb_library_browser_get_property;
 
+	/**
+	 * RBLibraryBrowser:db:
+	 *
+	 * #RhythmDB instance
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_DB,
 					 g_param_spec_object ("db",
@@ -128,6 +154,14 @@
 							      "RhythmDB instance",
 							      RHYTHMDB_TYPE,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+	/**
+	 * RBLibraryBrowser:input-model:
+	 *
+	 * This #RhythmDBQueryModel defines the set of entries that
+	 * the browser filters.  This property is not writeable.
+	 * To set a new input query model, use 
+	 * #rb_library_browser_set_model.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_INPUT_MODEL,
 					 g_param_spec_object ("input-model",
@@ -135,6 +169,18 @@
 							      "input RhythmDBQueryModel instance",
 							      RHYTHMDB_TYPE_QUERY_MODEL,
 							      G_PARAM_READABLE));
+	/**
+	 * RBLibraryBrowser:output-model:
+	 *
+	 * This #RhythmDBQueryModel contains the filtered set of
+	 * entries.  It is a subset of the entries contained in the
+	 * input model.  This should be used as the model backing
+	 * the source's entry view.
+	 *
+	 * Sources using this widget should connect to the notify
+	 * signal for this property, updating their entry view when
+	 * it changes.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_OUTPUT_MODEL,
 					 g_param_spec_object ("output-model",
@@ -142,6 +188,10 @@
 							      "output RhythmDBQueryModel instance",
 							      RHYTHMDB_TYPE_QUERY_MODEL,
 							      G_PARAM_READABLE));
+	/**
+	 * RBLibraryBrowser:entry-type:
+	 * The type of entries to use in the browser.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_ENTRY_TYPE,
 					 g_param_spec_boxed ("entry-type",
@@ -287,6 +337,13 @@
 	}
 }
 
+/**
+ * rb_library_browser_new:
+ * @db: the #RhythmDB instance
+ * @entry_type: the entry type to use in the browser
+ *
+ * Return value: a new RBLibraryBrowser
+ */
 RBLibraryBrowser *
 rb_library_browser_new (RhythmDB *db,
 			RhythmDBEntryType entry_type)
@@ -378,6 +435,14 @@
 	rb_property_view_set_selection (view, NULL);
 }
 
+/**
+ * rb_library_browser_reset:
+ * @widget: a #RBLibraryBrowser
+ *
+ * Clears all selections in the browser.
+ *
+ * Return value: TRUE if anything was changed
+ */
 gboolean
 rb_library_browser_reset (RBLibraryBrowser *widget)
 {
@@ -408,6 +473,14 @@
 					     selections);
 }
 
+/**
+ * rb_library_browser_construct_query:
+ * @widget: a #RBLibraryBrowser
+ *
+ * Constructs a #RhythmDBQuery from the current selections in the browser.
+ *
+ * Return value: a #RhythmDBQuery constructed from the current selection.
+ */
 RhythmDBQuery *
 rb_library_browser_construct_query (RBLibraryBrowser *widget)
 {
@@ -427,6 +500,12 @@
 	return query;
 }
 
+/**
+ * rb_library_browser_has_selection:
+ * @widget: a #RBLibraryBrowser
+ *
+ * Return value: TRUE if any items in the browser are selected.
+ */
 gboolean
 rb_library_browser_has_selection (RBLibraryBrowser *widget)
 {
@@ -634,6 +713,14 @@
 	g_free (data);
 }
 
+/**
+ * rb_library_browser_set_selection:
+ * @widget: a #RBLibraryBrowser
+ * @type: the property for which to set the selection
+ * @selection: a list of strings to select
+ *
+ * Replaces any current selection for the specified property.
+ */
 void
 rb_library_browser_set_selection (RBLibraryBrowser *widget,
 				  RhythmDBPropType type,
@@ -684,6 +771,13 @@
 	priv->rebuild_data = rebuild_data;
 }
 
+/**
+ * rb_library_browser_get_property_views:
+ * @widget: a #RBLibraryBrowser
+ *
+ * Return value: a GList containing the #RBPropertyView<!-- -->s
+ *  in the browser.
+ */
 GList*
 rb_library_browser_get_property_views (RBLibraryBrowser *widget)
 {
@@ -692,6 +786,14 @@
 	return rb_collate_hash_table_values (priv->property_views);
 }
 
+/**
+ * rb_library_browser_get_property_view:
+ * @widget: a #RBLibraryBrowser
+ * @type: the property
+ *
+ * Return value: the #RBPropertyView for the specified property, or
+ *  NULL if there isn't one
+ */
 RBPropertyView *
 rb_library_browser_get_property_view (RBLibraryBrowser *widget,
 				      RhythmDBPropType type)
@@ -703,6 +805,18 @@
 	return view;
 }
 
+/**
+ * rb_library_browser_set_model:
+ * @widget: a #RBLibraryBrowser
+ * @model: the new input #RhythmDBQueryModel
+ * @query_pending: if TRUE, the caller promises to run a
+ *  query to populate the input query model.
+ *
+ * Specifies a new input query model for the browser.
+ * This should be the query model constructed from the 
+ * current search text, or the basic query model for the 
+ * source if there is no search text.
+ */
 void
 rb_library_browser_set_model (RBLibraryBrowser *widget,
 			      RhythmDBQueryModel *model,

Modified: trunk/widgets/rb-library-browser.h
==============================================================================
--- trunk/widgets/rb-library-browser.h	(original)
+++ trunk/widgets/rb-library-browser.h	Thu Mar 20 12:29:26 2008
@@ -37,15 +37,18 @@
 #define RB_IS_LIBRARY_BROWSER_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_LIBRARY_BROWSER))
 #define RB_LIBRARY_BROWSER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_LIBRARY_BROWSER, RBLibraryBrowserClass))
 
-typedef struct
+typedef struct _RBLibraryBrowser RBLibraryBrowser;
+typedef struct _RBLibraryBrowserClass RBLibraryBrowserClass;
+
+struct _RBLibraryBrowser
 {
 	GtkHBox parent;
-} RBLibraryBrowser;
+};
 
-typedef struct
+struct _RBLibraryBrowserClass
 {
 	GtkHBoxClass parent;
-} RBLibraryBrowserClass;
+};
 
 GType			rb_library_browser_get_type (void);
 RBLibraryBrowser *	rb_library_browser_new      (RhythmDB *db,
@@ -64,7 +67,7 @@
 gboolean 		rb_library_browser_has_selection (RBLibraryBrowser *widget);
 void 			rb_library_browser_set_selection (RBLibraryBrowser *widget,
 							  RhythmDBPropType type,
-							  GList *list);
+							  GList *selection);
 
 G_END_DECLS
 

Modified: trunk/widgets/rb-search-entry.c
==============================================================================
--- trunk/widgets/rb-search-entry.c	(original)
+++ trunk/widgets/rb-search-entry.c	Thu Mar 20 12:29:26 2008
@@ -57,6 +57,21 @@
 G_DEFINE_TYPE (RBSearchEntry, rb_search_entry, GTK_TYPE_HBOX)
 #define RB_SEARCH_ENTRY_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), RB_TYPE_SEARCH_ENTRY, RBSearchEntryPrivate))
 
+/**
+ * SECTION:RBSearchEntry:
+ * @short_description: text entry widget for the search box
+ *
+ * The search entry contains a label and a text entry box.
+ * The text entry box (a SexyIconEntry) contains an icon
+ * that acts as a 'clear' button.
+ *
+ * Signals are emitted when the search text changes,
+ * arbitrarily rate-limited to one every 300ms.
+ *
+ * When the text entry widget is non-empty, its colours are
+ * changed to display the text in black on yellow.
+ */
+
 enum
 {
 	SEARCH,
@@ -73,6 +88,14 @@
 
 	object_class->finalize = rb_search_entry_finalize;
 
+	/**
+	 * RBSearchEntry::search:
+	 * @text: search text
+	 *
+	 * Emitted when the search text changes.  A signal
+	 * handler must initiate a search on the current
+	 * source.
+	 */
 	rb_search_entry_signals[SEARCH] =
 		g_signal_new ("search",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -83,6 +106,12 @@
 			      G_TYPE_NONE,
 			      1,
 			      G_TYPE_STRING);
+
+	/**
+	 * RBSearchEntry::activate:
+	 *
+	 * Emitted when the entry is activated.
+	 */
 	rb_search_entry_signals[ACTIVATE] =
 		g_signal_new ("activate",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -153,6 +182,11 @@
 	G_OBJECT_CLASS (rb_search_entry_parent_class)->finalize (object);
 }
 
+/**
+ * rb_search_entry_new:
+ *
+ * Return value: new search entry widget.
+ */
 RBSearchEntry *
 rb_search_entry_new (void)
 {
@@ -167,6 +201,13 @@
 	return entry;
 }
 
+/**
+ * rb_search_entry_clear:
+ * @entry: a #RBSearchEntry
+ *
+ * Clears the search entry text.  The 'search' signal will
+ * be emitted.
+ */
 void
 rb_search_entry_clear (RBSearchEntry *entry)
 {
@@ -182,6 +223,14 @@
 	entry->priv->clearing = FALSE;
 }
 
+/**
+ * rb_search_entry_set_text:
+ * @entry: a #RBSearchEntry
+ * @text: new search text
+ *
+ * Sets the text in the search entry box.
+ * The 'search' signal will be emitted.
+ */
 void
 rb_search_entry_set_text (RBSearchEntry *entry, const char *text)
 {
@@ -263,8 +312,14 @@
 	return FALSE;
 }
 
+/**
+ * rb_search_entry_searching:
+ * @entry: a #RBSearchEntry
+ *
+ * Return value: TRUE if there is search text
+ */
 gboolean
-rb_search_entry_searching(RBSearchEntry *entry)
+rb_search_entry_searching (RBSearchEntry *entry)
 {
 	return strcmp ("", gtk_entry_get_text (GTK_ENTRY (entry->priv->entry))) != 0;
 }
@@ -276,6 +331,12 @@
 	g_signal_emit (G_OBJECT (entry), rb_search_entry_signals[ACTIVATE], 0);
 }
 
+/**
+ * rb_search_entry_grab_focus:
+ * @entry: a #RBSearchEntry
+ *
+ * Grabs input focus for the text entry widget.
+ */
 void
 rb_search_entry_grab_focus (RBSearchEntry *entry)
 {

Modified: trunk/widgets/rb-search-entry.h
==============================================================================
--- trunk/widgets/rb-search-entry.h	(original)
+++ trunk/widgets/rb-search-entry.h	Thu Mar 20 12:29:26 2008
@@ -33,22 +33,25 @@
 #define RB_IS_SEARCH_ENTRY_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_SEARCH_ENTRY))
 #define RB_SEARCH_ENTRY_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_SEARCH_ENTRY, RBSearchEntryClass))
 
+typedef struct _RBSearchEntry RBSearchEntry;
+typedef struct _RBSearchEntryClass RBSearchEntryClass;
+
 typedef struct RBSearchEntryPrivate RBSearchEntryPrivate;
 
-typedef struct
+struct _RBSearchEntry
 {
 	GtkHBox parent;
 
 	RBSearchEntryPrivate *priv;
-} RBSearchEntry;
+};
 
-typedef struct
+struct _RBSearchEntryClass
 {
 	GtkHBoxClass parent;
 
 	void (*search) (RBSearchEntry *view, const char *text);
 	void (*activate) (RBSearchEntry *entry);
-} RBSearchEntryClass;
+};
 
 GType		rb_search_entry_get_type (void);
 

Modified: trunk/widgets/rb-uri-dialog.c
==============================================================================
--- trunk/widgets/rb-uri-dialog.c	(original)
+++ trunk/widgets/rb-uri-dialog.c	Thu Mar 20 12:29:26 2008
@@ -96,7 +96,7 @@
 	object_class->get_property = rb_uri_dialog_get_property;
 
 	/**
-	 * rb-uri-dialog:label:
+	 * RBURIDialog:label:
 	 *
 	 * The label displayed in the dialog.
 	 */
@@ -109,7 +109,7 @@
 					                      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
 	/**
-	 * rb-uri-dialog::location-added:
+	 * RBURIDialog::location-added:
 	 * @uri: URI entered
 	 *
 	 * Emitted when the user has entered a URI into the dialog.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]