RB.Source

g Atk.ImplementorIface Atk.ImplementorIface Gtk.Widget Gtk.Widget Atk.ImplementorIface->Gtk.Widget GObject.GInterface GObject.GInterface GObject.GInterface->Atk.ImplementorIface Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable Gtk.Orientable Gtk.Orientable GObject.GInterface->Gtk.Orientable GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.Box Gtk.Box RB.DisplayPage RB.DisplayPage Gtk.Box->RB.DisplayPage Gtk.Buildable->Gtk.Widget Gtk.Container Gtk.Container Gtk.Container->Gtk.Box Gtk.Orientable->Gtk.Box Gtk.Widget->Gtk.Container RB.Source RB.Source RB.DisplayPage->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:

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:

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:

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
Parameters:

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.