RB.Source¶

Subclasses:: RB.BrowserSource, RB.PlaylistSource, RB.StreamingSource

Methods¶

Inherited:: RB.DisplayPage (12), Gtk.Box (14), Gtk.Container (35), Gtk.Widget (278), GObject.Object (37), Gtk.Buildable (10), Gtk.Orientable (2)
Structs:: Gtk.ContainerClass (5), Gtk.WidgetClass (12), GObject.ObjectClass (5)

	`add_to_queue` (queue)
	`add_uri` (uri, title, genre, callback, *data)
	`bind_settings` (entry_view, paned, browser, sort_order)
	`can_add_to_queue` ()
	`can_copy` ()
	`can_cut` ()
	`can_delete` ()
	`can_move_to_trash` ()
	`can_paste` ()
	`can_pause` ()
	`can_rename` ()
	`can_show_properties` ()
	`copy` ()
	`create_search_action` ()
	`cut` ()
	`delete_selected` ()
	`gather_selected_properties` (prop)
	`get_delete_label` ()
	`get_entry_view` ()
	`get_playback_status` (text, progress)
	`get_property_views` ()
	`handle_eos` ()
	`move_to_trash` ()
	`notify_filter_changed` ()
	`notify_playback_status_changed` ()
	`paste` (entries)
	`search` (search, cur_text, new_text)
	`set_hidden_when_empty` (hidden)
	`song_properties` ()
	`try_playlist` ()
	`update_play_statistics` (db, entry)
	`uri_is_source` (uri)
	`want_uri` (uri)

Virtual Methods¶

Inherited:: RB.DisplayPage (12), Gtk.Container (10), Gtk.Widget (82), GObject.Object (7), Gtk.Buildable (10)

	`do_add_to_queue` (queue)
	`do_add_uri` (uri, title, genre, callback, data)
	`do_can_add_to_queue` ()
	`do_can_copy` ()
	`do_can_cut` ()
	`do_can_delete` ()
	`do_can_move_to_trash` ()
	`do_can_paste` ()
	`do_can_pause` ()
	`do_can_rename` ()
	`do_copy` ()
	`do_cut` ()
	`do_delete_selected` ()
	`do_filter_changed` ()
	`do_get_delete_label` ()
	`do_get_entry_view` ()
	`do_get_playback_status` (text, progress)
	`do_get_property_views` ()
	`do_handle_eos` ()
	`do_move_to_trash` ()
	`do_paste` (entries)
	`do_reset_filters` ()
	`do_search` (search, cur_text, new_text)
	`do_song_properties` ()
	`do_try_playlist` ()
	`do_uri_is_source` (uri)
	`do_want_uri` (uri)

Properties¶

Inherited:: RB.DisplayPage (5), Gtk.Box (3), Gtk.Container (3), Gtk.Widget (39), Gtk.Orientable (1)

Name	Type	Flags	Short Description
`base-query-model`	`RB.RhythmDBQueryModel`	r	`RB.RhythmDBQueryModel` object (unfiltered)
`entry-type`	`RB.RhythmDBEntryType`	r/w/co	Type of the entries which should be displayed by this source
`hidden-when-empty`	`bool`	r/w	Whether the source should be displayed in the source list when it is empty
`load-status`	`RB.SourceLoadStatus`	r/w/c	load status
`play-order`	`RB.PlayOrder`	r	optional play order specific to the source
`playlist-menu`	`Gio.MenuModel`	r/w	playlist menu
`query-model`	`RB.RhythmDBQueryModel`	r/w	`RB.RhythmDBQueryModel` object
`settings`	`Gio.Settings`	r/w/c	`Gio.Settings` instance
`show-browser`	`bool`	r/w	whether the browser widget should be shown
`toolbar-menu`	`Gio.MenuModel`	r/w/co	toolbar menu

Child Properties¶

Inherited:: Gtk.Box (5)

Style Properties¶

Inherited:: Gtk.Widget (17)

Signals¶

