Thumbnails::Thumbnailer Class Reference

Requests and delivers thumbnails for given URI-based resources. More...

#include <thumbnailer.h>

List of all members.

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.

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.
Those function could be used after some resources are moved, copied or deleted. That should be reflected also in thumbnail's cache.

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


Detailed Description

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.
See also:
MediaArt::Info, Album, Artist, Track, Podcast, Radio documentation
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.

Constructor & Destructor Documentation

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.

Parameters:
defaultUri default URI which will passed to defaultThumbnail() signal
defaultPixmap default QPixmap which will passed to defaultThumbnail() signal


Member Function Documentation

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.

Parameters:
from list of source resources
to list of target places, where source resources were moved

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.

Parameters:
from list of source resources
to list of target places, where source resources were copied

static void Thumbnails::Thumbnailer::remove ( const QList< QUrl > &  fileUris  )  [static]

Update thumbnails cache after some resources were deleted.

Parameters:
fileUris URI's list of resources which were deleted

static void Thumbnails::Thumbnailer::cleanup ( const QString &  prefix,
unsigned  before 
) [static]

Request for cleaning up the cache of invalid or old thumbnails.

Parameters:
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 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.

Returns:
a map between supported URI schemes and MIME types

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

Returns:
StringList with supported schedulers

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

Returns:
StringList with supported flavors

static QSize Thumbnails::Thumbnailer::getFlavorSize ( const QString &  flavor  )  [static]

Retrieves a size of particular kind of thumbnails.

Parameters:
flavor flavor we want to get the size of
Returns:
QSize structure which tells what dimensions have the flavor If given flavor does not exist it returns invalid QSize.

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.

Parameters:
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
Returns:
QUrl pointing to thumbnail of uri resource http://live.gnome.org/ThumbnailerSpec for more details about flavors.

void Thumbnails::Thumbnailer::setDefaultURI ( QUrl  uri  ) 

Changes the default URI for thumbnails.

Note:
When creating a QUrl objects please remember to use proper constructor/function. For strings with encoded urls (like those returned to You by for example qttracker) You need to use QUrl::fromEncoded(QString) function.
See also:
Comments for QUrl constructor: http://doc.trolltech.com/4.6/qurl.html#QUrl-2

defaultThumbnail()

Parameters:
uri new URI for default URI

void Thumbnails::Thumbnailer::setDefaultPixmap ( QPixmap  pixmap  ) 

Changes the default Pixmap for thumbnails.

See also:
defaultThumbnail()
Parameters:
pixmap to new Pixmap for default Pixmap

QUrl Thumbnails::Thumbnailer::defaultURI (  )  const

Gets current default URI for thumbnails.

See also:
defaultThumbnail()
Returns:
current default QUrl in human readable format (not encoded)

QPixmap Thumbnails::Thumbnailer::defaultPixmap (  )  const

Gets current default Pixmap for thumbnails.

See also:
defaultThumbnail()
Returns:
current default QPixmap

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.

Parameters:
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

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.

Parameters:
uris list of resources' uris for which we want to get thumbnails.
Note:
When creating a QUrl objects please remember to use proper constructor/function. For strings with encoded urls (like those returned to You by for example qttracker) You need to use QUrl::fromEncoded(QString) function.
See also:
Comments for QUrl constructor: http://doc.trolltech.com/4.6/qurl.html#QUrl-2
Parameters:
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
Returns:
true if there was any request made to tumbler. It means that there could be some signals later (but not necessary). false means that all thumbnails were ready before request was made to Thumbnailer - that tells us that all signals from Thumbnailer connected with request were arleady sent.

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.

Parameters:
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
Returns:
true if there was any request made to tumbler (MediaArt Requester). It means that there could be some signals later (but not necessary). false means that all thumbnails and MediaArts were ready before request was made to Thumbnailer - that tells us that all signals from Thumbnailer connected with request were arleady sent.
See also:
request()

void Thumbnails::Thumbnailer::started (  )  [signal]

New request has started to be processed.

Sent when new request has started.

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.

Parameters:
left says how many other request are still in the queue

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.

Parameters:
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.

Parameters:
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
See also:
thumbnail()

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

See also:
thumbnail() signal.

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.

void Thumbnails::Thumbnailer::dequeued ( const QUrl &  uri  )  [signal]

Some request was canceled and removed from queue.

Signals that particular thumbnail request was dequeued (canceled).

Parameters:
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).

Parameters:
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.

Parameters:
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.

Parameters:
error message describing the problem
media QUrl of resource for which thumbnailing failed
defaultUri QUrl with default thumbnail url
defaultPixmap pixmap with default thumbnail
See also:
error()


Member Data Documentation

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.

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()


The documentation for this class was generated from the following file:

Generated on Wed Oct 3 19:23:42 2012 for thumbnailer by  doxygen 1.5.6