RBSource

RBSource — base class for sources

Synopsis

                    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);
void                rb_source_search                    (RBSource *source,
                                                         RBSourceSearch *search,
                                                         const char *cur_text,
                                                         const char *new_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);
RBTrackTransferBatch * 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,
                                                         RBSourceAddCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);
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);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBox
                                 +----GtkHBox
                                       +----RBSource
                                             +----RBPlaylistSource
                                             +----RBBrowserSource
                                             +----RBImportErrorsSource
                                             +----RBMissingFilesSource
                                             +----RBStreamingSource

Implemented Interfaces

RBSource implements AtkImplementorIface, GtkBuildable and GtkOrientable.

Properties

  "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 / Construct
  "query-model"              RhythmDBQueryModel*   : Read / Write
  "search-type"              RBSourceSearchType    : Read / Write / Construct
  "shell"                    RBShell*              : Read / Write / Construct Only
  "source-group"             RBSourceGroup*        : Read / Write / Construct Only
  "ui-manager"               GtkUIManager*         : Read
  "visibility"               gboolean              : Read / Write

Signals

  "deleted"                                        : Run Last
  "filter-changed"                                 : Run Last
  "status-changed"                                 : Run Last

Description

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.

Details

RBSource

typedef struct _RBSource RBSource;


RBSourceClass

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);

	void		(*impl_search)		(RBSource *source, RBSourceSearch *search, const char *cur_text, const char *new_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);
	RBTrackTransferBatch *(*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,
						 RBSourceAddCallback callback,
						 gpointer data,
						 GDestroyNotify destroy_data);
	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);
	char *		(*impl_get_delete_action) (RBSource *source);
} RBSourceClass;


enum RBSourceEOFType

typedef enum {
	RB_SOURCE_EOF_ERROR,
	RB_SOURCE_EOF_STOP,
	RB_SOURCE_EOF_RETRY,
	RB_SOURCE_EOF_NEXT,
} RBSourceEOFType;


RB_SOURCE_ICON_SIZE

#define RB_SOURCE_ICON_SIZE GTK_ICON_SIZE_LARGE_TOOLBAR


rb_source_notify_filter_changed ()

void                rb_source_notify_filter_changed     (RBSource *source);

Source implementations call this when their filter state changes

source :

a RBSource

rb_source_notify_status_changed ()

void                rb_source_notify_status_changed     (RBSource *source);

Source implementations call this when their status bar information changes.

source :

a RBSource

rb_source_update_play_statistics ()

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.

source :

a RBSource

db :

the RhythmDB instance

entry :

the RhythmDBEntry to update

rb_source_set_pixbuf ()

void                rb_source_set_pixbuf                (RBSource *source,
                                                         GdkPixbuf *pixbuf);

Sets the pixbuf for the source.

source :

a RBSource

pixbuf :

new GdkPixbuf for the source

rb_source_get_status ()

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.

source :

a RBSource

text :

holds the returned status text (allocated)

progress_text :

holds the returned text for the progress bar (allocated)

progress :

holds the progress value

rb_source_can_browse ()

gboolean            rb_source_can_browse                (RBSource *source);

Determines whether the source has a browser

source :

a RBSource

Returns :

TRUE if this source has a browser

rb_source_get_browser_key ()

char *              rb_source_get_browser_key           (RBSource *source);

Gets the GConf key controlling browser visibility

source :

a RBSource

Returns :

the GConf key name (allocated)

rb_source_browser_toggled ()

void                rb_source_browser_toggled           (RBSource *source,
                                                         gboolean enabled);

Called when the visibility of the browser changes.

source :

a RBSource

enabled :

TRUE if the browser should be visible

rb_source_get_entry_view ()

RBEntryView *       rb_source_get_entry_view            (RBSource *source);

Returns the entry view widget for the source.

source :

a RBSource

Returns :

the RBEntryView instance for the source

rb_source_get_property_views ()

GList *             rb_source_get_property_views        (RBSource *source);

Returns a list containing the RBPropertyView instances for the source, if any.

source :

a RBSource

Returns :

list of property views

rb_source_can_rename ()

gboolean            rb_source_can_rename                (RBSource *source);

Determines whether the source can be renamed.

source :

a RBSource.

Returns :

TRUE if this source can be renamed

rb_source_search ()