Inherited:: RB.DisplayPage (2), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Short Description
`filter-changed`	Fires when the user changes the filter, either by changing the contents of the search box or by selecting a different browser entry.
`playback-status-changed`	Emitted to indicate playback status (buffering etc.) has changed
`reset-filters`	Action signal used to reset the source’s filters.

Fields¶

Inherited:: RB.DisplayPage (2), Gtk.Container (4), Gtk.Widget (69), GObject.Object (1)

Name	Type	Access	Description
parent	`RB.DisplayPage`	r

Class Details¶

class RB.Source(*args, **kwargs)¶

Bases:: RB.DisplayPage
Abstract:: Yes
Structure:: RB.SourceClass

add_to_queue(queue)¶

Parameters:: queue (RB.Source) – the RB.Source for the play queue

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

add_uri(uri, title, genre, callback, *data)¶

Parameters:

uri (str) – a URI to add
title (str) – theoretically, the title of the entity the URI points to
genre (str) – theoretically, the genre of the entity the URI points to
callback (RB.SourceAddCallback) – a callback function to call when complete
data (object or None) – data to pass to the callback

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

bind_settings(entry_view, paned, browser, sort_order)¶

Parameters:

entry_view (Gtk.Widget or None) – the RB.EntryView for the source
paned (Gtk.Widget or None) – the Gtk.Paned containing the entry view and the browser
browser (Gtk.Widget or None) – the browser (typically a RB.LibraryBrowser) for the source
sort_order (bool) – whether to bind the entry view sort order

Binds the source’s Gio.Settings 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.

can_add_to_queue()¶

Returns:: True if adding to the play queue is supported
Return type:: bool

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

can_copy()¶

Returns:: True if copying is supported
Return type:: bool

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

can_cut()¶

Returns:: True if cutting is supported
Return type:: bool

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

can_delete()¶

Returns:: True if deletion is supported
Return type:: bool

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

can_move_to_trash()¶

Returns:: True if trashing is supported
Return type:: bool

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

can_paste()¶

Returns:: True if the pasting is supported
Return type:: bool

Determines whether the source supports paste operations.

can_pause()¶

Returns:: True if pausing is supported
Return type:: bool

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

can_rename()¶

Returns:: True if this source can be renamed
Return type:: bool

Determines whether the source can be renamed.

can_show_properties()¶

Returns:: True if showing properties is supported
Return type:: bool

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

copy()¶

Returns:: a list containing the currently selected entries from the source.
Return type:: [RB.RhythmDBEntry]

Copies the selected entries to the clipboard.

create_search_action()¶

Returns:: Gio.Action instance
Return type:: Gio.Action

Creates a Gio.Action representing the selected search type for self. The action is stateful. Its state is a string containing the name of a registered search instance. If the source has a settings instance, it will be updated when the state changes. Changes coming from the settings instance are ignored. If the source doesn’t have a settings instance, it should set a default state on the action at some point.

cut()¶

Returns:: entries cut from the source.
Return type:: [RB.RhythmDBEntry]

Removes the currently selected entries from the source and returns them so they can be pasted into another source.

delete_selected()¶: Deletes the currently selected entries from the source.

gather_selected_properties(prop)¶

Parameters:: prop (RB.RhythmDBPropType) – property for which to gather selection
Returns:: list of property values
Return type:: [str]

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.

get_delete_label()¶

Returns:: allocated string holding the label string
Return type:: str

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.

get_entry_view()¶

Returns:: the RB.EntryView instance for the source
Return type:: RB.EntryView

Returns the entry view widget for the source.

get_playback_status(text, progress)¶

Parameters:

text (str or None) – holds returned playback status text
progress (float or None) – holds returned playback status progress value

Returns:

text:: holds returned playback status text
progress:: holds returned playback status progress value

Return type:

(text: str or None, progress: float)

Retrieves playback status details, such as buffering progress.

get_property_views()¶

Returns:: list of property views
Return type:: [RB.PropertyView]

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

handle_eos()¶

Returns:: EOS event handling type
Return type:: RB.SourceEOFType

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

