1 /****************************************************************************************
2  * Copyright (c) 2010 Ralf Engels <ralf-engels@gmx.de>                                  *
3  *                                                                                      *
4  * This program is free software; you can redistribute it and/or modify it under        *
5  * the terms of the GNU General Public License as published by the Free Software        *
6  * Foundation; either version 2 of the License, or (at your option) version 3 or        *
7  * any later version accepted by the membership of KDE e.V. (or its successor approved  *
8  * by the membership of KDE e.V.), which shall act as a proxy defined in Section 14 of  *
9  * version 3 of the license.                                                            *
10  *                                                                                      *
11  * This program is distributed in the hope that it will be useful, but WITHOUT ANY      *
12  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A      *
13  * PARTICULAR PURPOSE. See the GNU General Public License for more details.             *
14  *                                                                                      *
15  * You should have received a copy of the GNU General Public License along with         *
16  * this program.  If not, see <http://www.gnu.org/licenses/>.                           *
17  ****************************************************************************************/
18 
19 #ifndef AMAROK_BIAS_FACTORY_H
20 #define AMAROK_BIAS_FACTORY_H
21 
22 #include "amarok_export.h"
23 #include "dynamic/Bias.h"
24 
25 #include <QObject>
26 #include <KLocalizedString>
27 
28 class QXmlStreamReader;
29 class QXmlStreamWriter;
30 
31 namespace Dynamic
32 {
33     /** A bias that will be used when a "real" bias could not be found.
34         This bias will listen to the BiasFactory and present a "stand in" bias
35         until a new factory with it's name becomes available.
36         This will allow services with a bias to be switched off without their
37         bias getting removed or otherwise corrupted.
38     */
39     class ReplacementBias : public RandomBias
40     {
41         Q_OBJECT
42 
43         public:
44             explicit ReplacementBias( const QString &n );
45             ReplacementBias( const QString &n, QXmlStreamReader *reader );
46 
47             void toXml( QXmlStreamWriter *writer ) const override;
48 
49             static QString sName();
50             QString name() const override;
51             QString toString() const override;
52 
53             QWidget* widget( QWidget* parent = nullptr ) override;
54 
55         protected Q_SLOTS:
56                 void factoryChanged();
57 
58         private:
59                 QString m_name;
60                 QByteArray m_html;
61 
62                 Q_DISABLE_COPY(ReplacementBias)
63     };
64 
65     /**
66      * The factory which creates bias entries on demand. As the user can create any number
67      * of biases from from the bias addition widget, new custom biass types need to be able to be
68      * generated on command and at runtime.
69      **/
70     class AMAROK_EXPORT AbstractBiasFactory
71     {
72         public:
AbstractBiasFactory()73             AbstractBiasFactory() {}
~AbstractBiasFactory()74             virtual ~AbstractBiasFactory() {}
75 
76             /** Returns the translated name of the type of bias.
77                 This one is used in the combo boxes when selecting the bias.
78                 It could be eg. "Last.fm Similar Artists"
79              */
80             virtual QString i18nName() const = 0;
81 
82             /** Returns an internal non-translatable name for this custom bias type.
83                 This name must be unique over all biases and will also be used
84                 when reading and writing a bias to xml.
85              */
86             virtual QString name() const = 0;
87 
88             /** Returns the translated description of the bias */
89             virtual QString i18nDescription() const = 0;
90 
91             /** Create the custom bias. The caller takes owner of the pointer
92              */
93             virtual BiasPtr createBias() = 0;
94 
95             /** Creates a new custom bias from xml data
96              */
97             virtual BiasPtr createFromXml( QXmlStreamReader *reader );
98     };
99 
100     class AMAROK_EXPORT BiasFactory : public QObject
101     {
102         Q_OBJECT
103 
104     public:
105         static BiasFactory* instance();
106 
107         /** Add a new CustomBiasEntry to the registry.
108              It will show up for users when then select the type of bias they want.
109          */
110         static void registerNewBiasFactory( AbstractBiasFactory* factory );
111 
112         /** Remove CustomBiasEntry from the list of bias types that the user can select.
113          */
114         static void removeBiasFactory( AbstractBiasFactory* factory );
115 
116         /** Helper function to get a bias from an xml tag */
117         static BiasPtr fromXml( QXmlStreamReader *reader );
118 
119         /** Helper function to get a bias from an name */
120         static BiasPtr fromName( const QString &name );
121 
122         /**
123          * Returns all the current registered factories for this CustomBias
124          */
125         static QList<AbstractBiasFactory*> factories();
126 
127     Q_SIGNALS:
128         /** Emitted when the list of bias factories was changed. */
129         void changed();
130 
131     private:
132         BiasFactory( QObject *parent = nullptr );
133         ~BiasFactory() override;
134 
135         void emitChanged();
136 
137         static BiasFactory* s_instance;
138         static QList<Dynamic::AbstractBiasFactory*> s_biasFactories;
139     };
140 }
141 
142 #endif
143