GNOME.org
 

rhythmbox r5639 - in trunk: . doc/reference widgets

Author: jmatthew
Date: Fri Mar 21 14:54:15 2008
New Revision: 5639
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5639&view=rev

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

	* doc/reference/rhythmbox-sections.txt:
	* widgets/rb-property-view.c: (rb_property_view_class_init):
	* widgets/rb-property-view.h:
	* widgets/rb-query-creator.c: (rb_query_creator_class_init),
	(rb_query_creator_get_sort_order):
	* widgets/rb-query-creator.h:
	Add gtk-doc for RBPropertyView and RBQueryCreator


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/widgets/rb-property-view.c
   trunk/widgets/rb-property-view.h
   trunk/widgets/rb-query-creator.c
   trunk/widgets/rb-query-creator.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Fri Mar 21 14:54:15 2008
@@ -943,7 +943,9 @@
 
 <SECTION>
 <FILE>rb-property-view</FILE>
-RBPropertyViewPrivate
+<TITLE>RBPropertyView</TITLE>
+RBPropertyView
+RBPropertyViewClass
 rb_property_view_new
 rb_property_view_append_column_custom
 rb_property_view_set_selection_mode
@@ -962,6 +964,7 @@
 RB_PROPERTY_VIEW_CLASS
 RB_IS_PROPERTY_VIEW_CLASS
 RB_PROPERTY_VIEW_GET_CLASS
+RBPropertyViewPrivate
 </SECTION>
 
 <SECTION>
@@ -1014,6 +1017,9 @@
 
 <SECTION>
 <FILE>rb-query-creator</FILE>
+<TITLE>RBQueryCreator</TITLE>
+RBQueryCreator
+RBQueryCreatorClass
 RBQueryCreatorLimitType
 rb_query_creator_new
 rb_query_creator_new_from_query

Modified: trunk/widgets/rb-property-view.c
==============================================================================
--- trunk/widgets/rb-property-view.c	(original)
+++ trunk/widgets/rb-property-view.c	Fri Mar 21 14:54:15 2008
@@ -89,6 +89,20 @@
 
 #define RB_PROPERTY_VIEW_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), RB_TYPE_PROPERTY_VIEW, RBPropertyViewPrivate))
 
+/**
+ * SECTION:rb-property-view
+ * @short_description: a #GtkTreeView backed by a #RhythmDBPropertyModel
+ *
+ * A simple #GtkTreeView that displays the contents of a #RhythmDBPropertyModel.
+ * The first row in the tree view displays the total number of properties and entries,
+ * in the form "All 473 artists (6241)".  Each subsequent row in the tree view 
+ * displays a property value and the number of entries from the #RhythmDBQueryModel
+ * with that value.
+ *
+ * The property view itself creates a single column, but additional columns can be
+ * added.
+ */
+
 enum
 {
 	PROPERTY_SELECTED,
@@ -125,6 +139,11 @@
 	object_class->set_property = rb_property_view_set_property;
 	object_class->get_property = rb_property_view_get_property;
 
+	/**
+	 * RBPropertyView:db:
+	 *
+	 * #RhythmDB instance
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_DB,
 					 g_param_spec_object ("db",
@@ -133,6 +152,11 @@
 							      RHYTHMDB_TYPE,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RBPropertyView:prop:
+	 *
+	 * The property that is displayed in this view
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_PROP,
 					 g_param_spec_enum ("prop",
@@ -142,6 +166,11 @@
 							    RHYTHMDB_PROP_TYPE,
 							    G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RBPropertyView:title:
+	 * 
+	 * The title displayed in the header of the property view
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_TITLE,
 					 g_param_spec_string ("title",
@@ -149,6 +178,11 @@
 							      "title",
 							      "",
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+	/**
+	 * RBPropertyView:property-model:
+	 *
+	 * The #RhythmDBProperyModel backing the view.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_MODEL,
 					 g_param_spec_object ("property-model",
@@ -156,6 +190,11 @@
 							      "RhythmDBPropertyModel",
 							      RHYTHMDB_TYPE_PROPERTY_MODEL,
 							      G_PARAM_READWRITE));
+	/**
+	 * RBPropertyView:draggable:
+	 *
+	 * Whether the property view acts as a data source for drag and drop operations.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_DRAGGABLE,
 					 g_param_spec_boolean ("draggable",
@@ -164,6 +203,13 @@
 							       TRUE,
 							       G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RBPropertyView::property-activated:
+	 * @view: the #RBPropertyView
+	 * @name: the property value that was activated
+	 *
+	 * Emitted when a row in a property view is activated by double clicking.
+	 */
 	rb_property_view_signals[PROPERTY_ACTIVATED] =
 		g_signal_new ("property-activated",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -175,6 +221,13 @@
 			      1,
 			      G_TYPE_STRING);
 
+	/**
+	 * RBPropertyView::property-selected:
+	 * @view: the #RBPropertyView
+	 * @name: the property value that has been selected
+	 *
+	 * Emitted when an individual property value becomes selected.
+	 */
 	rb_property_view_signals[PROPERTY_SELECTED] =
 		g_signal_new ("property-selected",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -186,6 +239,13 @@
 			      1,
 			      G_TYPE_STRING);
 
+	/**
+	 * RBPropertyView::properties-selected:
+	 * @view: the #RBPropertyView
+	 * @properties: a list containing the selected property values
+	 *
+	 * Emitted when the set of selected property values changes.
+	 */
 	rb_property_view_signals[PROPERTIES_SELECTED] =
 		g_signal_new ("properties-selected",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -197,6 +257,13 @@
 			      1,
 			      G_TYPE_POINTER);
 
+	/**
+	 * RBPropertyView::property-selection-reset:
+	 * @view: the #RBPropertyView
+	 *
+	 * Emitted when the selection is reset.  At this point, no property values
+	 * are selected.
+	 */
 	rb_property_view_signals[SELECTION_RESET] =
 		g_signal_new ("property-selection-reset",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -206,6 +273,15 @@
 			      g_cclosure_marshal_VOID__VOID,
 			      G_TYPE_NONE,
 			      0);
+
+	/**
+	 * RBPropertyView::show-popup:
+	 * @view: the #RBPropertyView
+	 *
+	 * Emitted when a popup menu should be displayed for the property view.
+	 * The source containing the property view should connect a handler to
+	 * this signal that * displays an appropriate popup.
+	 */
 	rb_property_view_signals[SHOW_POPUP] =
 		g_signal_new ("show_popup",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -365,6 +441,16 @@
 	}
 }
 
