~ubuntu-branches/ubuntu/oneiric/kdeplasma-addons/oneiric

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
/*
 *   Copyright (C) 2007 Tobias Koenig <tokoe@kde.org>
 *
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU Library General Public License version 2 as
 *   published by the Free Software Foundation
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details
 *
 *   You should have received a copy of the GNU Library General Public
 *   License along with this program; if not, write to the
 *   Free Software Foundation, Inc.,
 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef COMICPROVIDER_H
#define COMICPROVIDER_H

#include <QtCore/QDate>
#include <QtCore/QObject>
#include <KPluginInfo>
#include <KPluginFactory>

#include "plasma_comic_export.h"

class QImage;
class KUrl;

#define COMICPROVIDER_EXPORT_PLUGIN( classname, componentName, catalogName ) \
    K_PLUGIN_FACTORY( classname ## Factory, registerPlugin< classname >(); ) \
    K_EXPORT_PLUGIN( classname ## Factory( componentName, catalogName ) )

/**
 * This class is an interface for comic providers.
 */
class PLASMA_COMIC_EXPORT ComicProvider : public QObject
{
    Q_OBJECT

    public:
        /**
         * Describes the type of how this comic provider
         * references the previous or next comic strip.
         */
        enum IdentifierType {
            DateIdentifier = 0,   ///< References by date
            NumberIdentifier,     ///< References by numerical identifier
            StringIdentifier      ///< References by arbitrary string
        };

        /**
         * Creates a new comic provider.
         *
         * @param parent The parent object.
         * @param args Arguments passed by the plugin loader.
         */
        ComicProvider( QObject *parent, const QVariantList &args );

        /**
         * Destroys the comic provider.
         */
        virtual ~ComicProvider();

        /**
         * Returns the type of identifier that is used by this
         * comic provider.
         */
        virtual IdentifierType identifierType() const = 0;

        /**
         * Returns the type of suffix that is used by this
         * comic provider.
         */
        virtual QString suffixType() const;

        /**
         * Returns the url of the website where the comic of that particular date resides.
         */
        virtual KUrl websiteUrl() const = 0;

        /**
         * Returns the url of the website where the comic has a shop.
         */
        virtual KUrl shopUrl() const;

        /**
         * Returns the requested image.
         *
         * Note: This method returns only a valid image after the
         *       finished() signal has been emitted.
         */
        virtual QImage image() const = 0;

        /**
         * Returns the identifier of the comic request.
         */
        virtual QString identifier() const = 0;

        /**
         * Returns the identifier of the next comic (default: date of next day).
         */
        virtual QString nextIdentifier() const;

        /**
         * Returns the identifier of the previous comic (default: date of previous day
         * as long).
         */
        virtual QString previousIdentifier() const;

        /**
         * Returns the identifier of the first strip.
         */
        virtual QString firstStripIdentifier() const;

        /**
         * Returns the author of the comic.
         */
        virtual QString comicAuthor() const;

        /**
         * Returns the title of the strip.
         */
        virtual QString stripTitle() const;

        /**
         * Returns additionalText of the comic.
         */
        virtual QString additionalText() const;

        /**
         * Returns the identifier for the comic
         */
        virtual QString pluginName() const;

        /**
         * Returns the name for the comic
         */
        virtual QString name() const;

        /**
         * Returns wether the comic is leftToRight or not
         */
        virtual bool isLeftToRight() const;

        /**
        * Returns wether the comic is topToBottom or not
        */
        virtual bool isTopToBottom() const;

        /**
         * Returns the plugin info for the comic
         */
        KPluginInfo description() const;

        /**
         * Set whether this request is for the current comic (only used internally).
         */
        void setIsCurrent( bool value );

        /**
         * Returns whether this request is for the current comic (only used internally).
         */
        bool isCurrent() const;

    Q_SIGNALS:
        /**
         * This signal is emitted whenever a request has been finished
         * successfully.
         *
         * @param provider The provider which emitted the signal.
         */
        void finished( ComicProvider *provider );

        /**
         * This signal is emitted whenever an error has occurred.
         *
         * @param provider The provider which emitted the signal.
         */
        void error( ComicProvider *provider );

    protected:
        /**
         * Returns the date identifier that was requested by the applet.
         */
        QDate requestedDate() const;

        /**
         * Returns the numeric identifier that was requested by the applet.
         */
        int requestedNumber() const;

        /**
         * Returns the string identifier that was requested by the applet.
         */
        QString requestedString() const;

        /**
         * @internal
         *
         * Returns the comic name of the string identifier that was requested by the applet.
         */
        QString requestedComicName() const;

        /**
         * Returns the date of the first available comic strip.
         */
        QDate firstStripDate() const;

        /**
         * Sets the date of the first available comic strip.
         */
        void setFirstStripDate( const QDate &date );

        /**
         * Returns the number of the first available comic strip (default: 1 ).
         */
        int firstStripNumber() const;

        /**
         * Sets the number of the first available comic strip.
         */
        void setFirstStripNumber( int number );

        /**
         * Sets the name of the comic author.
         */
        void setComicAuthor( const QString &author );

        typedef QMap<QString, QString> MetaInfos;

        /**
         * This method should be used by all comic providers to request
         * websites or images from the web. It encapsulates the HTTP
         * handling and calls pageRetrieved() or pageError() on success or error.
         *
         * @param url The url to access.
         * @param id A unique id that identifies this request.
         * @param infos A list of meta information passed to http.
         */
        void requestPage( const KUrl &url, int id, const MetaInfos &infos = MetaInfos() );

        /**
         * This method is called whenever a request done by requestPage() was successful.
         *
         * @param id The unique identifier of that request.
         * @param data The data of the fetched object.
         */
        virtual void pageRetrieved( int id, const QByteArray &data );

        /**
         * This method is called whenever a request done by requestPage() has failed.
         *
         * @param id The unique identifier of that request.
         * @param message The error message.
         */
        virtual void pageError( int id, const QString &message );

    private:
        class Private;
        Private* const d;

        Q_PRIVATE_SLOT( d, void jobDone( KJob* ) )
};

#endif