Requests and delivers thumbnails for given URI-based resources. More...
#include <thumbnailer.h>
Signals | |
void | started () |
New request has started to be processed. | |
void | finished (int left) |
Some request is done. | |
void | thumbnail (const QUrl &uri, const QUrl &thumbnailUri, const QPixmap &pixmap, const QString &flavor) |
New thumbnail is ready for You. | |
void | thumbnail (const MediaArt::Info &media, const QUrl &thumbnailUri, const QPixmap &pixmap, const QString &flavor) |
New thumbnail for media art is ready for You. | |
void | defaultThumbnail (const QUrl &uri, const QUrl &thumbnailUri, const QPixmap &pixmap, const QString &flavor) |
Thumbnail need to be (re)created. | |
void | defaultThumbnail (const MediaArt::Info &media, const QUrl &thumbnailUri, const QPixmap &pixmap, const QString &flavor) |
Media Art's thumbnail is not available yet. | |
void | dequeued (const QUrl &uri) |
Some request was canceled and removed from queue. | |
void | dequeued (const MediaArt::Info &media) |
Some request was canceled and removed from queue. | |
void | error (const QString &error, const QUrl &uri, const QUrl &defaultUri=QUrl(), const QPixmap &defaultPixmap=QPixmap()) |
Some error occured during the request. | |
void | error (const QString &error, const MediaArt::Info &media, const QUrl &defaultUri=QUrl(), const QPixmap &defaultPixmap=QPixmap()) |
Some error occured during the media art's thumbnail request. | |
Public Member Functions | |
void | cancel (bool sendRemainingSignals=true, bool unqueueFromTumbler=true) |
Cancel all currently running request. | |
bool | request (QList< QUrl > &uris, QStringList &mimeTypes, bool sendPixmap=false, QString flavor=QString(), QString scheduler=QString(), bool autoCancel=false, bool sendRemainingSignals=true) |
Make a request for thumbnails. | |
bool | request (QList< MediaArt::Info > &media, bool sendPixmap=false, QString flavor=QString(), QString scheduler=QString(), bool autoCancel=false, bool sendRemainingSignals=true) |
Requests for Media Art's thumbnails. | |
Configuration state functions. | |
Thumbnailer is not copyable and assigneable, so it should be always used by pointers (in lists, hashes etc.). You can also create Thumbnailer and use it by value but remember to not assign it to any other Thumbnailer, otherwise some request could be lost. It is strongly adivsed to create one Thumbnailer object per application/thread and make all request through that one object. Just thinks about it as a proxy for D-Bus API. | |
~Thumbnailer () | |
Destruct Thumbnailer object and clean memmory. | |
Thumbnailer (QUrl defaultUri=QUrl(), QPixmap defaultPixmap=QPixmap()) | |
Construct new Thumbnailer object with default values. | |
void | setDefaultURI (QUrl uri) |
Changes the default URI for thumbnails. | |
void | setDefaultPixmap (QPixmap pixmap) |
Changes the default Pixmap for thumbnails. | |
QUrl | defaultURI () const |
Gets current default URI for thumbnails. | |
QPixmap | defaultPixmap () const |
Gets current default Pixmap for thumbnails. | |
Static Public Member Functions | |
static QUrl | getThumbnailPath (const QUrl &uri, const QString &flavor) |
Returns thumbnail's URI for particular resource. | |
Cache related functions. | |
static void | move (const QList< QUrl > &from, const QList< QUrl > &to) |
Update thumbnails cache after some resources were moved. | |
static void | copy (const QList< QUrl > &from, const QList< QUrl > &to) |
Update thumbnails cache after some resources were copied. | |
static void | remove (const QList< QUrl > &fileUris) |
Update thumbnails cache after some resources were deleted. | |
static void | cleanup (const QString &prefix, unsigned before) |
Request for cleaning up the cache of invalid or old thumbnails. | |
Friends | |
class | Thumbnails::ThumbnailerPrivate |
Supported schedulers, schemes, MIMEs types and flavors. | |
Developer can check results from those functions to get informations what are all the possibilities of the Thumbnailer. It is possible to get informations about supported schedulers and flavors. Also informations about what kind of MIME types are supported for particular URI scheme could be retrieved by the developer. | |
static const QString | noopScheduler |
Scheduler 'noop' which returns only already existing thumbnails. | |
static const QString | defaultFlavor |
Default flavor which could be used with getThumbnailPath function. | |
static QMultiHash< QString, QString > | getSupported () |
Returns supported MIME types for particular URI schemes. | |
static QStringList | getSchedulers () |
Returns list of supported schedulers. | |
static QStringList | getFlavors () |
Returns list of supported flavors. | |
static QSize | getFlavorSize (const QString &flavor) |
Retrieves a size of particular kind of thumbnails. |
Requests and delivers thumbnails for given URI-based resources.
Uses the D-Bus service org.freedesktop.thumbnails.Thumbnailer1. For D-Bus API see: http://live.gnome.org/ThumbnailerSpec . Thumbnailer tries to be as much similiar to original D-Bus API as possible but in order to make it more efficency some additional functionalities were added. Basic use of that class looks like this (pseudo-code):
//create object with default values Thumbnailer* thumb = new Thumbnailer (QUrl("file:///default/image/path"));
Given default value will be returned to You if You will use defaultThumbnail signal. If You do not want to utilize this signal (or You do not want to use parameters of that signal) you can call constructor without any parameters:
Thumbnailer* thumb = new Thumbnailer ();
Next You need to create list with uris of documents You want to get thumbnailed and connect signals of Thumbnailer object to get know when thumbnail is ready
// connect signals You are interested in (in this case the simplest way - // just thumbnail signal) QObject::connect ( thumb, SIGNAL(thumbnail(QUrl,QUrl,QPixmap,QString)), this, SLOT(thumbnail(QUrl,QUrl,QPixmap)) ); // make list with uris and mime types for request QUrl fileUri ("file:///some/image/path.jpeg"); QString fileMimeType = "image/jpeg"; QList<QUrl> urisList; QStringList mimeList; urisList << fileUri; // You can add as much uris as you want ... mimelList << fileMimeType; // ...just remember to add the same number, // matching mime types
Now it is time to make a request:
// make a request
thumb->request (urisList, mimeList);
or
// make a request and ask Thumbnailer to load every thumbnail in the request thumb->request (urisList, mimeList, true);
In the second case You will get QPixmap in thumbnail()'s third parameter, so you do not need to open and load data itself.
Of course You need to have a slot in Your class which will handle new thumbnail and utilize it. It could be something like this:
public slot void MyClass::thumbnail ( QUrl fileUri, QUrl thumbnailUri, QPixmap pixmap, QString flavor ) { qDebug() << "Thumbnail for image" << fileUri.toString() << << "is located in path:" << thumbnailUri.toString(); // if You made a request with the third parameter set to true You can do: this->label->setPixmap (pixmap); }
You can also use the rest of Thumbnailer's signals to know a little bit more what is happening with Your request. For details see documentation for particular signals and request() method:
QObject::connect ( thumb, SIGNAL(error(QString,QUrl)), this, SLOT(error(QString,QUrl)) ); QObject::connect ( thumb, SIGNAL(dequeued(QUrl)), this, SLOT(dequeued(QUrl)) ); QObject::connect ( thumb, SIGNAL(started()), this, SLOT(loadingStarted()) ); QObject::connect ( thumb, SIGNAL(finished(int)), this, SLOT(loadingFinished(int)) ); QObject::connect ( thumb, SIGNAL(defaultThumbnail(QUrl,QUrl,QPixmap,QString)), this, SLOT(defaultThumbnail(QUrl,QUrl,QPixmap)) );
Beside thumbnailing particular resources You can request for Media Art thumbnails.
In order to do that just call request method with list of MediaArt::Info objects, not QUrl ones. Then listen for signals exactly the same as for normal thumbnails but with MediaArt::Info parameter in place of QUrl as a source of the requests.
Thumbnails::Thumbnailer::~Thumbnailer | ( | ) |
Destruct Thumbnailer object and clean memmory.
All request are automatically canceled/dequeued. All remaining signals are sent before object is deleted but no new thumbnail will arrive - there will be only dequeued and finished signals.
Thumbnails::Thumbnailer::Thumbnailer | ( | QUrl | defaultUri = QUrl() , |
|
QPixmap | defaultPixmap = QPixmap() | |||
) |
Construct new Thumbnailer object with default values.
Default values for defaultThumbnail() signal.
defaultUri | default URI which will passed to defaultThumbnail() signal | |
defaultPixmap | default QPixmap which will passed to defaultThumbnail() signal |
void Thumbnails::Thumbnailer::cancel | ( | bool | sendRemainingSignals = true , |
|
bool | unqueueFromTumbler = true | |||
) |
Cancel all currently running request.
You can call this function if You are not interested anymore in retriving thumbnails You had asked before.
sendRemainingSignals | if You give true here You will get all dequeue signals for resources which were not processed yet; otherwise You will get only finished signal. | |
unqueueFromTumbler | if You cancel request by hand You should also unqueue request from Tumbler. If tubmler crashed or was resetted You should not try to unqueue request from new instance of Tumbler |
static void Thumbnails::Thumbnailer::cleanup | ( | const QString & | prefix, | |
unsigned | before | |||
) | [static] |
Request for cleaning up the cache of invalid or old thumbnails.
prefix | the prefix that must match the URIs of original thumbnailables of whom the thumbnail must be deleted | |
before | filter so that only thumbnails of files that have a modified time older than before are deleted |
static void Thumbnails::Thumbnailer::copy | ( | const QList< QUrl > & | from, | |
const QList< QUrl > & | to | |||
) | [static] |
Update thumbnails cache after some resources were copied.
Length of from and to lists should be exactly the same.
from | list of source resources | |
to | list of target places, where source resources were copied |
QPixmap Thumbnails::Thumbnailer::defaultPixmap | ( | ) | const |
Gets current default Pixmap for thumbnails.
void Thumbnails::Thumbnailer::defaultThumbnail | ( | const QUrl & | uri, | |
const QUrl & | thumbnailUri, | |||
const QPixmap & | pixmap, | |||
const QString & | flavor | |||
) | [signal] |
Thumbnail need to be (re)created.
When You make a request for a thumbnail or resource which does not have thumbnail already it will take some time to create this (sometimes the thumbnail need to be recreated also - this is the same situation). You will get this signal in that case with some defaults values (which You can set by setDefaultPixmap(), setDefaultURI() and Thumbnailer()) which You can utilize to show some infromations to the user that he need to wait a little bit for real thumbnail.
After defaultThumbnail signal You will receive thumbnail signal with some small delay (depends on current performance of the platform)
The definition of signal is the same as
void Thumbnails::Thumbnailer::defaultThumbnail | ( | const MediaArt::Info & | media, | |
const QUrl & | thumbnailUri, | |||
const QPixmap & | pixmap, | |||
const QString & | flavor | |||
) | [signal] |
Media Art's thumbnail is not available yet.
If media art content is not available at call time, or thumbnail of existing media art's content is not available then You will receive this signal. It means that after some time You will receive thumbnail() signal if it was possible to fetch and to thumbnail the media art's content or error() signal if media art's content is not available or there is some problem with it that prevents it to be thumbnailed.
Check definition of thumbnail() signal which is the same as this signal with only one difference - values of thumbnailUri and pixmap ar the default ones, not real.
QUrl Thumbnails::Thumbnailer::defaultURI | ( | ) | const |
Gets current default URI for thumbnails.
void Thumbnails::Thumbnailer::dequeued | ( | const QUrl & | uri | ) | [signal] |
Some request was canceled and removed from queue.
Signals that particular thumbnail request was dequeued (canceled).
uri | QUrl of resource for which thumbnailing was canceled |
void Thumbnails::Thumbnailer::dequeued | ( | const MediaArt::Info & | media | ) | [signal] |
Some request was canceled and removed from queue.
Signals that particular media art's thumbnail request was dequeued (canceled).
media | media art for which thumbnailing was canceled |
void Thumbnails::Thumbnailer::error | ( | const QString & | error, | |
const QUrl & | uri, | |||
const QUrl & | defaultUri = QUrl() , |
|||
const QPixmap & | defaultPixmap = QPixmap() | |||
) | [signal] |
Some error occured during the request.
Signals that there were some error while trying to create thumbnail of uri resource.
Every resource You requested for and which failed will get individual error signal what differs from D-Bus API where some failed requests could be grouped and signaled together.
error | message describing the problem | |
uri | QUrl of resource for which thumbnailing failed | |
defaultUri | QUrl with default thumbnail url | |
defaultPixmap | pixmap with default thumbnail |
void Thumbnails::Thumbnailer::error | ( | const QString & | error, | |
const MediaArt::Info & | media, | |||
const QUrl & | defaultUri = QUrl() , |
|||
const QPixmap & | defaultPixmap = QPixmap() | |||
) | [signal] |
Some error occured during the media art's thumbnail request.
Signals that there were some error while trying to create thumbnail of media art.
error | message describing the problem | |
media | QUrl of resource for which thumbnailing failed | |
defaultUri | QUrl with default thumbnail url | |
defaultPixmap | pixmap with default thumbnail |
void Thumbnails::Thumbnailer::finished | ( | int | left | ) | [signal] |
Some request is done.
Signals that some request has finished. and there is no other work related to it. There will not be any other signals connected with that request.
Please note that if You made a couple of requests it does not mean there will not be ANY other signals. It just means that one of that requests is done - the other could be still in queue and there could be some signals for those other requests.
If You want to know when all request are done You need to check left parameter. When it is equal 0 it means there is no other request processed anymore.
left | says how many other request are still in the queue |
static QStringList Thumbnails::Thumbnailer::getFlavors | ( | ) | [static] |
Returns list of supported flavors.
Flavor describe the kind of thumbnail. You could want to retrive a a normal thumbnail or preview. There could be more options like: large, small, cropped and so on. This function returns to You list with supported flavors on the system.
When You make a request You can ask for particular kind of thumbnail and if You give a wrong flavor error will occur. The default value in request() method will always work. If You do not want to take care about proper flavor value You can also pass empty string as a flavor parameter to request() method.
Visit also ThumbnailerSpec page for more details about flavors:
http://live.gnome.org/ThumbnailerSpec
static QSize Thumbnails::Thumbnailer::getFlavorSize | ( | const QString & | flavor | ) | [static] |
Retrieves a size of particular kind of thumbnails.
flavor | flavor we want to get the size of |
static QStringList Thumbnails::Thumbnailer::getSchedulers | ( | ) | [static] |
Returns list of supported schedulers.
It gives to the developer information what kind of schedulers he can use. For detail informations about what are schedulers and what are the differences between them see: http://live.gnome.org/ThumbnailerSpec
static QMultiHash<QString, QString> Thumbnails::Thumbnailer::getSupported | ( | ) | [static] |
Returns supported MIME types for particular URI schemes.
If You request for resource which is of MIME type not supported for its URI scheme the thumbnail will not be created and You will get error signal for that request.
Returned Hash table as a key has QString with scheme and as a value supported MIME type. There could be more entries with the same scheme so you should check them all to find out if particular MIME type is supported.
static QUrl Thumbnails::Thumbnailer::getThumbnailPath | ( | const QUrl & | uri, | |
const QString & | flavor | |||
) | [static] |
Returns thumbnail's URI for particular resource.
This function just construct the uri pointing to file in which there should be a thumbnail for resource uri. It does not create a thumbnail itself.
uri | uri of resource of which thumbnail we are asking for | |
flavor | defines to what type of thumbnail we want to get the path. See getFlavors() and |
static void Thumbnails::Thumbnailer::move | ( | const QList< QUrl > & | from, | |
const QList< QUrl > & | to | |||
) | [static] |
Update thumbnails cache after some resources were moved.
Length of from and to lists should be exactly the same.
from | list of source resources | |
to | list of target places, where source resources were moved |
static void Thumbnails::Thumbnailer::remove | ( | const QList< QUrl > & | fileUris | ) | [static] |
Update thumbnails cache after some resources were deleted.
fileUris | URI's list of resources which were deleted |
bool Thumbnails::Thumbnailer::request | ( | QList< MediaArt::Info > & | media, | |
bool | sendPixmap = false , |
|||
QString | flavor = QString() , |
|||
QString | scheduler = QString() , |
|||
bool | autoCancel = false , |
|||
bool | sendRemainingSignals = true | |||
) |
Requests for Media Art's thumbnails.
It is exactly the same method as request() but it requests for media art's thumbnails. If some media art content is not available at the call moment, it will also try to fetch that content in the background.
There is no need for mime type here while media art content is always image/jpeg type.
media | list of media arts for which we want to get thumbnails | |
sendPixmap | set to TRUE if You would like to retireve QPixmap with Ready signal; otherwise FALSE | |
scheduler | define what scheduler will be used when requesting thumbnail from tumbler service if empty string is given thumbnailer will use its default scheduler | |
flavor | define what kind of thumbnail user want to retrieve (normal, preview etc.) if empty string is given thumbnailer will use its default flavor | |
autoCancel | set this to true if You want automatically cancel all previous, currently running request | |
sendRemainingSignals | if autoCancel is true, it tells if dequeued will be sent for canceled requests |
bool Thumbnails::Thumbnailer::request | ( | QList< QUrl > & | uris, | |
QStringList & | mimeTypes, | |||
bool | sendPixmap = false , |
|||
QString | flavor = QString() , |
|||
QString | scheduler = QString() , |
|||
bool | autoCancel = false , |
|||
bool | sendRemainingSignals = true | |||
) |
Make a request for thumbnails.
The only required parameters are uris and mimeTypes, which should be list with the same length.
If You want to get pixmap with defaultThumbnail/thumbnail signals remember to put true as a third parameter and if You want to retrieve some particular kind of thumbnail please remember to use flavor argument.
By default all previous, not finished request are not canceled. If You want so You need to be explicit about that and specify autoCancel parameter as a true.
uris | list of resources' uris for which we want to get thumbnails. |
mimeTypes | list with mime types correlated to uris list | |
sendPixmap | set to TRUE if You would like to retireve QPixmap with Ready signal; otherwise FALSE | |
scheduler | define what scheduler will be used when requesting thumbnail from tumbler service if empty string is given thumbnailer will use its default scheduler | |
flavor | define what kind of thumbnail user want to retrieve (normal, preview etc.) if empty string is given thumbnailer will use its default flavor | |
autoCancel | set this to true if You want automatically cancel all previous, currently running request | |
sendRemainingSignals | if autoCancel is true, it tells if dequeued will be sent for canceled requests |
void Thumbnails::Thumbnailer::setDefaultPixmap | ( | QPixmap | pixmap | ) |
Changes the default Pixmap for thumbnails.
pixmap | to new Pixmap for default Pixmap |
void Thumbnails::Thumbnailer::setDefaultURI | ( | QUrl | uri | ) |
Changes the default URI for thumbnails.
uri | new URI for default URI |
void Thumbnails::Thumbnailer::started | ( | ) | [signal] |
New request has started to be processed.
Sent when new request has started.
void Thumbnails::Thumbnailer::thumbnail | ( | const QUrl & | uri, | |
const QUrl & | thumbnailUri, | |||
const QPixmap & | pixmap, | |||
const QString & | flavor | |||
) | [signal] |
New thumbnail is ready for You.
Signals that there is new thumbnail ready and could be used by applications.
Every resource You requested for will get individual thumbnail signal what differs from D-Bus API where some resources could be grouped and signaled together.
uri | describe resource for which thumbnail was requested | |
thumbnailUri | tells You what is the URI of the new thumbnail | |
pixmap | pixmap with new thumbnail (if that information was requested; empty pixmap otherwise); | |
flavor | tells what type of thumbnail was requested |
void Thumbnails::Thumbnailer::thumbnail | ( | const MediaArt::Info & | media, | |
const QUrl & | thumbnailUri, | |||
const QPixmap & | pixmap, | |||
const QString & | flavor | |||
) | [signal] |
New thumbnail for media art is ready for You.
Check documentation for standard thumbnail() signal. This one is exactly the same one, but signals about thumbnail for media art.
media | media art for which we got a thumbnail | |
thumbnailUri | tells You what is the URI of the new thumbnail | |
pixmap | pixmap with new thumbnail (if that information was requested; empty pixmap otherwise); | |
flavor | tells what type of thumbnail was requested |
const QString Thumbnails::Thumbnailer::defaultFlavor [static] |
Default flavor which could be used with getThumbnailPath function.
If user want to get thumbnail path by himself and he want to get default flavor of thumbnail, He can use this value as a second parameter (flavor) of getThumbnailPath()
const QString Thumbnails::Thumbnailer::noopScheduler [static] |
Scheduler 'noop' which returns only already existing thumbnails.
This is a Thumbnailer's provided scheduler. You should use it if You are interested in fast reply from Thumbnailer - it will return You only those thumbnailes which are already existing and error signal for rest of them. Also none of the thumbnail will be updated or checked.