+/**
+ * rb_property_view_new:
+ * @db: #RhythmDB instance
+ * @propid: property ID to be displayed in the property view
+ * @title: title of the property view
+ *
+ * Creates a new #RBPropertyView displaying the specified property.
+ *
+ * Return value: new property view instance
+ */
 RBPropertyView *
 rb_property_view_new (RhythmDB *db,
 		      guint propid,
@@ -389,6 +475,14 @@
 	return view;
 }
 
+/**
+ * rb_property_view_set_selection_mode:
+ * @view: a #RBPropertyView
+ * @mode: the new #GtkSelectionMode for the property view
+ *
+ * Sets the selection mode (single or multiple) for the property view>
+ * The default selection mode is single.
+ */
 void
 rb_property_view_set_selection_mode (RBPropertyView *view,
 				     GtkSelectionMode mode)
@@ -400,6 +494,12 @@
 				     mode);
 }
 
+/**
+ * rb_property_view_reset:
+ * @view: a #RBPropertyView
+ *
+ * Clears the selection in the property view.
+ */
 void
 rb_property_view_reset (RBPropertyView *view)
 {
@@ -413,6 +513,12 @@
 	g_object_unref (model);
 }
 
+/**
+ * rb_property_view_get_model:
+ * @view: a #RBPropertyView
+ * 
+ * Return value: the #RhythmDBPropertyModel backing the view; no reference is taken
+ */
 RhythmDBPropertyModel *
 rb_property_view_get_model (RBPropertyView *view)
 {
@@ -425,6 +531,13 @@
 	return model;
 }
 
+/**
+ * rb_property_view_set_model:
+ * @view: a #RBPropertyView
+ * @model: the new #RhythmDBPropertyModel for the property view
+ *
+ * Replaces the model backing the property view.
+ */
 void
 rb_property_view_set_model (RBPropertyView *view,
 			    RhythmDBPropertyModel *model)
@@ -465,6 +578,12 @@
 	}
 }
 
+/**
+ * rb_property_view_get_num_properties
+ * @view: a #RBPropertyView
+ *
+ * Return value: the number of property values present in the view
+ */
 guint
 rb_property_view_get_num_properties (RBPropertyView *view)
 {
@@ -617,6 +736,15 @@
 	g_free (val);
 }
 
+/**
+ * rb_property_view_set_selection:
+ * @view: a #RBPropertyView
+ * @vals: the values to be selected
+ *
+ * Replaces the selection in the property view.  All values in the list
+ * that are present in the view will be selected, and the view will be
+ * scrolled to show the last value selected.
+ */
 void
 rb_property_view_set_selection (RBPropertyView *view,
 				const GList *vals)
@@ -649,6 +777,13 @@
 	rb_property_view_selection_changed_cb (view->priv->selection, view);
 }
 
