RBShell: Rhythmbox Development Reference Manual

## RBShell RBShell — holds the Rhythmbox main window and everything else |

## Functions

GQuark | rb_shell_error_quark ()
gboolean | rb_shell_present ()
RBSource * | rb_shell_guess_source_for_uri ()
gboolean | rb_shell_add_uri ()
gboolean | rb_shell_load_uri ()
void | rb_shell_toggle_visibility ()
gboolean | rb_shell_get_song_properties ()
gboolean | rb_shell_set_song_property ()
gboolean | rb_shell_quit ()
gboolean | rb_shell_activate_source_by_uri ()
gboolean | rb_shell_activate_source ()
void | rb_shell_notify_custom ()
gboolean | rb_shell_do_notify ()
void | rb_shell_register_entry_type_for_source ()
RBSource * | rb_shell_get_source_by_entry_type ()
gboolean | rb_shell_get_party_mode ()
void | rb_shell_append_display_page ()
void | rb_shell_add_widget ()
void | rb_shell_remove_widget ()

## Properties

GtkAccelGroup * | accel-group | Read
RBApplication * | application | Read / Write / Construct Only
gboolean | autostarted | Read / Write / Construct Only
RBShellClipboard * | clipboard | Read
RhythmDB * | db | Read
gboolean | disable-plugins | Read / Write / Construct Only
RBDisplayPageModel * | display-page-model | Read
RBDisplayPageTree * | display-page-tree | Read
gboolean | dry-run | Read / Write / Construct Only
RBLibrarySource * | library-source | Read
gboolean | no-registration | Read / Write / Construct Only
gboolean | no-update | Read / Write / Construct Only
RBPlaylistManager * | playlist-manager | Read
gchar * | playlists-file | Read / Write / Construct Only
RBShellPreferences * | prefs | Read
RBPlayQueueSource * | queue-source | Read
RBRemovableMediaManager * | removable-media-manager | Read
gchar * | rhythmdb-file | Read / Write / Construct Only
RBDisplayPage * | selected-page | Read
RBShellPlayer * | shell-player | Read
RBTaskList * | task-list | Read
RBTrackTransferQueue * | track-transfer-queue | Read
gboolean | visibility | Read / Write
GtkWindow * | window | Read

## Signals

void | create-song-info | Run Last
void | notify-custom | Run Last
void | notify-playing-entry | Run Last
void | visibility-changed | Run Last
gboolean | visibility-changing | Run Last

## Types and Values

enum | RBShellActivationType
enum | RBShellError
enum | RBShellUILocation
struct | RBShell
struct | RBShellClass

## Object Hierarchy

        GEnum
        ╰── RBShellUILocation
        GObject
        ╰── RBShell

## Description

RBShell is the main application class in Rhythmbox. It creates and holds references to the other main objects (RBShellPlayer, RhythmDB, RBDisplayPageTree), constructs the main window UI, and provides the basic DBus interface.

## Functions

### rb_shell_error_quark ()

    GQuark
    rb_shell_error_quark (void);

Returns the GQuark used for RBShell errors

#### Returns

shell error GQuark

### rb_shell_present ()

    gboolean
    rb_shell_present (RBShell *shell,
                      guint32 timestamp,
                      GError **error);

Attempts to display the main window to the user. See gtk_window_present for details.

#### Parameters

shell | the RBShell |
timestamp | GTK timestamp to use (for focus-stealing prevention) |
error | not used |

#### Returns

not used.

### rb_shell_guess_source_for_uri ()

    RBSource *
    rb_shell_guess_source_for_uri (RBShell *shell,
                                   const char *uri);

Attempts to locate the source that should handle the specified URI. This iterates through all sources, calling rb_source_want_uri, returning the source that returns the highest value.

#### Parameters

shell | the RBSource |
uri | the URI to guess a source for |

#### Returns

the most appropriate RBSource for the uri.

[transfer none]

### rb_shell_add_uri ()

    gboolean
    rb_shell_add_uri (RBShell *shell,
                      const char *uri,
                      const char *title,
                      const char *genre,
                      GError **error);

Adds the specified URI to the Rhythmbox database. Whether the title and genre specified are actually used is up to the source that handles the URI

#### Parameters

shell | the RBShell |
uri | the URI to add |
title | optional title value for the URI |
genre | optional genre value for the URI |
error | returns error information |

#### Returns

