RBShell

RBShell — holds the Rhythmbox main window and everything else

Synopsis

                    RBShell;
                    RBShellClass;
RBShell *           rb_shell_new                        (gboolean no_registration,
                                                         gboolean no_update,
                                                         gboolean dry_run,
                                                         gboolean autostarted,
                                                         char *rhythmdb,
                                                         char *playlists);
gboolean            rb_shell_present                    (RBShell *shell,
                                                         guint32 timestamp,
                                                         GError **error);
RBSource *          rb_shell_guess_source_for_uri       (RBShell *shell,
                                                         const char *uri);
gboolean            rb_shell_add_uri                    (RBShell *shell,
                                                         const char *uri,
                                                         const char *title,
                                                         const char *genre,
                                                         GError **error);
gboolean            rb_shell_load_uri                   (RBShell *shell,
                                                         const char *uri,
                                                         gboolean play,
                                                         GError **error);
GObject *           rb_shell_get_player                 (RBShell *shell);
const char *        rb_shell_get_player_path            (RBShell *shell);
GObject *           rb_shell_get_playlist_manager       (RBShell *shell);
const char *        rb_shell_get_playlist_manager_path  (RBShell *shell);
GObject *           rb_shell_get_ui_manager             (RBShell *shell);
void                rb_shell_toggle_visibility          (RBShell *shell);
gboolean            rb_shell_get_song_properties        (RBShell *shell,
                                                         const char *uri,
                                                         GHashTable **properties,
                                                         GError **error);
gboolean            rb_shell_set_song_property          (RBShell *shell,
                                                         const char *uri,
                                                         const char *propname,
                                                         const GValue *value,
                                                         GError **error);
gboolean            rb_shell_add_to_queue               (RBShell *shell,
                                                         const gchar *uri,
                                                         GError **error);
gboolean            rb_shell_remove_from_queue          (RBShell *shell,
                                                         const gchar *uri,
                                                         GError **error);
gboolean            rb_shell_clear_queue                (RBShell *shell,
                                                         GError **error);
gboolean            rb_shell_quit                       (RBShell *shell,
                                                         GError **error);
gboolean            rb_shell_do_notify                  (RBShell *shell,
                                                         gboolean requested,
                                                         GError **error);
void                rb_shell_register_entry_type_for_source
                                                        (RBShell *shell,
                                                         RBSource *source,
                                                         RhythmDBEntryType *type);
RBSource *          rb_shell_get_source_by_entry_type   (RBShell *shell,
                                                         RhythmDBEntryType *type);
gboolean            rb_shell_get_party_mode             (RBShell *shell);
void                rb_shell_append_source              (RBShell *shell,
                                                         RBSource *source,
                                                         RBSource *parent);
void                rb_shell_add_widget                 (RBShell *shell,
                                                         GtkWidget *widget,
                                                         RBShellUILocation location,
                                                         gboolean expand,
                                                         gboolean fill);
void                rb_shell_remove_widget              (RBShell *shell,
                                                         GtkWidget *widget,
                                                         RBShellUILocation location);
void                rb_shell_notebook_set_page          (RBShell *shell,
                                                         GtkWidget *widget);

Object Hierarchy

  GObject
   +----RBShell

Properties

  "autostarted"              gboolean              : Read / Write / Construct Only
  "clipboard"                RBShellClipboard*     : Read
  "db"                       RhythmDB*             : Read
  "dry-run"                  gboolean              : Read / Write / Construct Only
  "library-source"           RBLibrarySource*      : Read
  "no-registration"          gboolean              : Read / Write / Construct Only
  "no-update"                gboolean              : Read / Write / Construct Only
  "playlist-manager"         RBPlaylistManager*    : Read
  "playlists-file"           gchar*                : Read / Write / Construct Only
  "prefs"                    RBShellPreferences*   : Read
  "queue-source"             RBPlayQueueSource*    : Read
  "removable-media-manager"  RBRemovableMediaManager*  : Read
  "rhythmdb-file"            gchar*                : Read / Write / Construct Only
  "selected-source"          RBSource*             : Read
  "shell-player"             RBShellPlayer*        : Read
  "source-header"            RBSourceHeader*       : Read
  "sourcelist"               RBSourceList*         : Read
  "sourcelist-model"         RBSourceListModel*    : Read
  "track-transfer-queue"     RBTrackTransferQueue*  : Read
  "ui-manager"               GtkUIManager*         : Read
  "visibility"               gboolean              : Read / Write
  "window"                   GtkWindow*            : Read

Signals

  "create-song-info"                               : Run Last
  "database-load-complete"                         : Run Last
  "notify-custom"                                  : Run Last
  "notify-playing-entry"                           : Run Last
  "removable-media-scan-finished"                  : Run Last
  "visibility-changed"                             : Run Last
  "visibility-changing"                            : Run Last

Description

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

Details

RBShell

typedef struct _RBShell RBShell;


RBShellClass

typedef struct {
        GObjectClass 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);
} RBShellClass;


rb_shell_new ()

RBShell *           rb_shell_new                        (gboolean no_registration,
                                                         gboolean no_update,
                                                         gboolean dry_run,
                                                         gboolean autostarted,
                                                         char *rhythmdb,
                                                         char *playlists);

Creates the Rhythmbox shell. This is effectively a singleton, so it doesn't make sense to call this from anywhere other than main.c.

no_registration :

if TRUE, single-instance features are disabled

no_update :

if TRUE, don't update the database file

dry_run :

if TRUE, don't write back file metadata changes

autostarted :

TRUE if autostarted by the session manager

rhythmdb :

path to the database file

playlists :

path to the playlist file

Returns :

the RBShell instance

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.

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.

shell :

the RBSource

uri :

the URI to guess a source for

Returns :

the most appropriate RBSource for the uri

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

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.

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_get_player ()

GObject *           rb_shell_get_player                 (RBShell *shell);

Returns the RBShellPlayer object

shell :

the RBShell

Returns :

the RBShellPlayer object

rb_shell_get_player_path ()

const char *        rb_shell_get_player_path            (RBShell *shell);

Returns the DBus object path for the RBShellPlayer

shell :

the RBShell

Returns :

the DBus object path for the RBShellPlayer

rb_shell_get_playlist_manager ()

GObject *           rb_shell_get_playlist_manager       (RBShell *shell);

Returns the RBPlaylistManager object

shell :

the RBShell

Returns :

the RBPlaylistManager object

rb_shell_get_playlist_manager_path ()

const char *        rb_shell_get_playlist_manager_path  (RBShell *shell);

Returns the DBus path for the RBPlaylistManager object

shell :

the RBShell

Returns :

the DBus object path for the RBPlaylistManager

rb_shell_get_ui_manager ()

GObject *           rb_shell_get_ui_manager             (RBShell *shell);

Returns the main GtkUIManager object

shell :

the RBShell

Returns :

the main GtkUIManager object

rb_shell_toggle_visibility ()

void                rb_shell_toggle_visibility          (RBShell *shell);

Toggles the visibility of the main Rhythmbox window.

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.

shell :

the RBShell

uri :

the URI to query

properties :

returns the properties of the specified URI

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.

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_add_to_queue ()

gboolean            rb_shell_add_to_queue               (RBShell *shell,
                                                         const gchar *uri,
                                                         GError **error);

Adds the specified URI to the play queue. This only works if URI is already in the database.

shell :

the RBShell

uri :

the URI to add to the play queue

error :

not used

Returns :

not used

rb_shell_remove_from_queue ()

gboolean            rb_shell_remove_from_queue          (RBShell *shell,
                                                         const gchar *uri,
                                                         GError **error);

Removes the specified URI from the play queue. If the URI is not in the play queue, nothing happens.

shell :

the RBShell

uri :

the URI to remove from the play queue

error :

not used

Returns :

not used.

rb_shell_clear_queue ()

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

Removes all entries from the play queue.

shell :

the RBShell

error :

not used

Returns :

not used

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.

shell :

the RBShell

error :

not used

Returns :

not important

rb_shell_do_notify ()

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

Displays a notification of the current playing track.

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.

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.

shell :

the RBShell

type :

entry type for which to find a source

Returns :

source instance, if any

rb_shell_get_party_mode ()

gboolean            rb_shell_get_party_mode             (RBShell *shell);

Returns TRUE if the shell is in party mode

shell :

the RBShell

Returns :

TRUE if the shell is in party mode

rb_shell_append_source ()

void                rb_shell_append_source              (RBShell *shell,
                                                         RBSource *source,
                                                         RBSource *parent);

Registers a new source with the shell. All sources must be registered.

shell :

the RBShell

source :

the new RBSource

parent :

the parent source for the new source (optional)

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.

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.

shell :

the RBShell

widget :

the GtkWidget to remove from the main window

location :

the UI location to which the widget was originally added

rb_shell_notebook_set_page ()

void                rb_shell_notebook_set_page          (RBShell *shell,
                                                         GtkWidget *widget);

