rhythmbox r5639 - in trunk: . doc/reference widgets
- From: jmatthew svn gnome org
- To: svn-commits-list gnome org
- Subject: rhythmbox r5639 - in trunk: . doc/reference widgets
- Date: Fri, 21 Mar 2008 14:54:15 +0000 (GMT)
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]