1
/***************************************************************************
2
begin : Sun May 15 2005
3
copyright : (C) 2005, 2008 by Michael Pyne
4
email : michael.pyne@kdemail.net
5
***************************************************************************/
7
/***************************************************************************
9
* This program is free software; you can redistribute it and/or modify *
10
* it under the terms of the GNU General Public License as published by *
11
* the Free Software Foundation; either version 2 of the License, or *
12
* (at your option) any later version. *
14
***************************************************************************/
16
#ifndef JUK_COVERMANAGER_H
17
#define JUK_COVERMANAGER_H
19
#include <ksharedptr.h>
25
class CoverManagerPrivate;
31
template<class Key, class Value>
40
* This class saves the covers when its saveCovers() slot is called to avoid
41
* making CoverManager a QObject and avoid moving the actual implementation
42
* class (CoverManagerPrivate) to this .h file. Used with a QTimer to save
43
* the covers after changes are made.
45
class CoverSaveHelper : public QObject
50
CoverSaveHelper(QObject *parent);
61
* This class holds the data on a cover. This includes the path to the cover
62
* representation on-disk, and the artist and album associated with the cover.
63
* Don't assume that the artist or album information is filled out, it is
64
* there to allow the CoverManager to try to automatically assign covers to
67
* @author Michael Pyne <michael.pyne@kdemail.net>
70
class CoverData : public KShared
73
QPixmap pixmap() const;
74
QPixmap thumbnail() const;
80
unsigned refCount; // Refers to number of tracks using this.
83
typedef KSharedPtr<CoverData> CoverDataPtr;
84
typedef unsigned long coverKey; ///< Type of the id for a cover.
86
typedef QMap<coverKey, CoverDataPtr> CoverDataMap;
88
// I can't believe this actually works...
89
typedef CoverDataMap::const_iterator CoverDataMapIterator;
91
typedef QList<coverKey> CoverList;
94
* This class is used to drag covers in JuK. It adds a special mimetype that
95
* contains the cover ID used for this cover, and also supports an image/png
96
* mimetype for dragging to other applications.
98
* As of this writing the mimetype is application/x-juk-coverid
100
* @author Michael Pyne <michael.pyne@kdemail.net>
102
class CoverDrag : public QMimeData
107
CoverDrag(coverKey id);
109
static const char* mimetype();
111
static bool isCover(const QMimeData *data);
113
// CoverDrag stores QByteArray data for the cover id, this can convert it
115
static coverKey idFromData(const QMimeData *data);
119
* This class holds all of the cover art, and manages looking it up by artist
120
* and/or album. This class is similar to a singleton class, but instead all
121
* of the methods are static. This way you can invoke methods like this:
123
* CoverManager::method()
127
* CoverManager::instance()->method()
130
* @author Michael Pyne <michael.pyne@kdemail.net>
135
/// The set of different sizes you can request a pixmap as.
136
typedef enum { Thumbnail, FullSize } Size;
139
* Tries to match @p artist and @p album to a cover in the database.
141
* @param artist The artist to look for matching covers on.
142
* @param album The album to look for matching covers on.
143
* @return NoMatch if no match could be found, otherwise the id of the
144
* cover art that matches the given metadata.
146
static coverKey idFromMetadata(const QString &artist, const QString &album);
149
* Returns the cover art for @p id.
151
* @param id The id of the cover.
152
* @param size The size to return it as. Note that FullSize doesn't
153
* necessarily mean the pixmap is large, so you may need to
155
* @return QPixmap::null if there is no cover art for @p id, otherwise the
158
static QPixmap coverFromId(coverKey id, Size size = Thumbnail);
161
* Returns the cover art for @p ptr. This function is intended for use
164
* @param ptr The CoverData to get the cover of. Note that it is a
165
* CoverData, not CoverDataPtr.
166
* @param size The size to return it as.
169
static QPixmap coverFromData(const CoverData &coverData, Size size = Thumbnail);
172
* Returns the full suite of information known about the cover given by
175
* @param id the id of the cover to retrieve info on.
176
* @return 0 if there is no info on @p id, otherwise its information.
178
static CoverDataPtr coverInfo(coverKey id);
181
* Adds @p large to the cover database, associating with it @p artist and
184
* @param large The full size cover (the thumbnail is automatically
186
* @param artist The artist of the new cover.
187
* @param album The album of the new cover.
189
static coverKey addCover(const QPixmap &large, const QString &artist = "", const QString &album = "");
192
* Adds the file pointed to by the local path @p path to the database,
193
* associating it with @p artist and @p album.
195
* @param path The absolute path to the fullsize cover art.
196
* @param artist The artist of the new cover.
197
* @param album The album of the new cover.
199
static coverKey addCover(const KUrl &path, const QString &artist = "", const QString &album = "");
202
* Function to determine if @p id matches any covers in the database.
204
* @param id The id of the cover to search for.
205
* @return true if the database has a cover identified by @p id, false
208
static bool hasCover(coverKey id);
211
* Removes the cover identified by @p id.
213
* @param id the id of the cover to remove.
214
* @return true if the removal was successful, false if unsuccessful or if
215
* the cover didn't exist.
217
static bool removeCover(coverKey id);
220
* Replaces the cover art for the cover identified by @p id with @p large.
221
* Any other metadata such as artist and album is unchanged.
223
* @param id The id of the cover to replace.
224
* @param large The full size cover art for the new cover.
226
static bool replaceCover(coverKey id, const QPixmap &large);
229
* Saves the current CoverManager information to disk. Changes are not
230
* automatically written to disk due to speed issues, so you can
231
* periodically call this function while running to reduce the chance of
232
* lost data in the event of a crash.
234
static void saveCovers();
237
* This is a hack, as we should be shut down automatically by
238
* KStaticDeleter, but JuK is crashing for me on shutdown before
239
* KStaticDeleter gets a chance to run, which is cramping my testing.
241
static void shutdown();
244
* @return Iterator pointing to the first element in the cover database.
246
static CoverDataMapIterator begin();
249
* @return Iterator pointing after the last element in the cover database.
251
static CoverDataMapIterator end();
254
* @return A list of all of the id's listed in the database.
256
static CoverList keys();
259
* Associates @p path with the cover identified by @id. No comparison of
260
* metadata is performed to enforce this matching.
262
* @param path The absolute file path to the track.
263
* @param id The identifier of the cover to use with @p path.
265
static void setIdForTrack(const QString &path, coverKey id);
268
* Returns the identifier of the cover for the track at @p path.
270
* @param path The absolute file path to the track.
271
* @return NoMatch if @p path doesn't have a cover, otherwise the id of
274
static coverKey idForTrack(const QString &path);
277
* This identifier is used to indicate that no cover was found in the
280
static const coverKey NoMatch;
283
friend class CoverProxy; // Our QObject-wielding friend.
285
/// Called by CoverProxy to notify of a completed job.
286
static void jobComplete(KJob *job, bool completedSatisfactory);
287
static CoverManagerPrivate *data();
288
static QPixmap createThumbnail(const QPixmap &base);
291
#endif /* JUK_COVERMANAGER_H */
293
// vim: set et sw=4 tw=0 sta: