![]() |
![]() |
![]() |
Rhythmbox Development Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
struct RBShell; struct RBShellClass; RBShell * rb_shell_new (gboolean no_registration
,gboolean no_update
,gboolean dry_run
,gboolean autostarted
,gboolean disable_plugins
,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_add_widget (RBShell *shell
,GtkWidget *widget
,RBShellUILocation location
,gboolean expand
,gboolean fill
); void rb_shell_remove_widget (RBShell *shell
,GtkWidget *widget
,RBShellUILocation location
);
"autostarted" gboolean : Read / Write / Construct Only "clipboard" RBShellClipboard* : Read "db" RhythmDB* : Read "disable-plugins" gboolean : Read / Write / Construct Only "display-page-model" RBDisplayPageModel* : Read "display-page-tree" RBDisplayPageTree* : 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-page" RBDisplayPage* : Read "shell-player" RBShellPlayer* : Read "source-header" RBSourceHeader* : Read "track-transfer-queue" RBTrackTransferQueue* : Read "ui-manager" GtkUIManager* : Read "visibility" gboolean : Read / Write "window" GtkWindow* : Read
"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
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.
struct RBShellClass { 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); };
RBShell * rb_shell_new (gboolean no_registration
,gboolean no_update
,gboolean dry_run
,gboolean autostarted
,gboolean disable_plugins
,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.
|
if TRUE , single-instance features are disabled |
|
if TRUE , don't update the database file |
|
if TRUE , don't write back file metadata changes |
|
TRUE if autostarted by the session manager |
|
TRUE if the plugins should be disabled |
|
path to the database file |
|
path to the playlist file |
Returns : |
the RBShell instance |
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.
|
the RBShell |
|
GTK timestamp to use (for focus-stealing prevention) |
|
not used |
Returns : |
not used. |
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.
|
the RBSource |
|
the URI to guess a source for |
Returns : |
the most appropriate RBSource for the uri. [transfer none] |
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
|
the RBShell |
|
the URI to add |
|
optional title value for the URI |
|
optional genre value for the URI |
|
returns error information |
Returns : |
TRUE if the URI was added successfully |
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.
|
the RBShell |
|
the URI to load |
|
if TRUE, start playing the URI (if possible) |
|
returns error information |
Returns : |
TRUE if the URI was added successfully |
GObject * rb_shell_get_player (RBShell *shell
);
Returns the RBShellPlayer object
|
the RBShell |
Returns : |
the RBShellPlayer object. [transfer none] |
const char * rb_shell_get_player_path (RBShell *shell
);
Returns the DBus object path for the RBShellPlayer
|
the RBShell |
Returns : |
the DBus object path for the RBShellPlayer |
GObject * rb_shell_get_playlist_manager (RBShell *shell
);
Returns the RBPlaylistManager object
|
the RBShell |
Returns : |
the RBPlaylistManager object. [transfer none] |
const char * rb_shell_get_playlist_manager_path (RBShell *shell
);
Returns the DBus path for the RBPlaylistManager object
|
the RBShell |
Returns : |
the DBus object path for the RBPlaylistManager |
GObject * rb_shell_get_ui_manager (RBShell *shell
);
Returns the main GtkUIManager object
|
the RBShell |
Returns : |
the main GtkUIManager object. [transfer none] |
void rb_shell_toggle_visibility (RBShell *shell
);
Toggles the visibility of the main Rhythmbox window.
|
the RBShell |
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.
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.
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.
|
the RBShell |
|
the URI to add to the play queue |
|
not used |
Returns : |
not used |
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.
|
the RBShell |
|
the URI to remove from the play queue |
|
not used |
Returns : |
not used. |
gboolean rb_shell_clear_queue (RBShell *shell
,GError **error
);
Removes all entries from the play queue.
|
the RBShell |
|
not used |
Returns : |
not used |
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.
|
the RBShell |
|
not used |
Returns : |
not important |
gboolean rb_shell_do_notify (RBShell *shell
,gboolean requested
,GError **error
);
Displays a notification of the current playing track.
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.
|
the RBShell |
|
the RBSource to register |
|
the RhythmDBEntryType to register for |
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.
|
the RBShell |
|
entry type for which to find a source |
Returns : |
source instance, if any. [transfer none] |
gboolean rb_shell_get_party_mode (RBShell *shell
);
Returns TRUE
if the shell is in party mode
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.
void rb_shell_remove_widget (RBShell *shell
,GtkWidget *widget
,RBShellUILocation location
);
Removes a widget added with rb_shell_add_widget from the main window.
"autostarted"
property"autostarted" gboolean : Read / Write / Construct Only
Whether Rhythmbox was automatically started by the session manager
Default value: FALSE
"disable-plugins"
property"disable-plugins" gboolean : Read / Write / Construct Only
If TRUE
, disable plugins
Default value: FALSE
"display-page-model"
property "display-page-model" RBDisplayPageModel* : Read
The model underlying the display page tree
"display-page-tree"
property "display-page-tree" RBDisplayPageTree* : Read
The RBDisplayPageTree instance
"dry-run"
property"dry-run" gboolean : Read / Write / Construct Only
If TRUE, don't write back file metadata changes.
Default value: FALSE
"no-registration"
property"no-registration" gboolean : Read / Write / Construct Only
If TRUE
, disable single-instance features.
Default value: FALSE
"no-update"
property"no-update" gboolean : Read / Write / Construct Only
If TRUE
, don't update the database.
Default value: FALSE
"playlist-manager"
property"playlist-manager" RBPlaylistManager* : Read
The RBPlaylistManager instance
"playlists-file"
property"playlists-file" gchar* : Read / Write / Construct Only
The path to the playlist file
Default value: "playlists.xml"
"removable-media-manager"
property"removable-media-manager" RBRemovableMediaManager* : Read
The RBRemovableMediaManager instance
"rhythmdb-file"
property"rhythmdb-file" gchar* : Read / Write / Construct Only
The path to the rhythmdb file
Default value: "rhythmdb.xml"
"selected-page"
property "selected-page" RBDisplayPage* : Read
The currently selected display page
"track-transfer-queue"
property"track-transfer-queue" RBTrackTransferQueue* : Read
The RBTrackTransferQueue instance
"visibility"
property"visibility" gboolean : Read / Write
Whether the main window is currently visible.
Default value: TRUE
"create-song-info"
signalvoid 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.
|
the RBShell |
|
the new RBSongInfo window |
|
if TRUE , the song info window is for multiple entries |
|
user data set when the signal handler was connected. |
"database-load-complete"
signalvoid 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.
|
the RBShell |
|
user data set when the signal handler was connected. |
"notify-custom"
signalvoid user_function (RBShell *shell,
guint timeout,
gchar *primary,
gchar *secondary,
gchar *image_uri,
gboolean requested,
gpointer user_data) : Run Last
Emitted when a custom notification should be displayed to the user.
|
the RBShell |
|
length of time (in seconds) to display the notification |
|
main notification text |
|
secondary notification text |
|
URI for an image to include in the notification (optional) |
|
if TRUE , the notification was triggered by an explicit user action |
|
user data set when the signal handler was connected. |
"notify-playing-entry"
signalvoid user_function (RBShell *shell,
gboolean arg1,
gpointer user_data) : Run Last
Emitted when a notification should be displayed showing the current playing entry.
|
the RBShell |
|
user data set when the signal handler was connected. |
"removable-media-scan-finished"
signalvoid 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.
|
the RBShell |
|
user data set when the signal handler was connected. |
"visibility-changed"
signalvoid user_function (RBShell *shell,
gboolean visibile,
gpointer user_data) : Run Last
Emitted after the visibility of the main Rhythmbox window has changed.
|
the RBShell |
|
new visibility |
|
user data set when the signal handler was connected. |
"visibility-changing"
signalgboolean 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.