diff --git a/doc/reference/rhythmbox-sections.txt b/doc/reference/rhythmbox-sections.txt index a933e67e6..90ade41d4 100644 --- a/doc/reference/rhythmbox-sections.txt +++ b/doc/reference/rhythmbox-sections.txt @@ -446,7 +446,11 @@ RBRemovableMediaSource RBRemovableMediaSourceClass rb_removable_media_source_build_dest_uri rb_removable_media_source_track_added +rb_removable_media_source_track_add_error rb_removable_media_source_get_mime_types +rb_removable_media_source_get_format_descriptions +rb_removable_media_source_should_paste +rb_removable_media_source_should_paste_no_duplicate RB_REMOVABLE_MEDIA_SOURCE RB_IS_REMOVABLE_MEDIA_SOURCE @@ -1099,18 +1103,6 @@ rb_refstring_equal rb_refstring_get_type -
-rb-query-creator-private -CriteriaCreateWidget -CriteriaSetWidgetData -CriteriaGetWidgetData -num_property_options -num_sort_options -DEFAULT_SORTING_COLUMN -DEFAULT_SORTING_ORDER -get_box_widget_at_pos -
-
rb-dialog rb_error_dialog @@ -1338,7 +1330,9 @@ RB_IMPORT_ERRORS_SOURCE_GET_CLASS
rb-streaming-source -RBStreamingSourcePrivate +RBStreamingSource +RBStreamingSource +RBStreamingSourceClass rb_streaming_source_get_progress rb_streaming_source_set_streaming_title rb_streaming_source_set_streaming_artist @@ -1351,6 +1345,7 @@ rb_streaming_source_get_type RB_STREAMING_SOURCE_CLASS RB_IS_STREAMING_SOURCE_CLASS RB_STREAMING_SOURCE_GET_CLASS +RBStreamingSourcePrivate
@@ -1374,6 +1369,9 @@ RB_AUTO_PLAYLIST_SOURCE_GET_CLASS
rb-static-playlist-source +RBStaticPlaylistSource +RBStaticPlaylistSource +RBStaticPlaylistSourceClass rb_static_playlist_source_new rb_static_playlist_source_new_from_xml rb_static_playlist_source_load_from_xml diff --git a/lib/rb-async-queue-watch.c b/lib/rb-async-queue-watch.c index ce6b33c9f..02eda1063 100644 --- a/lib/rb-async-queue-watch.c +++ b/lib/rb-async-queue-watch.c @@ -33,6 +33,9 @@ /** * SECTION:rb-async-queue-watch * @short_description: GSource for watching a GAsyncQueue in the main loop + * + * This provides a way to feed work items to the main loop using a #GAsyncQueue + * without polling it. */ /** diff --git a/lib/rb-text-helpers.c b/lib/rb-text-helpers.c index b397bdaed..40d384697 100644 --- a/lib/rb-text-helpers.c +++ b/lib/rb-text-helpers.c @@ -33,6 +33,9 @@ /** * SECTION:rb-text-helpers * @short_description: text direction (LTR/RTL) functions + * + * Provides some helper functions for constructing strings that + * may include both left-to-right and right-to-left text. */ /* unicode direction markup characters diff --git a/rhythmdb/rb-refstring.c b/rhythmdb/rb-refstring.c index a2a42a67d..6e18ed21f 100644 --- a/rhythmdb/rb-refstring.c +++ b/rhythmdb/rb-refstring.c @@ -55,6 +55,11 @@ rb_refstring_free (RBRefString *refstr) g_free (refstr); } +/** + * rb_refstring_system_init: + * + * Sets up the refstring system. Called on startup. + */ void rb_refstring_system_init () { @@ -64,6 +69,16 @@ rb_refstring_system_init () NULL, (GDestroyNotify) rb_refstring_free); } +/** + * rb_refstring_new: + * @init: string to intern + * + * Returns an #RBRefString for the specified string. + * If one already exists, its reference count is incremented and it is + * returned. Otherwise, a new #RBRefString is created and returned. + * + * Return value: #RBRefString for @init + */ RBRefString * rb_refstring_new (const char *init) { @@ -90,6 +105,16 @@ rb_refstring_new (const char *init) return ret; } +/** + * rb_refstring_find: + * @init: string to find + * + * Returns an existing #RBRefString for @init if one exists, + * otherwise returns NULL. If an existing refstring is found, + * its reference count is increased. + * + * Return value: existing #RBRefString, or NULL + */ RBRefString * rb_refstring_find (const char *init) { @@ -105,6 +130,13 @@ rb_refstring_find (const char *init) return ret; } +/** + * rb_refstring_unref: + * @val: #RBRefString to unref + * + * Drops a reference to an #RBRefString. If this is the last + * reference, the string will be freed. + */ void rb_refstring_unref (RBRefString *val) { @@ -123,6 +155,12 @@ rb_refstring_unref (RBRefString *val) } } +/** + * rb_refstring_system_shutdown: + * + * Frees all data associated with the refstring system. + * Only called on shutdown. + */ void rb_refstring_system_shutdown (void) { @@ -130,6 +168,15 @@ rb_refstring_system_shutdown (void) g_mutex_free (rb_refstrings_mutex); } +/** + * rb_refstring_ref: + * @val: a #RBRefString to reference + * + * Increases the reference count for an existing #RBRefString. + * The refstring is returned for convenience. + * + * Return value: the same refstring + */ RBRefString * rb_refstring_ref (RBRefString *val) { @@ -142,6 +189,14 @@ rb_refstring_ref (RBRefString *val) return val; } +/** + * rb_refstring_get: + * @val: an #RBRefString + * + * Returns the actual string for a #RBRefString. + * + * Return value: underlying string, must not be freed + */ const char * rb_refstring_get (const RBRefString *val) { @@ -155,6 +210,17 @@ rb_refstring_get (const RBRefString *val) * get called often. */ +/** + * rb_refstring_get_folded: + * @val: an #RBRefString + * + * Returns the case-folded version of the string underlying @val. + * The case-folded string is cached inside the #RBRefString for + * speed. See @rb_search_fold for information on case-folding + * strings. + * + * Return value: case-folded string, must not be freed + */ const char * rb_refstring_get_folded (RBRefString *val) { @@ -182,6 +248,18 @@ rb_refstring_get_folded (RBRefString *val) return string; } +/** + * rb_refstring_get_sort_key: + * @val: an #RBRefString + * + * Returns the sort key version of the string underlying @val. + * The sort key string is cached inside the #RBRefString for speed. + * Sort key strings are not generally human readable, so don't display + * them anywhere. See @g_utf8_collate_key_for_filename for information + * on sort keys. + * + * Return value: sort key string, must not be freed. + */ const char * rb_refstring_get_sort_key (RBRefString *val) { @@ -213,6 +291,14 @@ rb_refstring_get_sort_key (RBRefString *val) return string; } +/** + * rb_refstring_hash: + * @p: an #RBRefString + * + * Hash function suitable for use with @GHashTable. + * + * Return value: hash value for the string underlying @p + */ guint rb_refstring_hash (gconstpointer p) { @@ -220,6 +306,17 @@ rb_refstring_hash (gconstpointer p) return g_str_hash (rb_refstring_get (ref)); } +/** + * rb_refstring_equal: + * @ap: an #RBRefString + * @bp: another #RBRefstring + * + * Key equality function suitable for use with #GHashTable. + * Equality checks for #RBRefString are just pointer comparisons, + * since there can only be one refstring for a given string. + * + * Return value: %TRUE if the strings are the same + */ gboolean rb_refstring_equal (gconstpointer ap, gconstpointer bp) { diff --git a/rhythmdb/rhythmdb-query.c b/rhythmdb/rhythmdb-query.c index ea990fbdc..dfd5098a0 100644 --- a/rhythmdb/rhythmdb-query.c +++ b/rhythmdb/rhythmdb-query.c @@ -54,6 +54,7 @@ #define RB_PARSE_YEAR_EQUALS RB_PARSE_EQUALS #define RB_PARSE_YEAR_GREATER RB_PARSE_GREATER #define RB_PARSE_YEAR_LESS RB_PARSE_LESS + /** * rhythmdb_query_copy: * @array: the query to copy. @@ -76,6 +77,13 @@ rhythmdb_query_copy (GPtrArray *array) return ret; } +/** + * rhythmdb_query_concatenate: + * @query1: query to append to + * @query2: query to append + * + * Appends @query2 to @query1. + */ void rhythmdb_query_concatenate (GPtrArray *query1, GPtrArray *query2) { @@ -101,6 +109,16 @@ rhythmdb_query_concatenate (GPtrArray *query1, GPtrArray *query2) } } +/** + * rhythmdb_query_parse_valist: + * @db: the #RhythmDB + * @args: the arguments to parse + * + * Converts a va_list into a parsed query in the form of a @GPtrArray. + * See @rhythmdb_query_parse for more information on the parsing process. + * + * Return value: converted query + */ GPtrArray * rhythmdb_query_parse_valist (RhythmDB *db, va_list args) { @@ -230,6 +248,16 @@ rhythmdb_query_append (RhythmDB *db, GPtrArray *query, ...) va_end (args); } +/** + * rhythmdb_query_append_params: + * @db: the #RhythmDB + * @query: the query to append to + * @type: query type + * @prop: query property + * @value: query value + * + * Appends a new query term to @query. + */ void rhythmdb_query_append_params (RhythmDB *db, GPtrArray *query, RhythmDBQueryType type, RhythmDBPropType prop, const GValue *value) @@ -273,7 +301,7 @@ rhythmdb_query_append_params (RhythmDB *db, GPtrArray *query, * @query: a query. * * Frees the query @query - **/ + */ void rhythmdb_query_free (GPtrArray *query) { @@ -373,6 +401,19 @@ write_encoded_gvalue (RhythmDB *db, g_free (quoted); } +/** + * rhythmdb_read_encoded_property: + * @db: the #RhythmDB + * @content: encoded property value + * @propid: property ID + * @val: returns the property value + * + * Converts a string containing a property value into a #GValue + * containing the native form of the property value. For boolean + * and numeric properties, this converts the string to a number. + * For #RHYTHMDB_PROP_TYPE, this looks up the entry type by name. + * For strings, no conversion is required. + */ void rhythmdb_read_encoded_property (RhythmDB *db, const char *content, @@ -433,6 +474,15 @@ rhythmdb_read_encoded_property (RhythmDB *db, } } +/** + * rhythmdb_query_serialize: + * @db: the #RhythmDB + * @query: query to serialize + * @parent: XML node to attach the query to + * + * Converts @query into XML form as a child of @parent. It can be converted + * back into a query by passing @parent to @rhythmdb_query_deserialize. + */ void rhythmdb_query_serialize (RhythmDB *db, GPtrArray *query, xmlNodePtr parent) @@ -518,6 +568,15 @@ rhythmdb_query_serialize (RhythmDB *db, GPtrArray *query, } } +/** + * rhythmdb_query_deserialize: + * @db: the #RhythmDB + * @parent: parent XML node of serialized query + * + * Converts a serialized query back into a @GPtrArray query. + * + * Return value: deserialized query. + */ GPtrArray * rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent) { @@ -629,6 +688,26 @@ rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent) * actually implements. e.g. RHYTHMDB_QUERY_YEAR_* **/ +/** + * rhythmdb_query_preprocess: + * @db: the #RhythmDB + * @query: query to preprocess + * + * Preprocesses a query to prepare it for execution. This has two main + * roles: to perform expensive data transformations once per query, rather + * than once per entry, and converting criteria to lower-level forms that + * are implemented by the database backend. + * + * For RHYTHMDB_PROP_SEARCH_MATCH, this converts the search terms into + * an array of case-folded words. + * + * When matching against case-folded properties such as + * #RHYTHMDB_PROP_TITLE_FOLDED, this case-folds the query value. + * + * When performing year-based criteria such as #RHYTHMDB_QUERY_PROP_YEAR_LESS, + * it converts the year into the Julian date such that a simple numeric + * comparison will work. + */ void rhythmdb_query_preprocess (RhythmDB *db, GPtrArray *query) { @@ -740,6 +819,16 @@ rhythmdb_query_preprocess (RhythmDB *db, GPtrArray *query) } } +/** + * rhythmdb_query_append_prop_multiple: + * @db: the #RhythmDB + * @query: the query to append to + * @propid: property ID to match + * @items: #GList of values to match against + * + * Appends a set of criteria to a query to match against any of the values + * listed in @items. + */ void rhythmdb_query_append_prop_multiple (RhythmDB *db, GPtrArray *query, RhythmDBPropType propid, GList *items) { @@ -781,6 +870,15 @@ rhythmdb_query_append_prop_multiple (RhythmDB *db, GPtrArray *query, RhythmDBPro RHYTHMDB_QUERY_END); } +/** + * rhythmdb_query_is_time_relative + * @db: the #RhythmDB + * @query: the query to check + * + * Checks if a query contains any time-relative criteria. + * + * Return value: %TRUE if time-relative criteria found + */ gboolean rhythmdb_query_is_time_relative (RhythmDB *db, GPtrArray *query) { diff --git a/rhythmdb/rhythmdb.h b/rhythmdb/rhythmdb.h index 56bce411a..498c9a90e 100644 --- a/rhythmdb/rhythmdb.h +++ b/rhythmdb/rhythmdb.h @@ -473,9 +473,9 @@ RhythmDBQuery * rhythmdb_query_copy (RhythmDBQuery *array); void rhythmdb_query_preprocess (RhythmDB *db, RhythmDBQuery *query); void rhythmdb_query_serialize (RhythmDB *db, RhythmDBQuery *query, - xmlNodePtr node); + xmlNodePtr parent); -RhythmDBQuery * rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr node); +RhythmDBQuery * rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent); char * rhythmdb_query_to_string (RhythmDB *db, RhythmDBQuery *query); diff --git a/shell/rb-history.c b/shell/rb-history.c index f91e8965e..e8b9564be 100644 --- a/shell/rb-history.c +++ b/shell/rb-history.c @@ -139,6 +139,8 @@ rb_history_class_init (RBHistoryClass *klass) * @destroyer: function to call when removing an entry from the history * @destroy_userdata: data to pass to @destroyer * + * Creates a new history instance. + * * Return value: a new #RBHistory */ RBHistory * @@ -286,7 +288,9 @@ rb_history_set_maximum_size (RBHistory *hist, guint maximum_size) * rb_history_length: * @hist: a #RBHistory * - * Return value: the number of entries in the history + * Returns the number of entries in the history. + * + * Return value: number of entries */ guint rb_history_length (RBHistory *hist) @@ -300,7 +304,9 @@ rb_history_length (RBHistory *hist) * rb_history_first: * @hist: a #RBHistory * - * Return value: the first entry in the history + * Returns the first entry in the history. + * + * Return value: first entry */ RhythmDBEntry * rb_history_first (RBHistory *hist) @@ -316,7 +322,9 @@ rb_history_first (RBHistory *hist) * rb_history_previous: * @hist: a #RBHistory * - * Return value: the #RhythmDBEntry before the current position + * Returns the #RhythmDBEntry before the current position. + * + * Return value: previous entry */ RhythmDBEntry * rb_history_previous (RBHistory *hist) @@ -333,7 +341,9 @@ rb_history_previous (RBHistory *hist) * rb_history_current: * @hist: a #RBHistory * - * Return value: the current #RhythmDBEntry, or NULL if there is no current position + * Returns the current #RhythmDBEntry, or NULL if there is no current position + * + * Return value: current entry or NULL */ RhythmDBEntry * rb_history_current (RBHistory *hist) @@ -347,7 +357,9 @@ rb_history_current (RBHistory *hist) * rb_history_next: * @hist: a #RBHistory * - * Return value: the #RhythmDBEntry after the current position + * Returns the #RhythmDBEntry after the current position + * + * Return value: next entry */ RhythmDBEntry * rb_history_next (RBHistory *hist) @@ -363,7 +375,9 @@ rb_history_next (RBHistory *hist) * rb_history_last: * @hist: a #RBHistory * - * Return value: the last #RhythmDBEntry in the history + * Returns the last #RhythmDBEntry in the history + * + * Return value: last entry */ RhythmDBEntry * rb_history_last (RBHistory *hist) @@ -677,7 +691,9 @@ rb_history_dump (RBHistory *hist) * @hist: a #RBHistory * @entry: a #RhythmDBEntry to check for * - * Return value: TRUE if the entry is present in the history list. + * Returns %TRUE if the entry is present in the history list. + * + * Return value: %TRUE if found */ gboolean rb_history_contains_entry (RBHistory *hist, RhythmDBEntry *entry) diff --git a/sources/rb-removable-media-source.c b/sources/rb-removable-media-source.c index 6d2284aa2..41543612b 100644 --- a/sources/rb-removable-media-source.c +++ b/sources/rb-removable-media-source.c @@ -27,6 +27,16 @@ * */ +/** + * SECTION:rb-removable-media-source + * @short_description: Base class for sources representing removable media + * + * This class provides support for transferring (and transcoding) entries to + * the device using drag and drop or cut and paste. The implementation must + * at minimum provide methods for returning a list of supported media types, + * and for constructing destination URIs for transfers. + */ + #include #include @@ -117,6 +127,11 @@ rb_removable_media_source_class_init (RBRemovableMediaSourceClass *klass) klass->impl_should_paste = impl_should_paste; + /** + * RBRemovableMediaSource:volume + * + * The #GVolume object that the source represents (optional) + */ g_object_class_install_property (object_class, PROP_VOLUME, g_param_spec_object ("volume", @@ -124,6 +139,11 @@ rb_removable_media_source_class_init (RBRemovableMediaSourceClass *klass) "GIO Volume", G_TYPE_VOLUME, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY)); + /** + * RBRemovableMediaSource:mount + * + * The #GMount object that the source represents + */ g_object_class_install_property (object_class, PROP_MOUNT, g_param_spec_object ("mount", @@ -593,6 +613,24 @@ impl_receive_drag (RBSource *asource, GtkSelectionData *data) return TRUE; } +/** + * rb_removable_media_source_build_dest_uri: + * @source: an #RBRemovableMediaSource + * @entry: the #RhythmDBEntry to build a URI for + * @mimetype: destination media type + * @extension: extension associated with destination media type + * + * Constructs a URI to use as the destination for a transfer or transcoding + * operation. The URI may be on the device itself, if the device is mounted + * into the normal filesystem or through gvfs, or it may be a temporary + * location used to store the file before uploading it to the device. + * + * The destination URI should conform to the device's normal URI format, + * and should use the provided extension instead of the extension from + * the source entry. + * + * Return value: constructed URI + */ char * rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source, RhythmDBEntry *entry, @@ -622,6 +660,21 @@ rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source, return uri; } +/** + * rb_removable_media_source_get_mime_types: + * @source: an #RBRemovableMediaSource + * + * Returns a #GList of allocated media type strings describing the + * formats supported by the device. If possible, these should be + * sorted in order of preference, as the first entry in the list + * for which an encoder is available will be used. + * + * Common media types include "audio/mpeg" for MP3, "application/ogg" + * for Ogg Vorbis, "audio/x-flac" for FLAC, and "audio/x-aac" for + * MP4/AAC. + * + * Return value: list of media types + */ GList * rb_removable_media_source_get_mime_types (RBRemovableMediaSource *source) { @@ -633,6 +686,16 @@ rb_removable_media_source_get_mime_types (RBRemovableMediaSource *source) return NULL; } +/** + * rb_removable_media_source_get_format_descriptions: + * @source: a #RBRemovableMediaSource + * + * Returns a #GList of allocated media format descriptions for + * the formats supported by the device. The list and the strings + * it holds must be freed by the caller. + * + * Return value: list of descriptions. + */ GList * rb_removable_media_source_get_format_descriptions (RBRemovableMediaSource *source) { @@ -660,6 +723,17 @@ rb_removable_media_source_get_format_descriptions (RBRemovableMediaSource *sourc return desc; } +/** + * rb_removablem_media_source_should_paste_no_duplicate: + * @source: an #RBRemovableMediaSource + * @entry: a #RhythmDBEntry to consider pasting + * + * This implementation of #rb_removable_media_should_paste checks for + * an existing entry on the device that matches the title, album, artist, + * and track number of the entry being considered. + * + * Return value: %TRUE if the entry should be transferred to the device. + */ gboolean rb_removable_media_source_should_paste_no_duplicate (RBRemovableMediaSource *source, RhythmDBEntry *entry) @@ -722,6 +796,18 @@ impl_should_paste (RBRemovableMediaSource *source, RhythmDBEntry *entry) return should_paste; } +/** + * rb_removable_media_source_should_paste: + * @source: an #RBRemovableMediaSource + * @entry: a #RhythmDBEntry to consider pasting + * + * Checks whether @entry should be transferred to the device. + * The source can check whether a matching entry already exists on the device, + * for instance. See @rb_removable_media_source_should_paste_no_duplicate + * a useful implementation. + * + * Return value: %TRUE if the entry should be transferred to the device + */ gboolean rb_removable_media_source_should_paste (RBRemovableMediaSource *source, RhythmDBEntry *entry) @@ -731,6 +817,22 @@ rb_removable_media_source_should_paste (RBRemovableMediaSource *source, return klass->impl_should_paste (source, entry); } +/** + * rb_removable_media_source_track_added: + * @source: an #RBRemovableMediaSource + * @entry: the source #RhythmDBEntry for the transfer + * @uri: the destination URI + * @filesize: size of the destination file + * @mimetype: media type of the destination file + * + * This is called when a transfer to the device has completed. + * If the source's impl_track_added method returns %TRUE, the destination + * URI will be added to the database using the entry type for the device. + * + * If the source uses a temporary area as the destination for transfers, + * it can instead upload the destination file to the device and create an + * entry for it, then return %FALSE. + */ void rb_removable_media_source_track_added (RBRemovableMediaSource *source, RhythmDBEntry *entry, @@ -761,6 +863,18 @@ rb_removable_media_source_track_added (RBRemovableMediaSource *source, } } +/** + * rb_removable_media_source_track_add_error: + * @source: an #RBRemovableMediaSource + * @entry: the source #RhythmDBEntry for the transfer + * @uri: the destination URI + * @error: the transfer error information + * + * This is called when a transfer fails. If the source's + * impl_track_add_error implementation returns %TRUE, an error dialog + * will be displayed to the user containing the error message, unless + * the error indicates that the destination file already exists. + */ void rb_removable_media_source_track_add_error (RBRemovableMediaSource *source, RhythmDBEntry *entry, diff --git a/sources/rb-removable-media-source.h b/sources/rb-removable-media-source.h index 60b3818ab..4deac136b 100644 --- a/sources/rb-removable-media-source.h +++ b/sources/rb-removable-media-source.h @@ -83,7 +83,7 @@ char* rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source void rb_removable_media_source_track_added (RBRemovableMediaSource *source, RhythmDBEntry *entry, const char *uri, - guint64 dest_size, + guint64 filesize, const char *mimetype); void rb_removable_media_source_track_add_error (RBRemovableMediaSource *source, RhythmDBEntry *entry, diff --git a/sources/rb-static-playlist-source.c b/sources/rb-static-playlist-source.c index 2caaa2adb..6310bba7c 100644 --- a/sources/rb-static-playlist-source.c +++ b/sources/rb-static-playlist-source.c @@ -27,6 +27,21 @@ * */ +/** + * SECTION:rb-static-playlist-source + * @short_description: Manually defined playlist class + * + * Static playlists are not defined by a query, but instead by manually selected + * and ordered tracks. + * + * This class is used for static playlists built from the user's library, and is + * also a base class for the play queue and for playlists on devices and network + * shares. + * + * It has some ability to track locations that are not yet present in the database + * and to add them to the playlist once they are added. + */ + #include "config.h" #include @@ -336,6 +351,18 @@ rb_static_playlist_source_constructed (GObject *object) gtk_widget_show_all (GTK_WIDGET (source)); } +/** + * rb_static_playlist_source_new: + * @shell: the #RBShell + * @name: the playlist name + * @sorting_name: the sorting name for the playlist (GConf key friendly) + * @local: if %TRUE, the playlist is local to the library + * @entry_type: type of database entries that can be added to the playlist. + * + * Creates a new static playlist source. + * + * Return value: new playlist. + */ RBSource * rb_static_playlist_source_new (RBShell *shell, const char *name, const char *sorting_name, gboolean local, RhythmDBEntryType entry_type) { @@ -389,6 +416,13 @@ rb_static_playlist_source_get_property (GObject *object, } } +/** + * rb_static_playlist_source_load_from_xml: + * @source: an #RBStaticPlaylistSource + * @node: XML node to load from + * + * Loads the playlist contents from the specified XML document node. + */ void rb_static_playlist_source_load_from_xml (RBStaticPlaylistSource *source, xmlNodePtr node) { @@ -410,6 +444,15 @@ rb_static_playlist_source_load_from_xml (RBStaticPlaylistSource *source, xmlNode } } +/** + * rb_static_playlist_source_new_from_xml: + * @shell: the #RBShell + * @node: XML node containing playlist entries + * + * Constructs a new playlist from the given XML document node. + * + * Return value: playlist read from XML + */ RBSource * rb_static_playlist_source_new_from_xml (RBShell *shell, xmlNodePtr node) { @@ -745,6 +788,16 @@ _add_location_cb (GFile *file, return TRUE; } +/** + * rb_static_playlist_source_add_location: + * @source: an #RBStaticPlaylistSource + * @location: location (URI) to add to the playlist + * @index: position at which to add the location (-1 to add at the end) + * + * If the location matches an entry in the database, the entry is added + * to the playlist. Otherwise, if it identifies a directory, the contents + * of that directory are added. + */ void rb_static_playlist_source_add_location (RBStaticPlaylistSource *source, const char *location, @@ -767,6 +820,14 @@ rb_static_playlist_source_add_location (RBStaticPlaylistSource *source, } +/** + * rb_static_playlist_source_add_locations: + * @source: an #RBStaticPlaylistSource + * @locations: a #GList of strings to add + * + * Adds the locations specified in @locations to the playlist. + * See @rb_static_playlist_source_add_location for details. + */ void rb_static_playlist_source_add_locations (RBStaticPlaylistSource *source, GList *locations) @@ -779,6 +840,15 @@ rb_static_playlist_source_add_locations (RBStaticPlaylistSource *source, } } +/** + * rb_static_playlist_source_remove_location: + * @source: an #RBStaticPlaylistSource + * @location: location to remove + * + * Removes the specified location from the playlist. This affects both + * the location map and the query model, whether an entry exists for the + * location or not. + */ void rb_static_playlist_source_remove_location (RBStaticPlaylistSource *source, const char *location) @@ -801,6 +871,14 @@ rb_static_playlist_source_remove_location (RBStaticPlaylistSource *source, } } +/** + * rb_static_playlist_source_add_entry: + * @source: an #RBStaticPlaylistSource + * @entry: entry to add to the playlist + * @index: position at which to add it (-1 to add at the end) + * + * Adds the specified entry to the playlist. + */ void rb_static_playlist_source_add_entry (RBStaticPlaylistSource *source, RhythmDBEntry *entry, @@ -812,6 +890,13 @@ rb_static_playlist_source_add_entry (RBStaticPlaylistSource *source, rb_static_playlist_source_add_location_internal (source, location, index); } +/** + * rb_static_playlist_source_remove_entry: + * @source: an #RBStaticPlaylistSource + * @entry: the entry to remove + * + * Removes the specified entry from the playlist. + */ void rb_static_playlist_source_remove_entry (RBStaticPlaylistSource *source, RhythmDBEntry *entry) @@ -822,6 +907,14 @@ rb_static_playlist_source_remove_entry (RBStaticPlaylistSource *source, rb_static_playlist_source_remove_location (source, location); } +/** + * rb_static_playlist_source_move_entry: + * @source: an #RBStaticPlaylistSource + * @entry: the entry to move + * @index: new location for the entry + * + * Moves an entry within the playlist. + */ void rb_static_playlist_source_move_entry (RBStaticPlaylistSource *source, RhythmDBEntry *entry, @@ -909,4 +1002,3 @@ impl_want_uri (RBSource *source, const char *uri) return 0; } - diff --git a/sources/rb-static-playlist-source.h b/sources/rb-static-playlist-source.h index aa1f61a63..02320ba86 100644 --- a/sources/rb-static-playlist-source.h +++ b/sources/rb-static-playlist-source.h @@ -45,15 +45,18 @@ G_BEGIN_DECLS #define RB_IS_STATIC_PLAYLIST_SOURCE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_STATIC_PLAYLIST_SOURCE)) #define RB_STATIC_PLAYLIST_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_STATIC_PLAYLIST_SOURCE, RBStaticPlaylistSourceClass)) -typedef struct +typedef struct _RBStaticPlaylistSource RBStaticPlaylistSource; +typedef struct _RBStaticPlaylistSourceClass RBStaticPlaylistSourceClass; + +struct _RBStaticPlaylistSource { RBPlaylistSource parent; -} RBStaticPlaylistSource; +}; -typedef struct +struct _RBStaticPlaylistSourceClass { RBPlaylistSourceClass parent; -} RBStaticPlaylistSourceClass; +}; GType rb_static_playlist_source_get_type (void); diff --git a/sources/rb-streaming-source.c b/sources/rb-streaming-source.c index 3027e1e20..4bb8d6e19 100644 --- a/sources/rb-streaming-source.c +++ b/sources/rb-streaming-source.c @@ -27,12 +27,12 @@ * */ -/* - * base class for streaming sources (internet radio, last.fm streams) - * provides handling of: - * - buffering signals (done) - * - streaming song metadata (done) - * - possibly updating play count etc.? +/** + * SECTION:rb-streaming-source + * @short_description: Base class for streaming sources such as internet radio + * + * This class provides handling of buffering signals and streaming song metadata + * common to different types of sources that play continuous streaming media. */ #include "config.h" @@ -82,7 +82,7 @@ static void extra_metadata_gather_cb (RhythmDB *db, RBStringValueMap *data, RBStreamingSource *source); -struct RBStreamingSourcePrivate +struct _RBStreamingSourcePrivate { RhythmDB *db; @@ -200,6 +200,15 @@ impl_handle_eos (RBSource *asource) return RB_SOURCE_EOF_RETRY; } +/** + * rb_streaming_source_get_progress: + * @source: a #RBStreamingSource + * @text: returns buffering status text + * @progress: returns buffering progress fraction + * + * Provides status text and progress fraction suitable for use in + * a streaming source's @rb_source_get_status method. + */ void rb_streaming_source_get_progress (RBStreamingSource *source, char **text, float *progress) { @@ -383,6 +392,14 @@ set_streaming_metadata (RBStreamingSource *source, source); } +/** + * rb_streaming_source_set_streaming_title: + * @source: a #RBStreamingSource + * @title: the new streaming song title + * + * Updates the streaming song title. Call this when an updated + * streaming song title is received from the stream. + */ void rb_streaming_source_set_streaming_title (RBStreamingSource *source, const char *title) @@ -394,6 +411,14 @@ rb_streaming_source_set_streaming_title (RBStreamingSource *source, title); } +/** + * rb_streaming_source_set_streaming_artist: + * @source: a #RBStreamingSource + * @artist: the new streaming song artist name + * + * Updates the streaming song artist name. Call this when an updated + * streaming song artist name is received from the stream. + */ void rb_streaming_source_set_streaming_artist (RBStreamingSource *source, const char *artist) @@ -405,6 +430,14 @@ rb_streaming_source_set_streaming_artist (RBStreamingSource *source, artist); } +/** + * rb_streaming_source_set_streaming_album: + * @source: a #RBStreamingSource + * @album: the new streaming song album name + * + * Updates the streaming song album name. Call this when an updated + * streaming song album name is received from the stream. + */ void rb_streaming_source_set_streaming_album (RBStreamingSource *source, const char *album) @@ -471,4 +504,3 @@ playing_entry_changed_cb (RBShellPlayer *player, g_object_unref (backend); } - diff --git a/sources/rb-streaming-source.h b/sources/rb-streaming-source.h index 9929eb6a6..e75f0511b 100644 --- a/sources/rb-streaming-source.h +++ b/sources/rb-streaming-source.h @@ -39,25 +39,27 @@ G_BEGIN_DECLS #define RB_IS_STREAMING_SOURCE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_STREAMING_SOURCE)) #define RB_STREAMING_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_STREAMING_SOURCE, RBStreamingSourceClass)) -typedef struct RBStreamingSourcePrivate RBStreamingSourcePrivate; +typedef struct _RBStreamingSource RBStreamingSource; +typedef struct _RBStreamingSourceClass RBStreamingSourceClass; +typedef struct _RBStreamingSourcePrivate RBStreamingSourcePrivate; -typedef struct +struct _RBStreamingSource { RBSource parent; RBStreamingSourcePrivate *priv; -} RBStreamingSource; +}; -typedef struct +struct _RBStreamingSourceClass { RBSourceClass parent; -} RBStreamingSourceClass; +}; GType rb_streaming_source_get_type (void); /* methods for subclasses */ void rb_streaming_source_get_progress (RBStreamingSource *source, - char **progress_text, + char **text, float *progress); void rb_streaming_source_set_streaming_title (RBStreamingSource *source, const char *title); @@ -69,4 +71,3 @@ void rb_streaming_source_set_streaming_album (RBStreamingSource *source, G_END_DECLS #endif /* __RB_STREAMING_SOURCE_H */ - diff --git a/tests/test-rhythmdb-tree-serialization.c b/tests/test-rhythmdb-tree-serialization.c index d8420eee6..f22dbc4d0 100644 --- a/tests/test-rhythmdb-tree-serialization.c +++ b/tests/test-rhythmdb-tree-serialization.c @@ -120,7 +120,7 @@ main (int argc, char **argv) db = rhythmdb_tree_new ("test.xml"); - /** + /* * TEST 1: Save with no entries */ g_print ("Test 1\n"); @@ -135,7 +135,7 @@ main (int argc, char **argv) rhythmdb_read_unlock (db); g_print ("Test 1: PASS\n"); - /** + /* * TEST 2: Save with a single entry */ g_print ("Test 1\n"); @@ -149,7 +149,7 @@ main (int argc, char **argv) rhythmdb_write_unlock (db); - /** + /* * THE END */ rhythmdb_shutdown (db); diff --git a/widgets/rb-dialog.c b/widgets/rb-dialog.c index 884f9af15..a0768068b 100644 --- a/widgets/rb-dialog.c +++ b/widgets/rb-dialog.c @@ -45,6 +45,9 @@ /** * SECTION:rb-dialog * @short_description: helper functions for creating gtk+ dialog windows + * + * This provides a couple of shortcuts for creating dialogs. If you want + * to annoy the user by displaying an error message, this is the way to do it. */ /**