move_to_trash()¶: Trashes the files backing the currently selected set of entries. In general, this should use RB.RhythmDB.entry_move_to_trash to perform the actual trash operation.

notify_filter_changed()¶: Source implementations call this when their filter state changes

notify_playback_status_changed()¶: Source implementations call this when their playback status changes.

paste(entries)¶

Parameters:: entries ([RB.RhythmDBEntry]) – a list of RB.RhythmDBEntry objects to paste in
Returns:: the RB.TrackTransferBatch used to perform the transfer (if any)
Return type:: RB.TrackTransferBatch

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 RB.TrackTransferBatch, the batch object is returned so the caller can monitor the transfer progress. The caller does not own a reference on the batch object.

search(search, cur_text, new_text)¶

Parameters:

search (RB.SourceSearch or None) – the active RB.SourceSearch instance
cur_text (str or None) – the current search text
new_text (str) – the new search text

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

set_hidden_when_empty(hidden)¶

Parameters:: hidden (bool) – if True, automatically hide the source

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

song_properties()¶: Displays a properties window for the currently selected entries.

try_playlist()¶

Returns:: True to attempt playlist parsing
Return type:: bool

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

update_play_statistics(db, entry)¶

Parameters:

db (RB.RhythmDB) – the RB.RhythmDB instance
entry (RB.RhythmDBEntry) – the RB.RhythmDBEntry to update

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.

uri_is_source(uri)¶

Parameters:: uri (str) – a URI for the source to consider
Returns:: True if the URI identifies the source itself.
Return type:: bool

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.

want_uri(uri)¶

Parameters:: uri (str) – a URI for the source to consider
Returns:: value from 0 to 100 indicating how much the source wants this URI.
Return type:: int

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.

do_add_to_queue(queue) virtual¶

Parameters:: queue (RB.Source) – the RB.Source for the play queue

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

do_add_uri(uri, title, genre, callback, data) virtual¶

Parameters:

uri (str) – a URI to add
title (str) – theoretically, the title of the entity the URI points to
genre (str) – theoretically, the genre of the entity the URI points to
callback (RB.SourceAddCallback) – a callback function to call when complete
data (object or None) – data to pass to the callback

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

do_can_add_to_queue() virtual¶

Returns:: True if adding to the play queue is supported
Return type:: bool

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

do_can_copy() virtual¶

Returns:: True if copying is supported
Return type:: bool

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

do_can_cut() virtual¶

Returns:: True if cutting is supported
Return type:: bool

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

do_can_delete() virtual¶

Returns:: True if deletion is supported
Return type:: bool

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

do_can_move_to_trash() virtual¶

Returns:: True if trashing is supported
Return type:: bool

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

do_can_paste() virtual¶

Returns:: True if the pasting is supported
Return type:: bool

Determines whether the source supports paste operations.

do_can_pause() virtual¶

Returns:: True if pausing is supported
Return type:: bool

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

do_can_rename() virtual¶

Returns:: True if this source can be renamed
Return type:: bool

Determines whether the source can be renamed.

do_copy() virtual¶

Returns:: a list containing the currently selected entries from the source.
Return type:: [RB.RhythmDBEntry]

Copies the selected entries to the clipboard.

do_cut() virtual¶

Returns:: entries cut from the source.
Return type:: [RB.RhythmDBEntry]

Removes the currently selected entries from the source and returns them so they can be pasted into another source.

do_delete_selected() virtual¶: Deletes the currently selected entries from the source.

do_filter_changed() virtual¶

do_get_delete_label() virtual¶

Returns:: allocated string holding the label string
Return type:: str

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.

do_get_entry_view() virtual¶

Returns:: the RB.EntryView instance for the source
Return type:: RB.EntryView

Returns the entry view widget for the source.

do_get_playback_status(text, progress) virtual¶

Parameters:

text (str or None) – holds returned playback status text
progress (float or None) – holds returned playback status progress value

Returns:

text:: holds returned playback status text
progress:: holds returned playback status progress value

Return type:

(text: str or None, progress: float)

