Python docs for PlaylistItem
This commit is contained in:
parent
e9a13bc864
commit
dc509db512
|
@ -1,4 +1,4 @@
|
||||||
class PlayerInterface : QObject {
|
class PlayerInterface : QObject /PyName=Player/ {
|
||||||
|
|
||||||
%TypeHeaderCode
|
%TypeHeaderCode
|
||||||
#include "core/player.h"
|
#include "core/player.h"
|
||||||
|
|
|
@ -13,10 +13,49 @@ class PlaylistItem {
|
||||||
#include "scripting/python/sharedpointermanager.h"
|
#include "scripting/python/sharedpointermanager.h"
|
||||||
%End
|
%End
|
||||||
|
|
||||||
public:
|
%Docstring
|
||||||
static PlaylistItem* NewFromType(const QString& type);
|
Represents a single row in a playlist.
|
||||||
static PlaylistItem* NewFromSongsTable(const QString& table, const Song& song);
|
|
||||||
|
|
||||||
|
Playlists in Clementine are lists of PlaylistItems. At a minimum each
|
||||||
|
PlaylistItem contains some metadata and a URL, but items may also have special
|
||||||
|
loading behaviour associated with them if playing the item is more complicated
|
||||||
|
than just loading a URL (for example, Last.fm stations have to request a
|
||||||
|
special playlist using the Last.fm API).
|
||||||
|
|
||||||
|
PlaylistItem is an abstract class and instances of it cannot be created
|
||||||
|
directly by Python code. If you want to add items to a playlist you should use
|
||||||
|
the C{Insert...} methods in L{Playlist}, such as
|
||||||
|
L{Playlist.InsertSongsOrLibraryItems()}.
|
||||||
|
|
||||||
|
You can get individual PlaylistItems from a L{Playlist} using
|
||||||
|
L{Playlist.item_at()}. Get the PlaylistItem that is currently playing (in any
|
||||||
|
playlist) using L{Player.GetCurrentItem()}. These functions are marked as
|
||||||
|
returning L{PlaylistItemPtr}s, because in C++ the playlist items are held
|
||||||
|
inside and managed by smart pointers. This doesn't affect Python at all
|
||||||
|
however - you can use a PlaylistItemPtr in just the same way as you would a
|
||||||
|
PlaylistItem.
|
||||||
|
|
||||||
|
>>> item = clementine.player.GetCurrentItem()
|
||||||
|
... print item.Metadata().title()
|
||||||
|
|
||||||
|
The L{options()} field of a PlaylistItem is an ORed combination of flags that
|
||||||
|
describe the item's behaviour when it is played. Valid values are:
|
||||||
|
|
||||||
|
- C{Default} - no special behaviour, the L{Url()} is used directly when
|
||||||
|
playing the song.
|
||||||
|
- C{SpecialPlayBehaviour} - The URL returned by Url() isn't the actual URL of
|
||||||
|
the music - the item needs to do something special before it can get an
|
||||||
|
actual URL. Causes StartLoading() to get called when the user wants to
|
||||||
|
play.
|
||||||
|
- C{ContainsMultipleTracks} - this item might be able to provide another
|
||||||
|
track after one finishes, for example in a radio stream. Causes LoadNext()
|
||||||
|
to get called when the next URL is required.
|
||||||
|
- C{PauseDisabled} - disables the "pause" action.
|
||||||
|
- C{LastFMControls} - enables the last.fm "ban" action.
|
||||||
|
|
||||||
|
%End
|
||||||
|
|
||||||
|
public:
|
||||||
enum Option {
|
enum Option {
|
||||||
Default,
|
Default,
|
||||||
SpecialPlayBehaviour,
|
SpecialPlayBehaviour,
|
||||||
|
@ -27,6 +66,22 @@ public:
|
||||||
typedef QFlags<PlaylistItem::Option> Options;
|
typedef QFlags<PlaylistItem::Option> Options;
|
||||||
|
|
||||||
struct SpecialLoadResult {
|
struct SpecialLoadResult {
|
||||||
|
%Docstring
|
||||||
|
Returned by StartLoading() and LoadNext(), indicates what the player should do
|
||||||
|
when it wants to load a playlist item that is marked SpecialPlayBehaviour or
|
||||||
|
ContainsMultipleTracks.
|
||||||
|
|
||||||
|
Valid values for the type_ field are:
|
||||||
|
|
||||||
|
- C{NoMoreTracks} - there wasn't a track available, and the player should
|
||||||
|
move on to the next playlist item.
|
||||||
|
- C{WillLoadAsynchronously} - there might be another track available,
|
||||||
|
something will call the player's HandleSpecialLoad() slot later with the
|
||||||
|
same original_url.
|
||||||
|
- C{TrackAvailable} - There was a track available. Its url is in media_url.
|
||||||
|
|
||||||
|
%End
|
||||||
|
|
||||||
enum Type {
|
enum Type {
|
||||||
NoMoreTracks,
|
NoMoreTracks,
|
||||||
WillLoadAsynchronously,
|
WillLoadAsynchronously,
|
||||||
|
@ -44,22 +99,87 @@ public:
|
||||||
};
|
};
|
||||||
|
|
||||||
QString type() const;
|
QString type() const;
|
||||||
|
%Docstring
|
||||||
|
type() -> str
|
||||||
|
Returns a string describing the subclass of PlaylistItem that this item really
|
||||||
|
is. This string is stored in the database so the correct subclass can be
|
||||||
|
recreated again when the playlist is loaded. Values include:
|
||||||
|
|
||||||
|
- C{Library}
|
||||||
|
- C{File}
|
||||||
|
- C{Stream}
|
||||||
|
- C{Jamendo}
|
||||||
|
- C{Magnatune}
|
||||||
|
- C{Radio}
|
||||||
|
%End
|
||||||
|
|
||||||
Options options() const;
|
Options options() const;
|
||||||
|
%Docstring
|
||||||
|
options() -> L{Options}
|
||||||
|
Returns the options set on this item.
|
||||||
|
|
||||||
|
@return: An ORed combination of L{Option}s.
|
||||||
|
%End
|
||||||
|
|
||||||
void Reload();
|
void Reload();
|
||||||
|
%Docstring
|
||||||
|
Reload()
|
||||||
|
If this item is backed by a file, re-reads the metadata from the file and
|
||||||
|
updates the row in the playlist.
|
||||||
|
|
||||||
|
@warning: This method is B{blocking} and runs on the GUI thread. It is better
|
||||||
|
to call L{BackgroundReload()} which runs in a separate thread.
|
||||||
|
%End
|
||||||
|
|
||||||
void BackgroundReload();
|
void BackgroundReload();
|
||||||
|
%Docstring
|
||||||
|
BackgroundReload()
|
||||||
|
Like L{Reload()}, but runs in a background thread.
|
||||||
|
%End
|
||||||
|
|
||||||
Song Metadata() const;
|
Song Metadata() const;
|
||||||
|
%Docstring
|
||||||
|
Metadata() -> L{Song}
|
||||||
|
Returns this item's metadata.
|
||||||
|
%End
|
||||||
|
|
||||||
QUrl Url() const;
|
QUrl Url() const;
|
||||||
|
%Docstring
|
||||||
|
Url() -> L{PyQt4.QtCore.QUrl}
|
||||||
|
Returns the URL that contains this item's media. This is usually derived from
|
||||||
|
C{Metadata().filename()}.
|
||||||
|
%End
|
||||||
|
|
||||||
void SetTemporaryMetadata(const Song& metadata);
|
void SetTemporaryMetadata(const Song& metadata);
|
||||||
void ClearTemporaryMetadata();
|
%Docstring
|
||||||
bool HasTemporaryMetadata() const;
|
SetTemporaryMetadata(metadata)
|
||||||
|
Sets some metadata on the item that will override that returned from
|
||||||
|
L{Metadata()} while the song is playing, and until L{ClearTemporaryMetadata()}
|
||||||
|
is called. This is useful for radio streams where the actual metadata is not
|
||||||
|
known until the stream is loaded.
|
||||||
|
|
||||||
void SetDynamicHistory(bool history);
|
@note: Some types of PlaylistItem may not allow you to override their metadata.
|
||||||
bool IsDynamicHistory() const;
|
@type metadata: L{Song}
|
||||||
|
%End
|
||||||
|
|
||||||
|
void ClearTemporaryMetadata();
|
||||||
|
%Docstring
|
||||||
|
ClearTemporaryMetadata()
|
||||||
|
Clears any metadata set by L{SetTemporaryMetadata()}.
|
||||||
|
%End
|
||||||
|
|
||||||
|
bool HasTemporaryMetadata() const;
|
||||||
|
%Docstring
|
||||||
|
HasTemporaryMetadata() -> bool
|
||||||
|
Returns true if L{SetTemporaryMetadata()} has been called.
|
||||||
|
%End
|
||||||
|
|
||||||
bool IsLocalLibraryItem() const;
|
bool IsLocalLibraryItem() const;
|
||||||
|
%Docstring
|
||||||
|
IsLocalLibraryItem() -> bool
|
||||||
|
Convenience function to check whether this item is from the local library (the
|
||||||
|
list of songs appearing in the Library tab).
|
||||||
|
%End
|
||||||
|
|
||||||
~PlaylistItem();
|
~PlaylistItem();
|
||||||
%MethodCode
|
%MethodCode
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
class PlaylistManagerInterface : QObject {
|
class PlaylistManagerInterface : QObject /PyName=PlaylistManager/ {
|
||||||
|
|
||||||
%TypeHeaderCode
|
%TypeHeaderCode
|
||||||
#include "playlist/playlistmanager.h"
|
#include "playlist/playlistmanager.h"
|
||||||
|
|
Loading…
Reference in New Issue