RBSource: Rhythmbox Development Reference Manual

## RBSource RBSource — base class for sources |

## Functions

gboolean | (*RBSourceFeatureFunc) ()
const char * | (*RBSourceStringFunc) ()
void | (*RBSourceAddCallback) ()
void | rb_source_notify_filter_changed ()
void | rb_source_update_play_statistics ()
RBEntryView * | rb_source_get_entry_view ()
GList * | rb_source_get_property_views ()
gboolean | rb_source_can_rename ()
void | rb_source_search ()
gboolean | rb_source_can_cut ()
gboolean | rb_source_can_delete ()
gboolean | rb_source_can_move_to_trash ()
gboolean | rb_source_can_copy ()
gboolean | rb_source_can_paste ()
gboolean | rb_source_can_add_to_queue ()
gboolean | rb_source_can_show_properties ()
GList * | rb_source_cut ()
GList * | rb_source_copy ()
RBTrackTransferBatch * | rb_source_paste ()
void | rb_source_add_to_queue ()
void | rb_source_move_to_trash ()
void | rb_source_song_properties ()
gboolean | rb_source_try_playlist ()
guint | rb_source_want_uri ()
gboolean | rb_source_uri_is_source ()
void | rb_source_add_uri ()
gboolean | rb_source_can_pause ()
RBSourceEOFType | rb_source_handle_eos ()
char * | rb_source_get_delete_label ()
GList * | rb_source_gather_selected_properties ()
void | rb_source_set_hidden_when_empty ()
void | rb_source_get_playback_status ()
void | rb_source_bind_settings ()
void | rb_source_notify_playback_status_changed ()

## Properties

RhythmDBQueryModel * | base-query-model | Read
RhythmDBEntryType * | entry-type | Read / Write / Construct Only
gboolean | hidden-when-empty | Read / Write
RBSourceLoadStatus | load-status | Read / Write / Construct
RBPlayOrder * | play-order | Read
GMenuModel * | playlist-menu | Read / Write
RhythmDBQueryModel * | query-model | Read / Write
GSettings * | settings | Read / Write / Construct
gboolean | show-browser | Read / Write
GMenuModel * | toolbar-menu | Read / Write / Construct Only

## Signals

void | filter-changed | Run Last
void | playback-status-changed | Run Last
void | reset-filters | Action

## Types and Values

enum | RBSourceEOFType
enum | RBSourceLoadStatus
struct | RBSource
struct | RBSourceClass

## Object Hierarchy

        GEnum
        ├── RBSourceEOFType
        ╰── RBSourceLoadStatus
        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBox
                        ╰── RBDisplayPage
                            ╰── RBSource
                                ├── RBPlaylistSource
                                ├── RBBrowserSource
                                ├── RBImportErrorsSource
                                ├── RBMissingFilesSource
                                ╰── RBStreamingSource

## Implemented Interfaces

RBSource implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## 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.

## Functions

### RBSourceFeatureFunc ()

    gboolean
    (*RBSourceFeatureFunc) (RBSource *source);

### RBSourceStringFunc ()

    const char *
    (*RBSourceStringFunc) (RBSource *source);

### RBSourceAddCallback ()

    void
    (*RBSourceAddCallback) (RBSource *source,
                            const char *uri,
                            gpointer data);

### rb_source_notify_filter_changed ()

    void
    rb_source_notify_filter_changed (RBSource *source);

Source implementations call this when their filter state changes

#### Parameters

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.

#### Parameters

source | a RBSource |
db | the RhythmDB instance |
entry | the RhythmDBEntry to update |

### rb_source_get_entry_view ()

    RBEntryView *
    rb_source_get_entry_view (RBSource *source);

Returns the entry view widget for the source.

#### Parameters

source | a RBSource |

#### Returns

the RBEntryView instance for the source.

[transfer none]

### 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.

#### Parameters

source | a RBSource |

#### Returns

list of property views.

[element-type RB.PropertyView][transfer container]

### rb_source_can_rename ()

    gboolean
    rb_source_can_rename (RBSource *source);

Determines whether the source can be renamed.

#### Parameters

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

#### Parameters