Retrieves playback status details, such as buffering progress.

do_get_property_views() virtual¶

Returns:: list of property views
Return type:: [RB.PropertyView]

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

do_handle_eos() virtual¶

Returns:: EOS event handling type
Return type:: RB.SourceEOFType

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

do_move_to_trash() virtual¶: Trashes the files backing the currently selected set of entries. In general, this should use RB.RhythmDB.entry_move_to_trash to perform the actual trash operation.

do_paste(entries) virtual¶

Parameters:: entries ([RB.RhythmDBEntry]) – a list of RB.RhythmDBEntry objects to paste in
Returns:: the RB.TrackTransferBatch used to perform the transfer (if any)
Return type:: RB.TrackTransferBatch

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 RB.TrackTransferBatch, the batch object is returned so the caller can monitor the transfer progress. The caller does not own a reference on the batch object.

do_reset_filters() virtual¶

do_search(search, cur_text, new_text) virtual¶

Parameters:

search (RB.SourceSearch or None) – the active RB.SourceSearch instance
cur_text (str or None) – the current search text
new_text (str) – the new search text

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

do_song_properties() virtual¶: Displays a properties window for the currently selected entries.

do_try_playlist() virtual¶

Returns:: True to attempt playlist parsing
Return type:: bool

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

do_uri_is_source(uri) virtual¶

Parameters:: uri (str) – a URI for the source to consider
Returns:: True if the URI identifies the source itself.
Return type:: bool

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.

do_want_uri(uri) virtual¶

Parameters:: uri (str) – a URI for the source to consider
Returns:: value from 0 to 100 indicating how much the source wants this URI.
Return type:: int

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.

Signal Details¶

RB.Source.signals.filter_changed(source)¶

Signal Name:: filter-changed
Flags:: RUN_LAST
Parameters:: source (RB.Source) – The object which received the signal

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

RB.Source.signals.playback_status_changed(source)¶

Signal Name:: playback-status-changed
Flags:: RUN_LAST
Parameters:: source (RB.Source) – The object which received the signal

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

RB.Source.signals.reset_filters(source)¶

Signal Name:: reset-filters
Flags:: RUN_LAST, ACTION
Parameters:: source (RB.Source) – The object which received the signal

Action signal used to reset the source’s filters.

Property Details¶

RB.Source.props.base_query_model¶

Name:: base-query-model
Type:: RB.RhythmDBQueryModel
Default Value:: None
Flags:: READABLE

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.

RB.Source.props.entry_type¶

Name:: entry-type
Type:: RB.RhythmDBEntryType
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Entry type for entries in this source.

RB.Source.props.hidden_when_empty¶

Name:: hidden-when-empty
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

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

RB.Source.props.load_status¶

Name:: load-status
Type:: RB.SourceLoadStatus
Default Value:: RB.SourceLoadStatus.LOADED
Flags:: READABLE, WRITABLE, CONSTRUCT

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

RB.Source.props.play_order¶

Name:: play-order
Type:: RB.PlayOrder
Default Value:: None
Flags:: READABLE

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

RB.Source.props.playlist_menu¶

Name:: playlist-menu
Type:: Gio.MenuModel
Default Value:: None
Flags:: READABLE, WRITABLE

A Gio.Menu instance to attach to the ‘add to playlist’ item in the edit menu. If None, the item will be disabled.

RB.Source.props.query_model¶

Name:: query-model
Type:: RB.RhythmDBQueryModel
Default Value:: None
Flags:: READABLE, WRITABLE

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.

RB.Source.props.settings¶

Name:: settings
Type:: Gio.Settings
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT

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

RB.Source.props.show_browser¶

Name:: show-browser
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE

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

RB.Source.props.toolbar_menu¶

Name:: toolbar-menu
Type:: Gio.MenuModel
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

A Gio.Menu instance describing the contents of a toolbar to display at the top of the source. The RB.Source class doesn’t actually display the toolbar anywhere. Adding the toolbar to a container is the responsibility of a subclass such as RB.BrowserSource.