/src/libtomahawk/playlist/dynamic/GeneratorInterface.h

  1/* === This file is part of Tomahawk Player - <http://tomahawk-player.org> ===
  2 *
  3 *   Copyright 2010-2011, Christian Muehlhaeuser <muesli@tomahawk-player.org>
  4 *   Copyright 2010-2011, Jeff Mitchell <jeff@tomahawk-player.org>
  5 *
  6 *   Tomahawk is free software: you can redistribute it and/or modify
  7 *   it under the terms of the GNU General Public License as published by
  8 *   the Free Software Foundation, either version 3 of the License, or
  9 *   (at your option) any later version.
 10 *
 11 *   Tomahawk is distributed in the hope that it will be useful,
 12 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 13 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 14 *   GNU General Public License for more details.
 15 *
 16 *   You should have received a copy of the GNU General Public License
 17 *   along with Tomahawk. If not, see <http://www.gnu.org/licenses/>.
 18 */
 19
 20#ifndef GENERATOR_INTERFACE_H
 21#define GENERATOR_INTERFACE_H
 22
 23#include <QtCore/QObject>
 24#include <QtCore/QSharedPointer>
 25#include <QStringList>
 26
 27#include "Typedefs.h"
 28#include "Query.h"
 29#include "playlist/dynamic/DynamicControl.h"
 30
 31#include "DllMacro.h"
 32
 33namespace Tomahawk
 34{
 35
 36/**
 37 * The abstract interface for Dynamic Playlist Generators. Generators have the following features:
 38 *      - They create new DynamicControls that are appropriate for the generator
 39 *      - They expose a list of controls that this generator currently is operating on
 40 *      - They have a mode of OnDemand or Static
 41 *
 42 *  And they generate tracks in two ways:
 43 *      - Statically (ask for X tracks, get X tracks)
 44 *      - On Demand (as for next track, ask for next track again, etc)
 45 */
 46class DLLEXPORT GeneratorInterface : public QObject
 47{
 48    Q_OBJECT
 49    Q_PROPERTY( QString type READ type )
 50    /// oh qjson.
 51    Q_PROPERTY( int mode READ mode WRITE setMode )
 52
 53public:
 54    // can't inline constructors/destructors for forward declared shared pointer types
 55    explicit GeneratorInterface( QObject* parent = 0 );
 56    virtual ~GeneratorInterface();
 57
 58    // Can't make it pure otherwise we can't shove it in QVariants :-/
 59    // empty QString means use default
 60    /// The generator will keep track of all the controls it creates. No need to tell it about controls
 61    ///  you ask it to create
 62    virtual dyncontrol_ptr createControl( const QString& type = QString() );
 63
 64    /// A logo to display for this generator, if it has one
 65    virtual QPixmap logo();
 66
 67    /**
 68     * Generate tracks from the controls in this playlist. If this generator is in static
 69     *  mode, then it will return the desired number of tracks. If the generator is in OnDemand
 70     *  mode, this will do nothing.
 71     *
 72     * Connect to the generated() signal for the results.
 73     *
 74     */
 75    virtual void generate( int number = -1 ) { Q_UNUSED( number ); }
 76
 77    /**
 78     * Starts an on demand session for this generator. Listen to the nextTrack() signal to get
 79     *  the first generated track
 80     */
 81    virtual void startOnDemand() {}
 82
 83    /**
 84     * Get the next on demand track.
 85     * \param rating Rating from 1-5, -1 for none
 86     */
 87    virtual void fetchNext( int rating = -1 ) { Q_UNUSED( rating ) }
 88
 89    /**
 90     * Return a sentence that describes this generator's controls. TODO english only ATM
 91     */
 92    virtual QString sentenceSummary() { return QString(); }
 93
 94    /**
 95     * If an OnDemand playlist can be steered, this returns true.
 96     * If so, the generator should also provide a steering widget
 97     *  in steeringWidget()
 98     */
 99    virtual bool onDemandSteerable() const { return false; }
100
101    /**
102     * Returns a widget used to steer the OnDemand dynamic playlist.
103     *  If this generator doesn't support this (and returns false for
104     * \c onDemandSteerable) this will be null. The generator is responsible
105     *  for reacting to changes in the widget.
106     *
107     * Steering widgets may emit a \c steeringChanged() signal, which will cause the model to toss any
108     *  upcoming tracks and re-fetch them.
109     *
110     */
111    virtual QWidget* steeringWidget() { return 0; }
112
113    /// The type of this generator
114    QString type() const { return m_type; }
115
116    int mode() const { return (int)m_mode; }
117    void setMode( int mode ) { m_mode = (GeneratorMode)mode; }
118
119    // control functions
120    QList< dyncontrol_ptr > controls();
121    void addControl( const dyncontrol_ptr& control );
122    void clearControls();
123    void setControls( const QList< dyncontrol_ptr>& controls );
124    void removeControl( const dyncontrol_ptr& control );
125
126signals:
127    void error( const QString& title, const QString& body);
128    void generated( const QList< Tomahawk::query_ptr>& queries );
129    void nextTrackGenerated( const Tomahawk::query_ptr& track );
130
131protected:
132    QString m_type;
133    GeneratorMode m_mode;
134    QList< dyncontrol_ptr > m_controls;
135};
136
137typedef QSharedPointer<GeneratorInterface> geninterface_ptr;
138
139};
140
141#endif