source | a RBSource |
search | the active RBSourceSearch instance. | [allow-none]
cur_text | the current search text. | [allow-none]
new_text | the new search text |

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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)

#### Parameters

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.

#### Parameters

source | a RBSource |

#### Returns

entries cut from the source.

[element-type RB.RhythmDBEntry][transfer full]

### rb_source_copy ()

    GList *
    rb_source_copy (RBSource *source);

Copies the selected entries to the clipboard.

#### Parameters

source | a RBSource |

#### Returns

a list containing the currently selected entries from the source.

[element-type RB.RhythmDBEntry][transfer full]

### 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.

#### Parameters

source | a RBSource |
entries | a list of RhythmDBEntry objects to paste in. | [element-type RB.RhythmDBEntry]

#### Returns

the RBTrackTransferBatch used to perform the transfer (if any).

[transfer none]

### 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.

#### Parameters

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.

#### Parameters

source | a RBSource |

### rb_source_song_properties ()

    void
    rb_source_song_properties (RBSource *source);

Displays a properties window for the currently selected entries.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

source | a RBSource |
uri | a URI for the source to consider |

#### Returns

TRUE if the URI identifies the source itself.

### rb_source_add_uri ()

    void
    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.

#### Parameters

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 |

### rb_source_can_pause ()

    gboolean
    rb_source_can_pause (RBSource *source);

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

#### Parameters

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.

#### Parameters

source | a RBSource |

#### Returns

EOS event handling type

### rb_source_get_delete_label ()

    char *
    rb_source_get_delete_label (RBSource *source);

Returns a translated label for the 'delete' menu item, allowing sources to better describe what happens to deleted entries. Playlists, for example, return "Remove from Playlist" here.

#### Parameters

source | a RBSource |

#### Returns

allocated string holding the label string

### 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.

#### Parameters

source | a RBSource |
prop | property for which to gather selection |

#### Returns

list of property values.

[element-type utf8][transfer full]

### 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.

#### Parameters

source | a RBSource |
hidden | if TRUE, automatically hide the source |

### rb_source_get_playback_status ()

    void
    rb_source_get_playback_status (RBSource *source,
                                   char **text,
                                   float *progress);

Retrieves playback status details, such as buffering progress.

#### Parameters

source | a RBSource |
text | holds returned playback status text. | [inout][allow-none][transfer full]
progress | holds returned playback status progress value. | [inout][allow-none]

### rb_source_bind_settings ()

    void
    rb_source_bind_settings (RBSource *source,
                             GtkWidget *entry_view,
                             GtkWidget *paned,
                             GtkWidget *browser,
                             gboolean sort_order);

Binds the source's GSettings instance to the given widgets. Should be called from the source's constructed method.

If the browser widget has a browser-views property, it will be bound to the browser-views settings key.

#### Parameters

source | the RBSource |
entry_view | the RBEntryView for the source. | [allow-none]
paned | the GtkPaned containing the entry view and the browser. | [allow-none]
browser | the browser (typically a RBLibraryBrowser) for the source. | [allow-none]
sort_order | whether to bind the entry view sort order |

### rb_source_notify_playback_status_changed ()

    void
    rb_source_notify_playback_status_changed
                                   (RBSource *source);

Source implementations call this when their playback status changes.

#### Parameters

source | a RBSource |

## Types and Values

### enum RBSourceEOFType

#### Members

RB_SOURCE_EOF_ERROR |  |
RB_SOURCE_EOF_STOP |  |
RB_SOURCE_EOF_RETRY |  |
RB_SOURCE_EOF_NEXT |  |

### enum RBSourceLoadStatus

#### Members

RB_SOURCE_LOAD_STATUS_NOT_LOADED |  |
RB_SOURCE_LOAD_STATUS_WAITING |  |
RB_SOURCE_LOAD_STATUS_LOADING |  |
RB_SOURCE_LOAD_STATUS_LOADED |  |

### struct RBSource

    struct RBSource;

