## rb-song-info

rb-song-info — song properties dialog

## Synopsis

                        RBSongInfo;
                        RBSongInfoClass;
    GtkWidget*          rb_song_info_new                    (RBSource *source,
                                                             RBEntryView *entry_view);
    guint               rb_song_info_append_page            (RBSongInfo *info,
                                                             const char *title,
                                                             GtkWidget *page);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkWindow
                                           +----GtkDialog
                                                 +----RBSongInfo

## Implemented Interfaces

RBSongInfo implements AtkImplementorIface and GtkBuildable.

## Properties

      "current-entry"            RhythmDBEntry*        : Read
      "entry-view"               RBEntryView*          : Read / Write / Construct Only
      "selected-entries"         GValueArray*          : Read
      "source"                   RBSource*             : Read / Write / Construct Only

## Signals

      "post-metadata-change"                           : Run Last
      "pre-metadata-change"                            : Run Last

## Description

Displays song properties and, if we know how to edit tags in the file, allows the user to edit them.

This class has two modes. It can display and edit properties of a single entry, in which case it uses a GtkNotebook to split the properties across 'basic' and 'details' pages, and it can display and edit properties of multiple entries at a time, in which case a smaller set of properties is displayed in a single set.

In single-entry mode, it is possible to add extra pages to the GtkNotebook widget in the dialog. The 'create-song-info' signal is emitted by the RBShell object, allowing signal handlers to add pages by calling rb_song_info_append_page. The lyrics plugin is currently the only place where this ability is used. In this mode, the dialog features 'back' and 'forward' buttons that move to the next or previous entries from the currently displayed track list.

In multiple-entry mode, only the set of properties that can usefully be set across multiple entries at once are displayed.

When the dialog is closed, any changes made will be applied to the entry (or entries) that were displayed in the dialog. For songs in the library, this will result in the song tags being updated on disk. For other entry types, this only updates the data store in the database.

## Details

### RBSongInfo

    typedef struct _RBSongInfo RBSongInfo;

### RBSongInfoClass

    typedef struct {
    	GtkDialogClass parent_class;

    	void (*pre_metadata_change) (RBSongInfo *info, RhythmDBEntry *entry);
    	void (*post_metadata_change) (RBSongInfo *info, RhythmDBEntry *entry);
    } RBSongInfoClass;

### rb_song_info_new ()

    GtkWidget*          rb_song_info_new                    (RBSource *source,
                                                             RBEntryView *entry_view);

Creates a new RBSongInfo for the selected entry or entries in the specified entry view.

`source` : | RBSource creating the song properties window
`entry_view` : | the RBEntryView to get selection data from
Returns : | the new song properties window

### rb_song_info_append_page ()

    guint               rb_song_info_append_page            (RBSongInfo *info,
                                                             const char *title,
                                                             GtkWidget *page);

Adds a new page to the song properties window. Should be called in a handler connected to the RBShell 'create-song-info' signal.

`info` : | a RBSongInfo
`title` : | the title of the new page
`page` : | the page GtkWidget
Returns : | the page number

## Property Details

### The `"current-entry"` property

      "current-entry"            RhythmDBEntry*        : Read

The RhythmDBEntry that is currently being displayed. Will be NULL for multiple-entry song properties windows.

### The `"entry-view"` property

      "entry-view"               RBEntryView*          : Read / Write / Construct Only

The RBEntryView for the source that created the song properties window. Used find the set of selected entries, and to change the selection when the 'back' and 'forward' buttons are pressed.

### The `"selected-entries"` property

      "selected-entries"         GValueArray*          : Read

The set of RhythmDBEntry objects currently being displayed. Valid for both single-entry and multiple-entry song properties windows.

### The `"source"` property

      "source"                   RBSource*             : Read / Write / Construct Only

The RBSource that created the song properties window. Used to update for track list changes, and to find the sets of albums, artist, and genres to use for tag edit completion.

## Signal Details

### The `"post-metadata-change"` signal

    void                user_function                      (RBSongInfo    *song_info,
                                                            RhythmDBEntry *entry,
                                                            gpointer       user_data)      : Run Last

Emitted just after changes have been applied to the database. Probably useless.

`song_info` : | the RBSongInfo instance
`entry` : | the RhythmDBEntry that was changed
`user_data` : | user data set when the signal handler was connected.

### The `"pre-metadata-change"` signal

    void                user_function                      (RBSongInfo    *song_info,
                                                            RhythmDBEntry *entry,
                                                            gpointer       user_data)      : Run Last

Emitted just before the changes made in the song properties window are applied to the database. This is only emitted in the single-entry case.

`song_info` : | the RBSongInfo instance
`entry` : | the RhythmDBEntry being changed
`user_data` : | user data set when the signal handler was connected.