void                rb_source_search                    (RBSource *source,
                                                         RBSourceSearch *search,
                                                         const char *cur_text,
                                                         const char *new_text);

Updates the source with new search text. The source should recreate the database query that feeds into the browser (if any).

source :

a RBSource

search :

the active RBSourceSearch instance (may be NULL)

cur_text :

the current search text (may be NULL)

new_text :

the new search text

rb_source_reset_filters ()

void                rb_source_reset_filters             (RBSource *source);

Clears all filters (browser selections, etc.) in this source.

source :

a RBSource

rb_source_get_config_widget ()

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.

source :

a RBSource

prefs :

the RBShellPreferences object

Returns :

configuration widget

rb_source_can_cut ()

gboolean            rb_source_can_cut                   (RBSource *source);

Determines whether the source supporst the typical cut (as in cut-and-paste) operation.

source :

a RBSource

Returns :

TRUE if cutting is supported

rb_source_can_delete ()

gboolean            rb_source_can_delete                (RBSource *source);

Determines whether the source allows the user to delete a selected set of entries.

source :

a RBSource

Returns :

TRUE if deletion is supported

rb_source_can_move_to_trash ()

gboolean            rb_source_can_move_to_trash         (RBSource *source);

Determines whether the source allows the user to trash the files backing a selected set of entries.

source :

a RBSource

Returns :

TRUE if trashing is supported

rb_source_can_copy ()

gboolean            rb_source_can_copy                  (RBSource *source);

Determines whether the source supports the copy part of a copy-and-paste operation.

source :

a RBSource

Returns :

TRUE if copying is supported

rb_source_can_paste ()

gboolean            rb_source_can_paste                 (RBSource *source);

Determines whether the source supports paste operations.

source :

a RBSource

Returns :

TRUE if the pasting is supported

rb_source_can_add_to_queue ()

gboolean            rb_source_can_add_to_queue          (RBSource *source);

Determines whether the source can add the selected entries to the play queue.

source :

a RBSource

Returns :

TRUE if adding to the play queue is supported

rb_source_can_show_properties ()

gboolean            rb_source_can_show_properties       (RBSource *source);

Determines whether the source can display a properties window for the currently selected entry (or set of entries)

source :

a RBSource

Returns :

TRUE if showing properties is supported

rb_source_cut ()

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.

source :

a RBSource

Returns :

a list of RhythmDBEntry objects cut from the source.

rb_source_copy ()

GList *             rb_source_copy                      (RBSource *source);

Copies the selected entries to the clipboard.

source :

a RBSource

Returns :

a list containing the currently selected entries from the source.

rb_source_paste ()

RBTrackTransferBatch * rb_source_paste                  (RBSource *source,
                                                         GList *entries);

Adds a list of entries previously cut or copied from another source. If the entries are not of the type used by the source, the entries will be copied and possibly converted into an acceptable format. This can be used for transfers to and from devices and network shares.

If the transfer is performed using an RBTrackTransferBatch, the batch object is returned so the caller can monitor the transfer progress. The caller does not own a reference on the batch object.

source :

a RBSource

entries :

a list of RhythmDBEntry objects to paste in

Returns :

the RBTrackTransferBatch used to perform the transfer (if any)

rb_source_delete ()

void                rb_source_delete                    (RBSource *source);

Deletes the currently selected entries from the source.

source :

a RBSource

rb_source_add_to_queue ()

void                rb_source_add_to_queue              (RBSource *source,
                                                         RBSource *queue);

Adds the currently selected entries to the end of the play queue.

source :

a RBSource

queue :

the RBSource for the play queue

rb_source_move_to_trash ()

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.

source :

a RBSource

rb_source_song_properties ()

void                rb_source_song_properties           (RBSource *source);

Displays a properties window for the currently selected entries.

source :

a RBSource

rb_source_try_playlist ()

gboolean            rb_source_try_playlist              (RBSource *source);

Determines whether playback URIs for entries in the source should be parsed as playlists rather than just played.

source :

a RBSource

Returns :

TRUE to attempt playlist parsing

rb_source_want_uri ()

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.

source :

a RBSource

uri :

a URI for the source to consider

Returns :

value from 0 to 100 indicating how much the source wants this URI.

rb_source_uri_is_source ()

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.

source :

a RBSource

uri :

a URI for the source to consider

Returns :

TRUE if the URI identifies the source itself.

rb_source_add_uri ()

