Docs for PlaylistManager

src/scripting/python/playlistmanager.sip

@@ -4,50 +4,318 @@ class PlaylistManagerInterface : QObject {
 #include "playlist/playlistmanager.h"
 %End
 
+%Docstring
+Container for all of Clementine's playlists.
+
+Clementine supports multiple tabbed playlists - a user can create a new
+playlist by clicking the C{New playlist} button at the top of the window, and
+switch between them by using the tabs above each playlist.
+This class manages the list of playlists and allows scripts to get at each
+individual playlist, create new ones or change existing ones.
+
+In the list of playlists, one playlist is the I{current} playlist and one is
+the I{active} playlist:
+  - The B{current} playlist is the one that is displayed in the PlaylistView
+    right now - the user can make a different playlist current by clicking on
+    another tab.  Actions such as clearing or shuffling the playlist, or
+    adding new songs, should operate on the current playlist by default.
+  - The B{active} playlist is the playlist that contains the currently
+    playing song, or if the player is stopped, it is the playlist that will
+    start playing when the user presses C{Play}.  The active and current
+    playlists don't have to be the same (although they sometimes are) - songs
+    can be playing from one playlist while another is displayed in the window.
+
+There will always be at least one playlist in the PlaylistManager, and the
+active and current playlists are guaranteed to always be valid.
+
+Each playlist has an ID that is used to save it in the database.  You can get
+the ID of a playlist by calling the L{Playlist.id()} method.
+
+You can't create new PlaylistManagers, there is only one instance of this
+class ever created.  You can access it through the global variable in the
+L{clementine} module:
+
+  >>> clementine.playlists
+%End
+
 public:
   int current_id() const;
+%Docstring
+current_id() -> int
+Returns the ID of the current playlist.
+%End
+
   int active_id() const;
+%Docstring
+active_id() -> int
+Returns the ID of the active playlist.
+%End
 
   Playlist* playlist(int id) const;
+%Docstring
+playlist(id) -> L{Playlist}
+Returns the Playlist with the given identifier.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   Playlist* current() const;
+%Docstring
+current() -> L{Playlist}
+Returns the current playlist.
+
+Equivalent to C{playlist(current_id())}.
+%End
+
   Playlist* active() const;
+%Docstring
+active() -> L{Playlist}
+Returns the active playlist.
+
+Equivalent to C{playlist(active_id())}.
+%End
 
   const QList<Playlist*> GetAllPlaylists() const;
+%Docstring
+GetAllPlaylists() -> list of L{Playlist}s
+Returns a list containing all the playlists.
+%End
 
   const QItemSelection& selection(int id) const;
+%Docstring
+selection(id) -> PyQt4.QtGui.QItemSelection
+Returns any selected items in the playlist with the given ID.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   const QItemSelection& current_selection() const;
+%Docstring
+current_selection() -> PyQt4.QtGui.QItemSelection
+Returns any selected items in the current playlist.
+
+Equivalent to C{selection(current_id())}.
+%End
+
   const QItemSelection& active_selection() const;
+%Docstring
+active_selection() -> PyQt4.QtGui.QItemSelection
+Returns any selected items in the active playlist.
+
+Equivalent to C{selection(active_id())}.
+%End
 
   QString name(int index) const;
+%Docstring
+name(id) -> str
+Returns the name of the playlist with the given ID.
+
+A playlist's name is shown in the tab bar above the playlist.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
 
   LibraryBackend* library_backend() const;
+%Docstring
+library_backend() -> L{LibraryBackend}
+Convenience function to return the local library backend.
+%End
+
   // PlaylistBackend* playlist_backend() const;
+
   PlaylistSequence* sequence() const;
+%Docstring
+sequence() -> L{PlaylistSequence}
+Convenience function to return the playlist sequence controller.
+
+A playlist sequence controller manages the repeat/shuffle state.  All
+playlists share the same playlist sequence controller.
+%End
+
   PlaylistParser* parser() const;
+%Docstring
+parser() -> L{PlaylistParser}
+Convenience function to return the playlist parser.
+
+This is used when loading and saving playlists to files (eg. C{.pls} or
+C{.xspf}) with the L{Load} and L{Save} methods.
+%End
 
 public slots:
   void New(const QString& name, const SongList& songs = SongList());
+%Docstring
+New(name, songs)
+Creates a new playlist and optionally fills it with a list of songs.
+
+The newly created playlist is made current and can be accessed with
+L{current()}.
+
+@param songs: A list of songs to add to the new playlist.  Defaults to the
+  empty list.
+@type songs: list of L{Song}s
+%End
+
   void Load(const QString& filename);
+%Docstring
+Load(filename)
+Creates a new playlist from a playlist file on disk.
+
+The playlist file is loaded by using the L{PlaylistParser} returned by
+L{parser()}.  The newly created playlist is made current and can be accessed
+with L{current()}.
+
+@note: If the file does not exist or can't be parsed for whatever reason, an
+  error dialog is shown and no playlist is created.
+%End
+
   void Save(int id, const QString& filename);
+%Docstring
+Save(id, filename)
+Saves the playlist with the given ID to a file.
+
+The playlist file is written by using the L{PlaylistParser} returned by
+L{parser()}.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   void Rename(int id, const QString& new_name);
+%Docstring
+Rename(id, new_name)
+Renames the playlist with the given ID.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   void Remove(int id);
+%Docstring
+Remove(id)
+Removes the playlist with the given ID.
+
+If you remove either the active or the current playlist then another playlist
+will be made active/current to replace it.  It is not possible to remove the
+last playlist - this function will silently return if you try.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   void ChangePlaylistOrder(const QList<int>& ids);
+%Docstring
+ChangePlaylistOrder(new_order)
+Rearranges the order of the tabs in the tab bar.
+
+@field new_order: A list of playlist IDs in the new desired order.
+@type new_order: list of ints
+%End
 
   void SetCurrentPlaylist(int id);
+%Docstring
+SetCurrentPlaylist(id)
+Changes the current playlist (the one visible in the window) to the one with
+the given ID.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   void SetActivePlaylist(int id);
+%Docstring
+SetActivePlaylist(id)
+Changes the active playlist to the one with the given ID.
+
+@warning: You MUST ensure that a playlist with this identifier exists before
+  calling this method.  If you request an ID that doesn't exist the program
+  will crash.
+%End
+
   void SetActiveToCurrent();
+%Docstring
+SetActiveToCurrent()
+Convenience function that sets the active playlist to be the same as the
+current playlist.
 
-  void SelectionChanged(const QItemSelection& selection);
+This is equivalent to calling C{SetActivePlaylist(current_id())}.
+%End
 
-  // Convenience slots that defer to either current() or active()
   void ClearCurrent();
+%Docstring
+ClearCurrent()
+Convenience function to clear the current playlist.
+
+Equivalent to calling C{current().Clear()}.
+%End
+
   void ShuffleCurrent();
+%Docstring
+ShuffleCurrent()
+Convenience function to shuffle the current playlist.
+
+Equivalent to calling C{current().Shuffle()}.
+%End
+
   void SetActivePlaying();
+%Docstring
+SetActivePlaying()
+Convenience function to mark the current song in the active playlist as
+Playing.
+
+Equivalent to calling C{active().Playing()}.
+%End
+
   void SetActivePaused();
+%Docstring
+SetActivePaused()
+Convenience function to mark the current song in the active playlist as
+Paused.
+
+Equivalent to calling C{active().Paused()}.
+%End
+
   void SetActiveStopped();
+%Docstring
+SetActiveStopped()
+Convenience function to mark the current song in the active playlist as
+Stopped.
+
+Equivalent to calling C{active().Stopped()}.
+%End
+
   void SetActiveStreamMetadata(const QUrl& url, const Song& song);
-  // Rate current song using 0.0 - 1.0 scale.
+%Docstring
+SetActiveStreamMetadata(url, song)
+Convenience function to set the metadata of the currently playing song in
+the active playlist.
+
+Equivalent to calling C{active().SetStreamMetadata(url, song)}.
+
+@type url: PyQt4.QtCore.QUrl
+@type song: L{Song}
+%End
+
   void RateCurrentSong(double rating);
+%Docstring
+RateCurrentSong(rating)
+Convenience function to set the rating of the currently playing song in the
+active playlist.
+
+Equivalent to calling C{active().RateSong(active().current_index(), rating)}.
+
+@param rating: from 0.0 to 1.0
+@type rating: float
+%End
 
   // void PlaySmartPlaylist(smart_playlists::GeneratorPtr generator, bool as_new, bool clear);