TRUE if the URI was added successfully

### rb_shell_load_uri ()

    gboolean
    rb_shell_load_uri (RBShell *shell,
                       const char *uri,
                       gboolean play,
                       GError **error);

Loads a URI representing a single song, a directory, a playlist, or an internet radio station, and optionally starts playing it.

For playlists containing only stream URLs, we either add the playlist itself (if it's remote) or each URL from it (if it's local). The main reason for this is so clicking on stream playlist links in web browsers works properly - the playlist file will be downloaded to /tmp/, and we can't add that to the database, so we need to add the stream URLs instead.

#### Parameters

shell | the RBShell |
uri | the URI to load |
play | if TRUE, start playing the URI (if possible) |
error | returns error information |

#### Returns

TRUE if the URI was added successfully

### rb_shell_toggle_visibility ()

    void
    rb_shell_toggle_visibility (RBShell *shell);

Toggles the visibility of the main Rhythmbox window.

#### Parameters

shell | the RBShell |

### rb_shell_get_song_properties ()

    gboolean
    rb_shell_get_song_properties (RBShell *shell,
                                  const char *uri,
                                  GHashTable **properties,
                                  GError **error);

Gathers and returns all metadata (including extra metadata such as album art URIs and lyrics) for the specified URI.

#### Parameters

shell | the RBShell |
uri | the URI to query |
properties | returns the properties of the specified URI. | [out callee-allocates][element-type utf8 GObject.Value]
error | returns error information |

#### Returns

`TRUE` if the URI is found in the database

### rb_shell_set_song_property ()

    gboolean
    rb_shell_set_song_property (RBShell *shell,
                                const char *uri,
                                const char *propname,
                                const GValue *value,
                                GError **error);

Attempts to set a property of a database entry identified by its URI. If the URI identifies a file and the property is one associated with a file metadata tag, the new value will be written to the file.

#### Parameters

shell | the RBShell |
uri | the URI to modify |
propname | the name of the property to modify |
value | the new value to set |
error | returns error information |

#### Returns

`TRUE` if the property was set successfully.

### rb_shell_quit ()

    gboolean
    rb_shell_quit (RBShell *shell,
                   GError **error);

Begins the process of shutting down Rhythmbox. This function will return. The error parameter and return value only exist because this function is part of the DBus interface.

#### Parameters

shell | the RBShell |
error | not used |

#### Returns

not important

### rb_shell_activate_source_by_uri ()

    gboolean
    rb_shell_activate_source_by_uri (RBShell *shell,
                                     const char *source_uri,
                                     guint play,
                                     GError **error);

Searches for a source matching `source_uri` and if found, selects it, and depending on the value of `play` , may start playing from it. Device-based sources will match the device node or mount point URI. Other types of sources may have their own URI scheme or format. This is part of the DBus interface.

#### Parameters

shell | the RBShell |
source_uri | URI for the source to activate |
play | 0: select source, 1: play source if not playing, 2: play source |
error | returns error information |

#### Returns

`TRUE` if successful

### rb_shell_activate_source ()

    gboolean
    rb_shell_activate_source (RBShell *shell,
                              RBSource *source,
                              guint play,
                              GError **error);

### rb_shell_notify_custom ()

    void
    rb_shell_notify_custom (RBShell *shell,
                            guint timeout,
                            const char *primary,
                            const char *secondary,
                            const char *image_uri,
                            gboolean requested);

### rb_shell_do_notify ()

    gboolean
    rb_shell_do_notify (RBShell *shell,
                        gboolean requested,
                        GError **error);

Displays a notification of the current playing track.

#### Parameters

shell | the RBShell |
requested | if `TRUE`, the notification was requested by some explicit user action |
error | not used |

#### Returns

not important

### rb_shell_register_entry_type_for_source ()

    void
    rb_shell_register_entry_type_for_source
                                   (RBShell *shell,
                                    RBSource *source,
                                    RhythmDBEntryType *type);

Registers a source as the owner of entries of the specified type. The main effect of this is that calling rb_shell_get_source_by_entry_type with the same entry type will return the source. A source should only be registered as the owner of a single entry type.

#### Parameters

shell | the RBShell |
source | the RBSource to register |
type | the RhythmDBEntryType to register for |

### rb_shell_get_source_by_entry_type ()

    RBSource *
    rb_shell_get_source_by_entry_type (RBShell *shell,
                                       RhythmDBEntryType *type);