gboolean            rb_source_add_uri                   (RBSource *source,
                                                         const char *uri,
                                                         const char *title,
                                                         const char *genre,
                                                         RBSourceAddCallback callback,
                                                         gpointer data,
                                                         GDestroyNotify destroy_data);

Adds an entry corresponding to the URI to the source. The title and genre parameters are not really used.

source :

a RBSource

uri :

a URI to add

title :

theoretically, the title of the entity the URI points to

genre :

theoretically, the genre of the entity the URI points to

callback :

a callback function to call when complete

data :

data to pass to the callback

destroy_data :

function to call to destroy the callback data

Returns :

TRUE if the URI was successfully added to the source

rb_source_can_pause ()

gboolean            rb_source_can_pause                 (RBSource *source);

Determines whether playback of entries from the source can be paused.

source :

a RBSource

Returns :

TRUE if pausing is supported

rb_source_handle_eos ()

RBSourceEOFType     rb_source_handle_eos                (RBSource *source);

Determines how EOS events should be handled when playing entries from the source.

source :

a RBSource

Returns :

EOS event handling type

rb_source_receive_drag ()

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.

source :

a RBSource

data :

the selection data

Returns :

TRUE if the source accepted the drag data

rb_source_show_popup ()

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.

source :

a RBSource

Returns :

TRUE if the source managed to display a popup

rb_source_delete_thyself ()

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.

source :

a RBSource

rb_source_activate ()

void                rb_source_activate                  (RBSource *source);

Called when the source is selected in the source list.

source :

a RBSource

rb_source_deactivate ()

void                rb_source_deactivate                (RBSource *source);

Called when the source is deselected in the source list.

source :

a RBSource

rb_source_get_ui_actions ()

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.

source :

a RBSource

Returns :

list of action names

rb_source_get_search_actions ()

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

source :

a RBSource

Returns :

list of search actions

rb_source_gather_selected_properties ()

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.

source :

a RBSource

prop :

property for which to gather selection

Returns :

list of property values

rb_source_set_hidden_when_empty ()

void                rb_source_set_hidden_when_empty     (RBSource *source,
                                                         gboolean hidden);

Enables or disables automatic hiding of the source when there are no entries in it.

source :

a RBSource

hidden :

if TRUE, automatically hide the source

Property Details

The "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.


The "entry-type" property

  "entry-type"               RhythmDBEntryType*    : Read / Write / Construct Only

Entry type for entries in this source.


The "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


The "icon" property

  "icon"                     GdkPixbuf*            : Read / Write

Icon to display in the source list


The "name" property

  "name"                     gchar*                : Read / Write

Source name as displayed in the source list

Default value: NULL


The "play-order" property

  "play-order"               RBPlayOrder*          : Read

If the source provides its own play order, it can override this property.


The "plugin" property

  "plugin"                   RBPlugin*             : Read / Write / Construct

The plugin that created this source.


The "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.


The "search-type" property

  "search-type"              RBSourceSearchType    : Read / Write / Construct

The type of searching this source provides, as a RBSourceSearchType value. This is used by the RBSourceHeader to modify the search box widget.

Default value: RB_SOURCE_SEARCH_NONE


The "shell" property

  "shell"                    RBShell*              : Read / Write / Construct Only

The rhythmbox shell object


The "source-group" property

  "source-group"             RBSourceGroup*        : Read / Write / Construct Only

Source group in which to display the source


The "ui-manager" property

  "ui-manager"               GtkUIManager*         : Read

The Gtk UIManager object


The "visibility" property

  "visibility"               gboolean              : Read / Write

If FALSE, the source will not be displayed in the source list

Default value: TRUE

Signal Details

The "deleted" signal

void                user_function                      (RBSource *source,
                                                        gpointer  user_data)      : Run Last

Emitted when the source is being deleted.

source :

the RBSource

user_data :

user data set when the signal handler was connected.

The "filter-changed" signal

void                user_function                      (RBSource *source,
                                                        gpointer  user_data)      : Run Last

Fires when the user changes the filter, either by changing the contents of the search box or by selecting a different browser entry.

source :

the RBSource

user_data :

user data set when the signal handler was connected.

The "status-changed" signal

void                user_function                      (RBSource *source,
                                                        gpointer  user_data)      : Run Last

Emitted when the source's status changes.

source :

the RBSource

user_data :

user data set when the signal handler was connected.