## rb-playlist-source

rb-playlist-source — Base class for playlist sources

## Synopsis

                        RBPlaylistSource;
                        RBPlaylistSourceClass;
    RBSource*           rb_playlist_source_new_from_xml     (RBShell *shell,
                                                             xmlNodePtr node);
    void                rb_playlist_source_save_playlist    (RBPlaylistSource *source,
                                                             const char *uri,
                                                             gboolean m3u_format);
    void                rb_playlist_source_save_to_xml      (RBPlaylistSource *source,
                                                             xmlNodePtr parent_node);
    void                rb_playlist_source_set_query_model  (RBPlaylistSource *source,
                                                             RhythmDBQueryModel *model);
    RhythmDBQueryModel* rb_playlist_source_get_query_model  (RBPlaylistSource *source);
    RhythmDB*           rb_playlist_source_get_db           (RBPlaylistSource *source);
    void                rb_playlist_source_mark_dirty       (RBPlaylistSource *source);
    gboolean            rb_playlist_source_location_in_map  (RBPlaylistSource *source,
                                                             const char *location);
    gboolean            rb_playlist_source_add_to_map       (RBPlaylistSource *source,
                                                             const char *location);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkHBox
                                           +----RBSource
                                                 +----RBPlaylistSource
                                                       +----RBAutoPlaylistSource
                                                       +----RBStaticPlaylistSource

## Implemented Interfaces

RBPlaylistSource implements AtkImplementorIface and GtkBuildable.

## Properties

      "db"                       RhythmDB*             : Read
      "dirty"                    gboolean              : Read
      "is-local"                 gboolean              : Read / Write / Construct Only
      "sorting-name"             gchar*                : Read / Write

## Description

This class provides some common infrastructure for playlist sources. A playlist, in this context, is a persistent user-defined selection from a set of songs. Playlists (static and auto) based on the main library are saved to the playlists.xml file stored alongside the rhythmdb.xml file. Playlists on portable music players are saved on the device in the format the player itself supports.

This class provides most of the source UI (excluding the search bar), holds some of the framework for loading and saving the playlists.xml file, and records which playlists need to be saved.

## Details

### RBPlaylistSource

    typedef struct _RBPlaylistSource RBPlaylistSource;

### RBPlaylistSourceClass

    typedef struct {
    	RBSourceClass parent;

    	/* methods */
    	void	(*impl_show_entry_view_popup)	(RBPlaylistSource *source, RBEntryView *view, gboolean over_entry);
    	void	(*impl_save_contents_to_xml)	(RBPlaylistSource *source, xmlNodePtr node);
    	void	(*impl_mark_dirty)		(RBPlaylistSource *source);
    } RBPlaylistSourceClass;

### rb_playlist_source_new_from_xml ()

    RBSource*           rb_playlist_source_new_from_xml     (RBShell *shell,
                                                             xmlNodePtr node);

Constructs a playlist source instance from the XML serialized format. This function knows about all the playlist types that can be saved to disk, and it hands off the XML node to the appropriate constructor based on the 'type' attribute of the root node of the playlist.

`shell` : | the RBShell instance
`node` : | libxml node containing the playlist
Returns : | the playlist

### rb_playlist_source_save_playlist ()

    void                rb_playlist_source_save_playlist    (RBPlaylistSource *source,
                                                             const char *uri,
                                                             gboolean m3u_format);

Saves the playlist to an external file in a standard format (M3U or PLS).

`source` : | a RBPlaylistSource
`uri` : | destination URI
`m3u_format` : | if TRUE, save as .m3u, otherwise .pls

### rb_playlist_source_save_to_xml ()

    void                rb_playlist_source_save_to_xml      (RBPlaylistSource *source,
                                                             xmlNodePtr parent_node);

Converts the playlist to XML format, below the specified parent node.

`source` : | the playlist source to save
`parent_node` : | libxml node below which to save the playlist

### rb_playlist_source_set_query_model ()

    void                rb_playlist_source_set_query_model  (RBPlaylistSource *source,
                                                             RhythmDBQueryModel *model);

Sets a new query model for the playlist. This updates the entry view to use the new query model and also updates the source query-model property.

This needs to be called when the playlist subclass creates a new query model.

`source` : | the RBPlaylistSource
`model` : | the new RhythmDBQueryModel

### rb_playlist_source_get_query_model ()

    RhythmDBQueryModel* rb_playlist_source_get_query_model  (RBPlaylistSource *source);

Returns the current RhythmDBQueryModel for the playlist. The caller must not unref the object once finished with it.

`source` : | a RBPlaylistSource
Returns : | the current RhythmDBQueryModel

### rb_playlist_source_get_db ()

    RhythmDB*           rb_playlist_source_get_db           (RBPlaylistSource *source);

Returns the RhythmDB instance. The caller must not unref the object once finished with it.

`source` : | a RBPlaylistSource
Returns : | the RhythmDB instance

### rb_playlist_source_mark_dirty ()

    void                rb_playlist_source_mark_dirty       (RBPlaylistSource *source);

Marks the playlist dirty. This generally means that the playlist will be saved to disk fairly soon, but the exact meaning can vary between playlist types.

`source` : | a RBPlaylistSource

### rb_playlist_source_location_in_map ()

    gboolean            rb_playlist_source_location_in_map  (RBPlaylistSource *source,
                                                             const char *location);

`source` : | a RBPlaylistSource
`location` : | a URI to check
Returns : | TRUE if the specified URI is in the playlist entry map

### rb_playlist_source_add_to_map ()

    gboolean            rb_playlist_source_add_to_map       (RBPlaylistSource *source,
                                                             const char *location);

Adds a URI to the playlist's entry map. This is useful when the URI is being added to the database, but no entry exists for it yet. When the entry is created, it will be added to the query model.

`source` : | a RBPlaylistSource
`location` : | a URI to add
Returns : | TRUE if the URI was added to the entry map, FALSE if it was already there.

## Property Details

### The `"db"` property

      "db"                       RhythmDB*             : Read

The RhythmDB instance

### The `"dirty"` property

      "dirty"                    gboolean              : Read

Whether the playlist has been changed since it was last saved to disk.

Default value: FALSE

### The `"is-local"` property

      "is-local"                 gboolean              : Read / Write / Construct Only

Whether the playlist is attached to the local library. Remote DAAP playlists, for example, are not local.

Default value: TRUE

### The `"sorting-name"` property

      "sorting-name"             gchar*                : Read / Write

A unique-ish name for the playlist, used to construct gconf keys to store information relating to the playlist.

Default value: NULL