Looks up and returns the source that owns entries of the specified type.

#### Parameters

shell | the RBShell |
type | entry type for which to find a source |

#### Returns

source instance, if any.

[transfer none]

### rb_shell_get_party_mode ()

    gboolean
    rb_shell_get_party_mode (RBShell *shell);

Returns `TRUE` if the shell is in party mode

#### Parameters

shell | the RBShell |

#### Returns

`TRUE` if the shell is in party mode

### rb_shell_append_display_page ()

    void
    rb_shell_append_display_page (RBShell *shell,
                                  RBDisplayPage *page,
                                  RBDisplayPage *parent);

Adds a new display page to the shell.

#### Parameters

shell | the RBShell |
page | the new RBDisplayPage |
parent | the parent page for the new page. | [allow-none]

### rb_shell_add_widget ()

    void
    rb_shell_add_widget (RBShell *shell,
                         GtkWidget *widget,
                         RBShellUILocation location,
                         gboolean expand,
                         gboolean fill);

Adds a widget to the main Rhythmbox window. See gtk_box_pack_start for details on how the expand and fill parameters work.

#### Parameters

shell | the RBShell |
widget | the GtkWidget to insert into the main window |
location | the location at which to insert the widget |
expand | whether the widget should be given extra space |
fill | whether the widget should fill all space allocated to it |

### rb_shell_remove_widget ()

    void
    rb_shell_remove_widget (RBShell *shell,
                            GtkWidget *widget,
                            RBShellUILocation location);

Removes a widget added with rb_shell_add_widget from the main window.

#### Parameters

shell | the RBShell |
widget | the GtkWidget to remove from the main window |
location | the UI location to which the widget was originally added |

## Types and Values

### enum RBShellActivationType

#### Members

RB_SHELL_ACTIVATION_SELECT |  |
RB_SHELL_ACTIVATION_PLAY |  |
RB_SHELL_ACTIVATION_ALWAYS_PLAY |  |

### enum RBShellError

#### Members

RB_SHELL_ERROR_NO_SUCH_URI |  |
RB_SHELL_ERROR_NO_SUCH_PROPERTY |  |
RB_SHELL_ERROR_IMMUTABLE_PROPERTY |  |
RB_SHELL_ERROR_INVALID_PROPERTY_TYPE |  |
RB_SHELL_ERROR_NO_SOURCE_FOR_URI |  |

### enum RBShellUILocation

#### Members

RB_SHELL_UI_LOCATION_SIDEBAR |  |
RB_SHELL_UI_LOCATION_RIGHT_SIDEBAR |  |
RB_SHELL_UI_LOCATION_MAIN_TOP |  |
RB_SHELL_UI_LOCATION_MAIN_BOTTOM |  |

### struct RBShell

    struct RBShell;

### struct RBShellClass

    struct RBShellClass {
            GtkApplicationClass parent_class;

    	/* signals */
    	gboolean (*visibility_changing) (RBShell *shell, gboolean initial, gboolean visible);
    	void	 (*visibility_changed) (RBShell *shell, gboolean visible);
    	void	 (*create_song_info) (RBShell *shell, RBSongInfo *song_info, gboolean multi);
    	void	 (*removable_media_scan_finished) (RBShell *shell);
    	void     (*database_load_complete) (RBShell *shell);
    };

## Property Details

### The `“accel-group”` property

      “accel-group”              GtkAccelGroup *

A GtkAccelGroup instance to use for additional accelerator keys

Owner: RBShell

Flags: Read

### The `“application”` property

      “application”              RBApplication *

RBApplication instance.

Owner: RBShell

Flags: Read / Write / Construct Only

### The `“autostarted”` property

      “autostarted”              gboolean

Whether Rhythmbox was automatically started by the session manager

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“clipboard”` property

      “clipboard”                RBShellClipboard *

The RBShellClipboard instance

Owner: RBShell

Flags: Read

### The `“db”` property

      “db”                       RhythmDB *

The RhythmDB instance

Owner: RBShell

Flags: Read

### The `“disable-plugins”` property

      “disable-plugins”          gboolean

If `TRUE`, disable plugins

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“display-page-model”` property

      “display-page-model”       RBDisplayPageModel *

The model underlying the display page tree

Owner: RBShell

Flags: Read

### The `“display-page-tree”` property

      “display-page-tree”        RBDisplayPageTree *