+/**
+ * rb_property_view_get_selection:
+ * @view: a #RBPropertyView
+ *
+ * Return value: a #GList containing the selected property values.  The list must
+ * be freed by the caller.
+ */
 GList *
 rb_property_view_get_selection (RBPropertyView *view)
 {
@@ -751,6 +886,13 @@
 	return TRUE;
 }
 
+/**
+ * rb_property_view_append_column_custom:
+ * @view: a #RBPropertyView
+ * @column: a #GtkTreeViewColumn to append to the view
+ *
+ * Appends a custom created column to the view.
+ */
 void
 rb_property_view_append_column_custom (RBPropertyView *view,
 				       GtkTreeViewColumn *column)
@@ -797,6 +939,17 @@
 	return FALSE;
 }
 
+/**
+ * rb_property_view_set_search_func:
+ * @view: a #RBPropertyView
+ * @func: tree view search function to use for this view
+ * @func_data: data to pass to the search function
+ * @notify: function to call to dispose of the data
+ *
+ * Sets the compare function for the interactive search capabilities.
+ * The function must return FALSE when the search key string matches
+ * the row it is passed.
+ */
 void
 rb_property_view_set_search_func (RBPropertyView *view,
 				  GtkTreeViewSearchEqualFunc func,
@@ -809,3 +962,4 @@
 					     func, func_data,
 					     notify);
 }
+

Modified: trunk/widgets/rb-property-view.h
==============================================================================
--- trunk/widgets/rb-property-view.h	(original)
+++ trunk/widgets/rb-property-view.h	Fri Mar 21 14:54:15 2008
@@ -39,16 +39,19 @@
 #define RB_IS_PROPERTY_VIEW_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_PROPERTY_VIEW))
 #define RB_PROPERTY_VIEW_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_PROPERTY_VIEW, RBPropertyViewClass))
 
+typedef struct _RBPropertyView RBPropertyView;
+typedef struct _RBPropertyViewClass RBPropertyViewClass;
+
 typedef struct RBPropertyViewPrivate RBPropertyViewPrivate;
 
-typedef struct
+struct _RBPropertyView
 {
 	GtkScrolledWindow parent;
 
 	RBPropertyViewPrivate *priv;
-} RBPropertyView;
+};
 
-typedef struct
+struct _RBPropertyViewClass
 {
 	GtkScrolledWindowClass parent;
 
@@ -57,7 +60,7 @@
 	void (*property_activated)	(RBPropertyView *view, const char *name);
 	void (*selection_reset)		(RBPropertyView *view);
 	void (*show_popup)		(RBPropertyView *view);
-} RBPropertyViewClass;
+};
 
 GType		rb_property_view_get_type		(void);
 

Modified: trunk/widgets/rb-query-creator.c
==============================================================================
--- trunk/widgets/rb-query-creator.c	(original)
+++ trunk/widgets/rb-query-creator.c	Fri Mar 21 14:54:15 2008
@@ -98,6 +98,24 @@
 G_DEFINE_TYPE (RBQueryCreator, rb_query_creator, GTK_TYPE_DIALOG)
 #define QUERY_CREATOR_GET_PRIVATE(o)  (G_TYPE_INSTANCE_GET_PRIVATE ((o), rb_query_creator_get_type(), RBQueryCreatorPrivate))
 
