![]() |
![]() |
![]() |
Rhythmbox Development Reference Manual | ![]() |
---|---|---|---|---|
RBSource; RBSourceClass; enum RBSourceEOFType; #define RB_SOURCE_ICON_SIZE void rb_source_notify_filter_changed (RBSource *source); void rb_source_notify_status_changed (RBSource *source); void rb_source_update_play_statistics (RBSource *source, RhythmDB *db, RhythmDBEntry *entry); void rb_source_set_pixbuf (RBSource *source, GdkPixbuf *pixbuf); void rb_source_get_status (RBSource *source, char **text, char **progress_text, float *progress); gboolean rb_source_can_browse (RBSource *source); char* rb_source_get_browser_key (RBSource *source); void rb_source_browser_toggled (RBSource *source, gboolean enabled); RBEntryView* rb_source_get_entry_view (RBSource *source); GList* rb_source_get_property_views (RBSource *source); gboolean rb_source_can_rename (RBSource *source); gboolean rb_source_can_search (RBSource *source); void rb_source_search (RBSource *source, const char *text); void rb_source_reset_filters (RBSource *source); GtkWidget* rb_source_get_config_widget (RBSource *source, RBShellPreferences *prefs); gboolean rb_source_can_cut (RBSource *source); gboolean rb_source_can_delete (RBSource *source); gboolean rb_source_can_move_to_trash (RBSource *source); gboolean rb_source_can_copy (RBSource *source); gboolean rb_source_can_paste (RBSource *source); gboolean rb_source_can_add_to_queue (RBSource *source); gboolean rb_source_can_show_properties (RBSource *source); GList* rb_source_cut (RBSource *source); GList* rb_source_copy (RBSource *source); void rb_source_paste (RBSource *source, GList *entries); void rb_source_delete (RBSource *source); void rb_source_add_to_queue (RBSource *source, RBSource *queue); void rb_source_move_to_trash (RBSource *source); void rb_source_song_properties (RBSource *source); gboolean rb_source_try_playlist (RBSource *source); guint rb_source_want_uri (RBSource *source, const char *uri); gboolean rb_source_uri_is_source (RBSource *source, const char *uri); gboolean rb_source_add_uri (RBSource *source, const char *uri, const char *title, const char *genre); gboolean rb_source_can_pause (RBSource *source); RBSourceEOFType rb_source_handle_eos (RBSource *source); gboolean rb_source_receive_drag (RBSource *source, GtkSelectionData *data); gboolean rb_source_show_popup (RBSource *source); void rb_source_delete_thyself (RBSource *source); void rb_source_activate (RBSource *source); void rb_source_deactivate (RBSource *source); GList* rb_source_get_ui_actions (RBSource *source); GList* rb_source_get_search_actions (RBSource *source); GList* rb_source_gather_selected_properties (RBSource *source, RhythmDBPropType prop); void rb_source_set_hidden_when_empty (RBSource *source, gboolean hidden);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBox +----GtkHBox +----RBSource +----RBPlaylistSource +----RBBrowserSource +----RBImportErrorsSource +----RBMissingFilesSource
"base-query-model" RhythmDBQueryModel* : Read "entry-type" RhythmDBEntryType* : Read / Write / Construct Only "hidden-when-empty" gboolean : Read / Write "icon" GdkPixbuf* : Read / Write "name" gchar* : Read / Write "play-order" RBPlayOrder* : Read "plugin" RBPlugin* : Read / Write "query-model" RhythmDBQueryModel* : Read / Write "shell" RBShell* : Read / Write / Construct Only "source-group" RBSourceGroup* : Read / Write / Construct Only "ui-manager" GtkUIManager* : Read "visibility" gboolean : Read / Write
This class provides methods for requesting information about the UI capabilities of the source, and defines the expectations that apply to all sources - that they will provide RBEntryView and RhythmDBQueryModel objects, mostly.
Many of the methods on this class come in can_do_x and do_x pairs. When can_do_x always returns FALSE, the class does not need to implement the do_x method.
Useful subclasses include RBBrowserSource, which includes a RBLibraryBrowser and takes care of constructing an RBEntryView too; RBRemovableMediaSource, which takes care of many aspects of implementing a source that represents a removable device; and RBPlaylistSource, which provides functionality for playlist-like sources.
typedef struct { GtkHBoxClass parent; /* signals */ void (*status_changed) (RBSource *source); void (*filter_changed) (RBSource *source); void (*deleted) (RBSource *source); void (*artistalbum_changed) (RBSource *source); /* methods */ void (*impl_get_status) (RBSource *source, char **text, char **progress_text, float *progress); gboolean (*impl_can_browse) (RBSource *source); char * (*impl_get_browser_key) (RBSource *source); void (*impl_browser_toggled) (RBSource *source, gboolean enabled); RBEntryView * (*impl_get_entry_view) (RBSource *source); GList * (*impl_get_property_views) (RBSource *source); gboolean (*impl_can_rename) (RBSource *source); gboolean (*impl_can_search) (RBSource *source); void (*impl_search) (RBSource *source, const char *text); void (*impl_reset_filters) (RBSource *source); GtkWidget * (*impl_get_config_widget)(RBSource *source, RBShellPreferences *prefs); gboolean (*impl_can_cut) (RBSource *source); gboolean (*impl_can_delete) (RBSource *source); gboolean (*impl_can_move_to_trash) (RBSource *source); gboolean (*impl_can_copy) (RBSource *source); gboolean (*impl_can_paste) (RBSource *source); gboolean (*impl_can_add_to_queue)(RBSource *source); GList * (*impl_cut) (RBSource *source); GList * (*impl_copy) (RBSource *source); void (*impl_paste) (RBSource *source, GList *entries); void (*impl_delete) (RBSource *source); void (*impl_add_to_queue) (RBSource *source, RBSource *queue); void (*impl_move_to_trash) (RBSource *source); void (*impl_song_properties) (RBSource *source); gboolean (*impl_try_playlist) (RBSource *source); guint (*impl_want_uri) (RBSource *source, const char *uri); gboolean (*impl_add_uri) (RBSource *source, const char *uri, const char *title, const char *genre); gboolean (*impl_uri_is_source) (RBSource *source, const char *uri); gboolean (*impl_can_pause) (RBSource *source); RBSourceEOFType (*impl_handle_eos) (RBSource *source); gboolean (*impl_have_url) (RBSource *source); gboolean (*impl_receive_drag) (RBSource *source, GtkSelectionData *data); gboolean (*impl_show_popup) (RBSource *source); void (*impl_delete_thyself) (RBSource *source); void (*impl_activate) (RBSource *source); void (*impl_deactivate) (RBSource *source); GList * (*impl_get_ui_actions) (RBSource *source); GList * (*impl_get_search_actions) (RBSource *source); } RBSourceClass;
typedef enum { RB_SOURCE_EOF_ERROR, RB_SOURCE_EOF_STOP, RB_SOURCE_EOF_RETRY, RB_SOURCE_EOF_NEXT, } RBSourceEOFType;
void rb_source_notify_filter_changed (RBSource *source);
Source implementations call this when their filter state changes
|
a RBSource |
void rb_source_notify_status_changed (RBSource *source);
Source implementations call this when their status bar information changes.
|
a RBSource |
void rb_source_update_play_statistics (RBSource *source, RhythmDB *db, RhythmDBEntry *entry);
Updates play count and play time statistics for a database entry. Sources containing entries that do not normally reach EOS should call this for an entry when it is no longer being played.
|
a RBSource |
|
the RhythmDB instance |
|
the RhythmDBEntry to update |
void rb_source_set_pixbuf (RBSource *source, GdkPixbuf *pixbuf);
Sets the pixbuf for the source.
|
a RBSource |
|
new GdkPixbuf for the source |
void rb_source_get_status (RBSource *source, char **text, char **progress_text, float *progress);
Retrieves the details to display in the status bar for the source. If the progress value returned is less than zero, the progress bar will pulse. If the progress value is greater than or equal to 1, the progress bar will be hidden.
|
a RBSource |
|
holds the returned status text (allocated) |
|
holds the returned text for the progress bar (allocated) |
|
holds the progress value |
gboolean rb_source_can_browse (RBSource *source);
|
a RBSource |
Returns : |
TRUE if this source has a browser |
char* rb_source_get_browser_key (RBSource *source);
|
a RBSource |
Returns : |
the GConf key that determines browser visibility for this source (allocated) |
void rb_source_browser_toggled (RBSource *source, gboolean enabled);
Called when the visibility of the browser changes.
|
a RBSource |
|
TRUE if the browser should be visible |
RBEntryView* rb_source_get_entry_view (RBSource *source);
|
a RBSource |
Returns : |
the RBEntryView instance for the source |
GList* rb_source_get_property_views (RBSource *source);
|
a RBSource |
Returns : |
a list containing the RBPropertyViews that make up the browser for this source, if any. |
gboolean rb_source_can_rename (RBSource *source);
|
a RBSource. |
Returns : |
TRUE if this source can be renamed |
gboolean rb_source_can_search (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source can be searched using the search box |
void rb_source_search (RBSource *source, const char *text);
Updates the source with new search text. The source should recreate the database query that feeds into the browser (if any).
|
a RBSource |
|
new search text |
void rb_source_reset_filters (RBSource *source);
Clears all filters (browser selections, etc.) in this source.
|
a RBSource |
GtkWidget* rb_source_get_config_widget (RBSource *source, RBShellPreferences *prefs);
Source implementations can use this to return an optional configuration widget. The widget will be displayed in a page in the preferences dialog.
|
a RBSource |
|
the RBShellPreferences object |
Returns : |
configuration widget |
gboolean rb_source_can_cut (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source supports the typical cut (as in cut-and-paste) operation. |
gboolean rb_source_can_delete (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source allows the user to delete a selected set of entries. |
gboolean rb_source_can_move_to_trash (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source allows the user to trash the files backing a selected set of entries. |
gboolean rb_source_can_copy (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source supports the copy part of a copy-and-paste operation. |
gboolean rb_source_can_paste (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source supports the typical paste (as in cut-and-paste) operation. |
gboolean rb_source_can_add_to_queue (RBSource *source);
|
a RBSource |
Returns : |
TRUE if this source can add the current selected set of entries to the play queue |
gboolean rb_source_can_show_properties (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the source can display a properties window for the currently selected entry (or set of entries) |
GList* rb_source_cut (RBSource *source);
Removes the currently selected entries from the source and returns them so they can be pasted into another source.
|
a RBSource |
Returns : |
a list of RhythmDBEntry objects cut from the source. |
GList* rb_source_copy (RBSource *source);
|
a RBSource |
Returns : |
a list containing the currently selected entries from the source. |
void rb_source_paste (RBSource *source, GList *entries);
Adds a list of entries previously cut or copied from another source.
|
a RBSource |
|
a list of RhythmDBEntry objects to paste in |
void rb_source_delete (RBSource *source);
Deletes the currently selected entries from the source.
|
a RBSource |
void rb_source_add_to_queue (RBSource *source, RBSource *queue);
Adds the currently selected entries to the end of the play queue.
void rb_source_move_to_trash (RBSource *source);
Trashes the files backing the currently selected set of entries. In general, this should use rhythmdb_entry_move_to_trash to perform the actual trash operation.
|
a RBSource |
void rb_source_song_properties (RBSource *source);
Displays a properties window for the currently selected entries.
|
a RBSource |
gboolean rb_source_try_playlist (RBSource *source);
|
a RBSource |
Returns : |
TRUE if the playback URIs for entries in the source should be parsed as playlists, rather than just played. |
guint rb_source_want_uri (RBSource *source, const char *uri);
Returns an indication of how much the source wants to handle the specified URI. 100 is the highest usual value, and should only be used when the URI can only be associated with this source. 0 should be used when the URI does not match the source at all.
|
a RBSource |
|
a URI for the source to consider |
Returns : |
value from 0 to 100 indicating how much the source wants this URI. |
gboolean rb_source_uri_is_source (RBSource *source, const char *uri);
Checks if the URI matches the source itself. A source should return TRUE here if the URI points to the device that the source represents, for example.
|
a RBSource |
|
a URI for the source to consider |
Returns : |
TRUE if the URI identifies the source itself. |
gboolean rb_source_add_uri (RBSource *source, const char *uri, const char *title, const char *genre);
Adds an entry corresponding to the URI to the source. The
title
and genre
parameters are not really used.
|
a RBSource |
|
a URI to add |
|
theoretically, the title of the entity the URI points to |
|
theoretically, the genre of the entity the URI points to |
Returns : |
TRUE if the URI was successfully added to the source |
gboolean rb_source_can_pause (RBSource *source);
|
a RBSource |
Returns : |
TRUE if playback of entries from the source can be paused. |
RBSourceEOFType rb_source_handle_eos (RBSource *source);
|
a RBSource |
Returns : |
how EOS events should be handled for entries from this source |
gboolean rb_source_receive_drag (RBSource *source, GtkSelectionData *data);
This is called when the user drags something to the source. Depending on the drag data type, the data might be a list of RhythmDBEntry objects, a list of URIs, or a list of album or artist or genre names.
|
a RBSource |
|
the selection data |
Returns : |
TRUE if the source accepted the drag data |
gboolean rb_source_show_popup (RBSource *source);
Called when the user performs an action (such as right-clicking) that should result in a popup menu being displayed for the source.
|
a RBSource |
Returns : |
TRUE if the source managed to display a popup |
void rb_source_delete_thyself (RBSource *source);
This is called when the source should delete itself. The 'deleted' signal will be emitted, which removes the source from the source list. This will not actually dispose of the source object, so reference counting must still be handled correctly.
|
a RBSource |
void rb_source_activate (RBSource *source);
Called when the source is selected in the source list.
|
a RBSource |
void rb_source_deactivate (RBSource *source);
Called when the source is deselected in the source list.
|
a RBSource |
GList* rb_source_get_ui_actions (RBSource *source);
Returns a list of UI action names. Items for these actions will be added to the toolbar.
|
a RBSource |
Returns : |
list of action names |
GList* rb_source_get_search_actions (RBSource *source);
Returns a list of UI action names. Buttons for these actions will be added to the search bar. The source must identify the selected search action when constructing a database query for searching
|
a RBSource |
Returns : |
list of search actions |
GList* rb_source_gather_selected_properties (RBSource *source, RhythmDBPropType prop);
Returns a list containing the values of the specified property from the selected entries in the source. This is used to implement the 'browse this artist' (etc.) actions.
|
a RBSource |
|
property for which to gather selection |
Returns : |
list of property values |
"base-query-model"
property"base-query-model" RhythmDBQueryModel* : Read
The unfiltered query model for the source, containing all entries in the source. Source classes should override this if they perform filtering based on the search box or a browser.
"entry-type"
property"entry-type" RhythmDBEntryType* : Read / Write / Construct Only
Entry type for entries in this source.
"hidden-when-empty"
property"hidden-when-empty" gboolean : Read / Write
If TRUE, the source will not be displayed in the source list when it contains no entries.
Default value: FALSE
"name"
property"name" gchar* : Read / Write
Source name as displayed in the source list
Default value: NULL
"play-order"
property"play-order" RBPlayOrder* : Read
If the source provides its own play order, it can override this property.
"query-model"
property"query-model" RhythmDBQueryModel* : Read / Write
The current query model for the source. This is used in various places, including the play order, to find the set of entries within the source.
"source-group"
property"source-group" RBSourceGroup* : Read / Write / Construct Only
Source group in which to display the source
"visibility"
property"visibility" gboolean : Read / Write
If FALSE, the source will not be displayed in the source list
Default value: TRUE
"deleted"
signalvoid user_function (RBSource *source, gpointer user_data) : Run Last
Emitted when the source is being deleted.
|
the RBSource |
|
user data set when the signal handler was connected. |
"filter-changed"
signalvoid user_function (RBSource *rbsource, gpointer user_data) : Run Last
|
the object which received the signal. |
|
user data set when the signal handler was connected. |