Thumbnailer Qt API

Overview

Introduction

libthumbnailer-qt.so provides access to Unity's thumbnailer service (see the thumbnailer-service(1) man page). The implementation accesses the thumbnailer service via its DBus interface.

Methods to retrieve thumbnails are asynchronous; you can also use them synchronously by calling waitForFinished() on the Request that is returned from the asynchronous methods.

Asynchronous API

We'll use the following class definition to illustrate how to retrieve thumbnails asynchronously. (Note that this is a naive implementation; a more realistic implementation would allow multiple requests to be in progress.)

class AsyncThumbnailProvider : public QObject
{
Q_OBJECT
public:
AsyncThumbnailProvider() = default;
void getThumbnail(QString const& path, QSize const& size);
QImage image() const
{
if (request_ && request_->isValid())
{
return request_->image();
}
return QImage();
}
Q_SIGNALS:
void imageReady();
public Q_SLOTS:
void requestFinished();
private:
QSharedPointer<unity::thumbnailer::qt::Request> request_;
};

To retrieve a thumbnail asynchronously, you call the getThumbnail() method. (If you are intersted in album covers and artist images, you will also need to create methods to retrieve those. The implementation is almost identical, so we do not show it here.)

getThumbnail() does not block and returns a QSharedPointer to a Request object, which emits emits a finished() signal once the request is complete. Therefore, our getThumbnail() implementation connects the request's finished() signal to the requestFinished() slot of our class. The implementation of requestFinished() checks if the request succeeded; the caller can retrieve the actual image by calling the image() method.

void AsyncThumbnailProvider::getThumbnail(QString const& path, QSize const& size)
{
request_ = thumbnailer_.getThumbnail(path, size);
connect(request_.data(), &unity::thumbnailer::qt::Request::finished,
this, &AsyncThumbnailProvider::requestFinished);
}
void AsyncThumbnailProvider::requestFinished()
{
if (request_->isValid())
{
Q_EMIT imageReady();
}
else
{
request_.reset(nullptr);
QString errorMessage = request_->errorMessage();
// Do whatever you need to do to report the error.
}
}

Synchronous API

For synchronous requests, we can use the following class:

class SyncThumbnailProvider : public QObject
{
Q_OBJECT
public:
SyncThumbnailProvider() = default;
QImage getThumbnail(QString const& path, QSize const& size);
private:
};

The implementation is trivial: we simple start the request and wait for it to complete before returning the image:

QImage SyncThumbnailProvider::getThumbnail(QString const& path, QSize const& size)
{
auto request = thumbnailer_.getThumbnail(path, size);
request->waitForFinished(); // Blocks until the response is ready.
if (request->isValid())
{
return request->image();
}
QString errorMessage = request->errorMessage();
// Do whatever you need to do to report the error.
return QImage();
}

Note that waitForFinished() can block the calling thread for several seconds, so do not call this from the UI thread.