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

http://github.com/tomahawk-player/tomahawk · C Header · 141 lines · 47 code · 23 blank · 71 comment · 0 complexity · 232e4dadc9f445af09eebde39d6860f5 MD5 · raw file

  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. #ifndef GENERATOR_INTERFACE_H
  20. #define GENERATOR_INTERFACE_H
  21. #include <QtCore/QObject>
  22. #include <QtCore/QSharedPointer>
  23. #include <QStringList>
  24. #include "Typedefs.h"
  25. #include "Query.h"
  26. #include "playlist/dynamic/DynamicControl.h"
  27. #include "DllMacro.h"
  28. namespace Tomahawk
  29. {
  30. /**
  31. * The abstract interface for Dynamic Playlist Generators. Generators have the following features:
  32. * - They create new DynamicControls that are appropriate for the generator
  33. * - They expose a list of controls that this generator currently is operating on
  34. * - They have a mode of OnDemand or Static
  35. *
  36. * And they generate tracks in two ways:
  37. * - Statically (ask for X tracks, get X tracks)
  38. * - On Demand (as for next track, ask for next track again, etc)
  39. */
  40. class DLLEXPORT GeneratorInterface : public QObject
  41. {
  42. Q_OBJECT
  43. Q_PROPERTY( QString type READ type )
  44. /// oh qjson.
  45. Q_PROPERTY( int mode READ mode WRITE setMode )
  46. public:
  47. // can't inline constructors/destructors for forward declared shared pointer types
  48. explicit GeneratorInterface( QObject* parent = 0 );
  49. virtual ~GeneratorInterface();
  50. // Can't make it pure otherwise we can't shove it in QVariants :-/
  51. // empty QString means use default
  52. /// The generator will keep track of all the controls it creates. No need to tell it about controls
  53. /// you ask it to create
  54. virtual dyncontrol_ptr createControl( const QString& type = QString() );
  55. /// A logo to display for this generator, if it has one
  56. virtual QPixmap logo();
  57. /**
  58. * Generate tracks from the controls in this playlist. If this generator is in static
  59. * mode, then it will return the desired number of tracks. If the generator is in OnDemand
  60. * mode, this will do nothing.
  61. *
  62. * Connect to the generated() signal for the results.
  63. *
  64. */
  65. virtual void generate( int number = -1 ) { Q_UNUSED( number ); }
  66. /**
  67. * Starts an on demand session for this generator. Listen to the nextTrack() signal to get
  68. * the first generated track
  69. */
  70. virtual void startOnDemand() {}
  71. /**
  72. * Get the next on demand track.
  73. * \param rating Rating from 1-5, -1 for none
  74. */
  75. virtual void fetchNext( int rating = -1 ) { Q_UNUSED( rating ) }
  76. /**
  77. * Return a sentence that describes this generator's controls. TODO english only ATM
  78. */
  79. virtual QString sentenceSummary() { return QString(); }
  80. /**
  81. * If an OnDemand playlist can be steered, this returns true.
  82. * If so, the generator should also provide a steering widget
  83. * in steeringWidget()
  84. */
  85. virtual bool onDemandSteerable() const { return false; }
  86. /**
  87. * Returns a widget used to steer the OnDemand dynamic playlist.
  88. * If this generator doesn't support this (and returns false for
  89. * \c onDemandSteerable) this will be null. The generator is responsible
  90. * for reacting to changes in the widget.
  91. *
  92. * Steering widgets may emit a \c steeringChanged() signal, which will cause the model to toss any
  93. * upcoming tracks and re-fetch them.
  94. *
  95. */
  96. virtual QWidget* steeringWidget() { return 0; }
  97. /// The type of this generator
  98. QString type() const { return m_type; }
  99. int mode() const { return (int)m_mode; }
  100. void setMode( int mode ) { m_mode = (GeneratorMode)mode; }
  101. // control functions
  102. QList< dyncontrol_ptr > controls();
  103. void addControl( const dyncontrol_ptr& control );
  104. void clearControls();
  105. void setControls( const QList< dyncontrol_ptr>& controls );
  106. void removeControl( const dyncontrol_ptr& control );
  107. signals:
  108. void error( const QString& title, const QString& body);
  109. void generated( const QList< Tomahawk::query_ptr>& queries );
  110. void nextTrackGenerated( const Tomahawk::query_ptr& track );
  111. protected:
  112. QString m_type;
  113. GeneratorMode m_mode;
  114. QList< dyncontrol_ptr > m_controls;
  115. };
  116. typedef QSharedPointer<GeneratorInterface> geninterface_ptr;
  117. };
  118. #endif