### struct RBSourceClass

    struct RBSourceClass {
    	RBDisplayPageClass parent;

    	/* signals */
    	void (*filter_changed) (RBSource *source);
    	void (*reset_filters) (RBSource *source);

    	/* methods */

    	RBEntryView * (*get_entry_view) (RBSource *source);
    	GList *		(*get_property_views) (RBSource *source);

    	gboolean (*can_rename)		(RBSource *source);

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

    	gboolean (*can_cut)		(RBSource *source);
    	gboolean (*can_delete)		(RBSource *source);
    	gboolean (*can_move_to_trash) 	(RBSource *source);
    	gboolean (*can_copy)		(RBSource *source);
    	gboolean (*can_paste)		(RBSource *source);
    	gboolean (*can_add_to_queue) (RBSource *source);

    	GList *		(*cut)			(RBSource *source);
    	GList *		(*copy)			(RBSource *source);
    	RBTrackTransferBatch *(*paste)		(RBSource *source, GList *entries);
    	void		(*delete_selected) (RBSource *source);
    	void		(*add_to_queue)		(RBSource *source, RBSource *queue);
    	void		(*move_to_trash) (RBSource *source);

    	void		(*song_properties) (RBSource *source);

    	gboolean (*try_playlist)		(RBSource *source);
    	guint		(*want_uri)		(RBSource *source, const char *uri);
    	void		(*add_uri)		(RBSource *source,
    						 const char *uri,
    						 const char *title,
    						 const char *genre,
    						 RBSourceAddCallback callback,
    						 gpointer data,
    						 GDestroyNotify destroy_data);
    	gboolean (*uri_is_source) (RBSource *source, const char *uri);

    	gboolean (*can_pause)		(RBSource *source);
    	RBSourceEOFType (*handle_eos)		(RBSource *source);
    	void		(*get_playback_status) 	(RBSource *source, char **text, float *progress);

    	char *		(*get_delete_label) 	(RBSource *source);
    };

## Property Details

### The `“base-query-model”` property

      “base-query-model”         RhythmDBQueryModel *

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.

Flags: Read

### The `“entry-type”` property

      “entry-type”               RhythmDBEntryType *

Entry type for entries in this source.

Flags: Read / Write / Construct Only

### The `“hidden-when-empty”` property

      “hidden-when-empty”        gboolean

If TRUE, the source will not be displayed in the source list when it contains no entries.

Flags: Read / Write

Default value: FALSE

### The `“load-status”` property

      “load-status”              RBSourceLoadStatus

Indicates whether the source is not loaded, is currently loading data, or is fully loaded.

Flags: Read / Write / Construct

Default value: RB_SOURCE_LOAD_STATUS_LOADED

### The `“play-order”` property

      “play-order”               RBPlayOrder *

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

Flags: Read

### The `“playlist-menu”` property

      “playlist-menu”            GMenuModel *

A GMenu instance to attach to the 'add to playlist' item in the edit menu. If NULL, the item will be disabled.

Flags: Read / Write

### The `“query-model”` property

      “query-model”              RhythmDBQueryModel *

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.

Flags: Read / Write

### The `“settings”` property

      “settings”                 GSettings *

The GSettings instance storing settings for the source. The instance must have a schema of org.gnome.Rhythmbox.Source.

Flags: Read / Write / Construct

### The `“show-browser”` property

      “show-browser”             gboolean

Whether the browser widget for the source (if any) should be displayed. This should be overridden in sources that include a browser widget.

Flags: Read / Write

Default value: TRUE

### The `“toolbar-menu”` property

      “toolbar-menu”             GMenuModel *

A GMenu instance describing the contents of a toolbar to display at the top of the source. The RBSource class doesn't actually display the toolbar anywhere. Adding the toolbar to a container is the responsibility of a subclass such as RBBrowserSource.

Flags: Read / Write / Construct Only

## Signal Details

### The `“filter-changed”` signal

    void
    user_function (RBSource *source,
                   gpointer  user_data)

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

#### Parameters

source | the RBSource |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playback-status-changed”` signal

    void
    user_function (RBSource *source,
                   gpointer  user_data)

Emitted to indicate playback status (buffering etc.) has changed

#### Parameters

source | the RBSource |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“reset-filters”` signal

    void
    user_function (RBSource *source,
                   gpointer  user_data)

Action signal used to reset the source's filters.

#### Parameters

source | the RBSource |
user_data | user data set when the signal handler was connected. |

Flags: Action