+/**
+ * SECTION:rb-query-creator
+ * @short_description: database query creator widget
+ *
+ * The query creator is used to create and edit automatic playlists.
+ * It is only capable of constructing queries that consist of a flat
+ * list of criteria.  It cannot nested criteria or represent full 
+ * boolean logic expressions.
+ *
+ * In addition to query criteria, the query creator also allows the user
+ * to specify limits on the size of the result set, in terms of the number
+ * of entries, the total duration, or the total file size; and also the
+ * order in which the results are to be sorted.
+ *
+ * The structure of the query creator is defined in the glade file 
+ * create-playlist.xml.
+ */
+
 enum
 {
 	PROP_0,
@@ -115,6 +133,11 @@
 	object_class->set_property = rb_query_creator_set_property;
 	object_class->get_property = rb_query_creator_get_property;
 
+	/**
+	 * RBQueryCreator:db:
+	 *
+	 * The #RhythmDB instance
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_DB,
 					 g_param_spec_object ("db",
@@ -123,6 +146,11 @@
 							      RHYTHMDB_TYPE,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RBQueryCreator:creating:
+	 *
+	 * TRUE if a new playlist is being created.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_CREATING,
 					 g_param_spec_boolean ("creating",
@@ -295,6 +323,12 @@
 	}
 }
 
+/**
+ * rb_query_creator_new:
+ * @db: the #RhythmDB instance
+ *
+ * Return value: new query creator widget
+ */
 GtkWidget *
 rb_query_creator_new (RhythmDB *db)
 {
@@ -433,6 +467,20 @@
 	return TRUE;
 }
 
+/**
+ * rb_query_creator_new_from_query:
+ * @db: the #RhythmDB instance
+ * @query: an existing query to start from
+ * @limit_type: the type of result set limit
+ * @limit_value: the result set limit value
+ * @sort_column: the column on which to sort query results
+ * @sort_direction: the direction in which to sort query results
+ *
+ * Constructs a new query creator with an existing query and limit and sort
+ * settings.
+ *
+ * Return value: new query creator widget
+ */
 GtkWidget *
 rb_query_creator_new_from_query (RhythmDB *db,
                                  GPtrArray *query,
@@ -455,6 +503,15 @@
 	return GTK_WIDGET (creator);
 }
 
+/**
+ * get_box_widget_at_pos:
+ * @box: #GtkBox to extract child from
+ * @pos: index of the child to retrieve
+ *
+ * Extracts a child widget from a #GtkBox.
+ *
+ * Return value: child widget from the box
+ */
 GtkWidget *
 get_box_widget_at_pos (GtkBox *box, guint pos)
 {
@@ -491,6 +548,14 @@
 	return property_type->criteria_create_widget (constrain);
 }
 
+/**
+ * rb_query_creator_get_query:
+ * @creator: #RBQueryCreator instance
+ *
+ * Constructs a database query that represents the criteria in the query creator.
+ *
+ * Return value: database query array
+ */
 GPtrArray *
 rb_query_creator_get_query (RBQueryCreator *creator)
 {
@@ -550,6 +615,16 @@
 	return query;
 }
 
+/**
+ * rb_query_creator_get_limit:
+ * @creator: #RBQueryCreator instance
+ * @type: used to return the limit type
+ * @limit: used to return the limit value
+ *
+ * Retrieves the limit type and value from the query creator.
+ * The limit value is returned as the first element in a
+ * #GValueArray.
+ */
 void
 rb_query_creator_get_limit (RBQueryCreator *creator,
 			    RhythmDBQueryModelLimitType *type,
@@ -596,9 +671,18 @@
 	}
 }
 
+/**
+ * rb_query_creator_get_sort_order:
+ * @creator: #RBQueryCreator instance
+ * @sort_key: returns the sort key name
+ * @sort_direction: returns the sort direction
+ *
+ * Retrieves the sort settings from the query creator.
+ * The sort direction is returned as a #GtkSortType value.
+ */
 void
 rb_query_creator_get_sort_order (RBQueryCreator *creator,
-                                 const char **sort_column,
+                                 const char **sort_key,
                                  gint *sort_direction)
 {
 	RBQueryCreatorPrivate *priv;
@@ -614,10 +698,10 @@
 			*sort_direction = GTK_SORT_ASCENDING;
 	}
 
-	if (sort_column != NULL) {
+	if (sort_key != NULL) {
 		int i;
 		i = gtk_option_menu_get_history (GTK_OPTION_MENU (priv->sort_menu));
-		*sort_column = sort_options[i].sort_key;
+		*sort_key = sort_options[i].sort_key;
 	}
 }
 

Modified: trunk/widgets/rb-query-creator.h
==============================================================================
--- trunk/widgets/rb-query-creator.h	(original)
+++ trunk/widgets/rb-query-creator.h	Fri Mar 21 14:54:15 2008
@@ -36,15 +36,18 @@
 #define RB_IS_QUERY_CREATOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_QUERY_CREATOR))
 #define RB_QUERY_CREATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_QUERY_CREATOR, RBQueryCreatorClass))
 
-typedef struct
+typedef struct _RBQueryCreator RBQueryCreator;
+typedef struct _RBQueryCreatorClass RBQueryCreatorClass;
+
+struct _RBQueryCreator
 {
 	GtkDialog parent;
-} RBQueryCreator;
+};
 
-typedef struct
+struct _RBQueryCreatorClass
 {
 	GtkDialogClass parent_class;
-} RBQueryCreatorClass;
+};
 
 GType		rb_query_creator_get_type	(void);
 
@@ -57,8 +60,8 @@
 GPtrArray *	rb_query_creator_get_query	(RBQueryCreator *creator);
 
 void		rb_query_creator_get_limit	(RBQueryCreator *creator,
-						 RhythmDBQueryModelLimitType *limit_type,
-						 GValueArray **limit_value);
+						 RhythmDBQueryModelLimitType *type,
+						 GValueArray **limit);
 
 void		rb_query_creator_get_sort_order (RBQueryCreator *creator, const char **sort_key, gint *sort_direction);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]