The RBDisplayPageTree instance

Owner: RBShell

Flags: Read

### The `“dry-run”` property

      “dry-run”                  gboolean

If TRUE, don't write back file metadata changes.

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“library-source”` property

      “library-source”           RBLibrarySource *

The library source

Owner: RBShell

Flags: Read

### The `“no-registration”` property

      “no-registration”          gboolean

If `TRUE`, disable single-instance features.

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“no-update”` property

      “no-update”                gboolean

If `TRUE`, don't update the database.

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: FALSE

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

      “playlist-manager”         RBPlaylistManager *

The RBPlaylistManager instance

Owner: RBShell

Flags: Read

### The `“playlists-file”` property

      “playlists-file”           gchar *

The path to the playlist file

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: "playlists.xml"

### The `“prefs”` property

      “prefs”                    RBShellPreferences *

The RBShellPreferences instance

Owner: RBShell

Flags: Read

### The `“queue-source”` property

      “queue-source”             RBPlayQueueSource *

The play queue source

Owner: RBShell

Flags: Read

### The `“removable-media-manager”` property

      “removable-media-manager”  RBRemovableMediaManager *

The RBRemovableMediaManager instance

Owner: RBShell

Flags: Read

### The `“rhythmdb-file”` property

      “rhythmdb-file”            gchar *

The path to the rhythmdb file

Owner: RBShell

Flags: Read / Write / Construct Only

Default value: "rhythmdb.xml"

### The `“selected-page”` property

      “selected-page”            RBDisplayPage *

The currently selected display page

Owner: RBShell

Flags: Read

### The `“shell-player”` property

      “shell-player”             RBShellPlayer *

The RBShellPlayer instance

Owner: RBShell

Flags: Read

### The `“task-list”` property

      “task-list”                RBTaskList *

The RBTaskList instance

Owner: RBShell

Flags: Read

### The `“track-transfer-queue”` property

      “track-transfer-queue”     RBTrackTransferQueue *

The RBTrackTransferQueue instance

Owner: RBShell

Flags: Read

### The `“visibility”` property

      “visibility”               gboolean

Whether the main window is currently visible.

Owner: RBShell

Flags: Read / Write

Default value: TRUE

### The `“window”` property

      “window”                   GtkWindow *

The main Rhythmbox window.

Owner: RBShell

Flags: Read

## Signal Details

### The `“create-song-info”` signal

    void
    user_function (RBShell    *shell,
                   RBSongInfo *song_info,
                   gboolean    multi,
                   gpointer    user_data)

Emitted when creating a new RBSongInfo window. Signal handlers can add pages to the song info window notebook to display additional information.

#### Parameters

shell | the RBShell |
song_info | the new RBSongInfo window |
multi | if `TRUE`, the song info window is for multiple entries |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“notify-custom”` signal

    void
    user_function (RBShell *shell,
                   guint    timeout,
                   gchar   *primary,
                   gchar   *secondary,
                   gchar   *image_uri,
                   gboolean requested,
                   gpointer user_data)

Emitted when a custom notification should be displayed to the user.

#### Parameters

shell | the RBShell |
timeout | length of time (in seconds) to display the notification |
primary | main notification text |
secondary | secondary notification text |
image_uri | URI for an image to include in the notification (optional) |
requested | if `TRUE`, the notification was triggered by an explicit user action |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“notify-playing-entry”` signal

    void
    user_function (RBShell *shell,
                   gboolean requested,
                   gpointer user_data)

Emitted when a notification should be displayed showing the current playing entry.

#### Parameters

shell | the RBShell |
requested | `TRUE` if user requested |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

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

    void
    user_function (RBShell *shell,
                   gboolean visibile,
                   gpointer user_data)

Emitted after the visibility of the main Rhythmbox window has changed.

#### Parameters

shell | the RBShell |
visibile | new visibility |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“visibility-changing”` signal

    gboolean
    user_function (RBShell *shell,
                   gboolean initial,
                   gboolean visible,
                   gpointer user_data)

Emitted before the visibility of the main window changes. The return value overrides the visibility setting. If multiple signal handlers are attached, the last one wins.

#### Parameters

shell | the RBShell |
initial | if `TRUE`, this is the initial visibility for the window |
visible | new shell visibility |
user_data | user data set when the signal handler was connected. |

Flags: Run Last