Changes the visible page in the main window notebook widget. Use this to display widgets added to the RB_SHELL_UI_LOCATION_MAIN_NOTEBOOK location.

shell :

the RBShell

widget :

GtkWidget for the page to display

Property Details

The "autostarted" property

  "autostarted"              gboolean              : Read / Write / Construct Only

Whether Rhythmbox was automatically started by the session manager

Default value: FALSE


The "clipboard" property

  "clipboard"                RBShellClipboard*     : Read

The RBShellClipboard instance


The "db" property

  "db"                       RhythmDB*             : Read

The RhythmDB instance


The "dry-run" property

  "dry-run"                  gboolean              : Read / Write / Construct Only

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

Default value: FALSE


The "library-source" property

  "library-source"           RBLibrarySource*      : Read

The library source


The "no-registration" property

  "no-registration"          gboolean              : Read / Write / Construct Only

If TRUE, disable single-instance features.

Default value: FALSE


The "no-update" property

  "no-update"                gboolean              : Read / Write / Construct Only

If TRUE, don't update the database.

Default value: FALSE


The "playlist-manager" property

  "playlist-manager"         RBPlaylistManager*    : Read

The RBPlaylistManager instance


The "playlists-file" property

  "playlists-file"           gchar*                : Read / Write / Construct Only

The path to the playlist file

Default value: "playlists.xml"


The "prefs" property

  "prefs"                    RBShellPreferences*   : Read

The RBShellPreferences instance


The "queue-source" property

  "queue-source"             RBPlayQueueSource*    : Read

The play queue source


The "removable-media-manager" property

  "removable-media-manager"  RBRemovableMediaManager*  : Read

The RBRemovableMediaManager instance


The "rhythmdb-file" property

  "rhythmdb-file"            gchar*                : Read / Write / Construct Only

The path to the rhythmdb file

Default value: "rhythmdb.xml"


The "selected-source" property

  "selected-source"          RBSource*             : Read

The currently selected source object


The "shell-player" property

  "shell-player"             RBShellPlayer*        : Read

The RBShellPlayer instance


The "source-header" property

  "source-header"            RBSourceHeader*       : Read

The RBSourceHeader instance


The "sourcelist" property

  "sourcelist"               RBSourceList*         : Read

The RBSourceList instance


The "sourcelist-model" property

  "sourcelist-model"         RBSourceListModel*    : Read

The tree model underlying the source list.


The "track-transfer-queue" property

  "track-transfer-queue"     RBTrackTransferQueue*  : Read

The RBTrackTransferQueue instance


The "ui-manager" property

  "ui-manager"               GtkUIManager*         : Read

The GtkUIManager instance


The "visibility" property

  "visibility"               gboolean              : Read / Write

Whether the main window is currently visible.

Default value: TRUE


The "window" property

  "window"                   GtkWindow*            : Read

The main Rhythmbox window.

Signal Details

The "create-song-info" signal

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

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

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.

The "database-load-complete" signal

void                user_function                      (RBShell *shell,
                                                        gpointer user_data)      : Run Last

Emitted when the database has been loaded. This is intended to allow DBus clients that start a new instance of the application to wait until a reasonable amount of state has been loaded before making further requests.

shell :

the RBShell

user_data :

user data set when the signal handler was connected.

The "notify-custom" signal

void                user_function                      (RBShell   *shell,
                                                        guint      timeout,
                                                        gchar     *primary,
                                                        gchar     *secondary,
                                                        GdkPixbuf *pixbuf,
                                                        gboolean   requested,
                                                        gpointer   user_data)      : Run Last

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

shell :

the RBShell

timeout :

length of time (in seconds) to display the notification

primary :

main notification text

secondary :

secondary notification text

pixbuf :

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.

The "notify-playing-entry" signal

void                user_function                      (RBShell *shell,
                                                        gboolean arg1,
                                                        gpointer user_data)      : Run Last

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

shell :

the RBShell

user_data :

user data set when the signal handler was connected.

The "removable-media-scan-finished" signal

void                user_function                      (RBShell *shell,
                                                        gpointer user_data)      : Run Last

Emitted when the initial scan for removable media devices is complete. This is intended to allow plugins to request a device scan only if the scan on startup has already been done, but it isn't very useful for that. See "scanned" for a better approach to this problem.

shell :

the RBShell

user_data :

user data set when the signal handler was connected.

The "visibility-changed" signal

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

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

shell :

the RBShell

visibile :

new visibility

user_data :

user data set when the signal handler was connected.

The "visibility-changing" signal

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

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.

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.