digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
Digikam::ProgressManager Class Reference

The ProgressManager singleton keeps track of all ongoing transactions and notifies observers (progress dialogs) when their progress percent value changes, when they are completed (by their owner), and when they are canceled. More...

+ Inheritance diagram for Digikam::ProgressManager:

Public Slots

void slotAbortAll ()
 Aborts all running jobs.
 
void slotStandardCancelHandler (ProgressItem *item)
 Calls setCompleted() on the item, to make sure it goes away.
 

Signals

void completeTransactionDeferred (ProgressItem *item)
 
void progressItemAdded (ProgressItem *)
 
void progressItemCanceled (ProgressItem *)
 
void progressItemCompleted (ProgressItem *)
 
void progressItemLabel (ProgressItem *, const QString &)
 
void progressItemProgress (ProgressItem *, unsigned int)
 
void progressItemStatus (ProgressItem *, const QString &)
 
void progressItemThumbnail (ProgressItem *, const QPixmap &)
 
void progressItemUsesBusyIndicator (ProgressItem *, bool)
 
void showProgressView ()
 Emitted when an operation requests the listeners to be shown.
 

Public Member Functions

ProgressItemfindItembyId (const QString &id) const
 
QString getUniqueID ()
 Use this to acquire a unique id number which can be used to discern an operation from all others going on at the same time.
 
bool isEmpty () const
 
ProgressItemsingleItem () const
 

Static Public Member Functions

static bool addProgressItem (ProgressItem *const t, ProgressItem *const parent=nullptr)
 Add a created progressItem outside manager with the given parent.
 
static ProgressItemcreateProgressItem (const QString &id, const QString &label, const QString &status=QString(), bool canBeCanceled=true, bool hasThumb=false)
 Use this version if you have the id string of the parent but without the parent instance.
 
static ProgressItemcreateProgressItem (const QString &label, const QString &status=QString(), bool canBeCanceled=true, bool hasThumb=false)
 Creates a ProgressItem with a unique id and the given label.
 
static ProgressItemcreateProgressItem (const QString &parent, const QString &id, const QString &label, const QString &status=QString(), bool canBeCanceled=true, bool hasThumb=false)
 Use this version if you have the id string of the parent and want to add a subjob to it.
 
static ProgressItemcreateProgressItem (ProgressItem *const parent, const QString &id, const QString &label, const QString &status=QString(), bool canBeCanceled=true, bool hasThumb=false)
 Creates a new progressItem with the given parent, id, label and initial status.
 
static void emitShowProgressView ()
 Ask all listeners to show the progress dialog, because there is something that wants to be shown.
 
static ProgressManagerinstance ()
 

Friends

class ProgressManagerCreator
 

Detailed Description

Each ProgressItem emits those signals individually and the singleton broadcasts them. Use the createProgressItem() statics to acquire an item and then call ->setProgress( int percent ) on it every time you want to update the item and ->setComplete() when the operation is done. This will delete the item. Connect to the item's progressItemCanceled() signal to be notified when the user cancels the transaction using one of the observing progress dialogs or by calling item->cancel() in some other way. The owner is responsible for calling setComplete() on the item, even if it is canceled. Use the standardCancelHandler() slot if that is all you want to do on cancel.

Note
if you request an item with a certain id and there is already one with that id, there will not be a new one created but the existing one will be returned. This is convenient for accessing items that are needed regularly without the to store a pointer to them or to add child items to parents by id.

Member Function Documentation

◆ addProgressItem()

bool Digikam::ProgressManager::addProgressItem ( ProgressItem *const  t,
ProgressItem *const  parent = nullptr 
)
static
Parameters
tThe process to add on manager.
parentSpecify an already existing item as the parent of this one (can be null).
Returns
true if ProgressItem have been added to manager, else false.

◆ createProgressItem() [1/4]

ProgressItem * Digikam::ProgressManager::createProgressItem ( const QString &  id,
const QString &  label,
const QString &  status = QString(),
bool  canBeCanceled = true,
bool  hasThumb = false 
)
static
Parameters
idUsed to identify this operation for cancel and progress info.
labelThe text to be displayed by progress handlers
statusAdditional text to be displayed for the item.
canBeCanceledcan the user cancel this operation? Cancelling the parent will cancel the children as well (if they can be canceled) and ongoing children prevent parents from finishing.
hasThumbflag to indicate if progress item has a thumbnail.
Returns
The ProgressItem representing the operation.

◆ createProgressItem() [2/4]

ProgressItem * Digikam::ProgressManager::createProgressItem ( const QString &  label,
const QString &  status = QString(),
bool  canBeCanceled = true,
bool  hasThumb = false 
)
static

This is the simplest way to acquire a progress item. It will not have a parent.

Parameters
labelThe text to be displayed by progress handlers
statusAdditional text to be displayed for the item.
canBeCanceledCan the user cancel this operation? Cancelling the parent will cancel the children as well (if they can be canceled) and ongoing children prevent parents from finishing.
hasThumbflag to indicate if progress item has a thumbnail.
Returns
The ProgressItem representing the operation.

◆ createProgressItem() [3/4]

ProgressItem * Digikam::ProgressManager::createProgressItem ( const QString &  parent,
const QString &  id,
const QString &  label,
const QString &  status = QString(),
bool  canBeCanceled = true,
bool  hasThumb = false 
)
static
Parameters
parentSpecify an already existing item as the parent of this one.
idUsed to identify this operation for cancel and progress info.
labelThe text to be displayed by progress handlers
statusAdditional text to be displayed for the item.
canBeCanceledcan the user cancel this operation? Cancelling the parent will cancel the children as well (if they can be canceled) and ongoing children prevent parents from finishing.
hasThumbflag to indicate if progress item has a thumbnail.
Returns
The ProgressItem representing the operation.

◆ createProgressItem() [4/4]

ProgressItem * Digikam::ProgressManager::createProgressItem ( ProgressItem *const  parent,
const QString &  id,
const QString &  label,
const QString &  status = QString(),
bool  canBeCanceled = true,
bool  hasThumb = false 
)
static
Parameters
parentSpecify an already existing item as the parent of this one.
idUsed to identify this operation for cancel and progress info.
labelThe text to be displayed by progress handlers
statusAdditional text to be displayed for the item.
canBeCanceledcan the user cancel this operation? Cancelling the parent will cancel the children as well (if they can be canceled) and ongoing children prevent parents from finishing.
hasThumbflag to indicate if progress item has a thumbnail.
Returns
The ProgressItem representing the operation.

◆ findItembyId()

ProgressItem * Digikam::ProgressManager::findItembyId ( const QString &  id) const
Returns
the progressitem for this
Parameters
idif it exist, else null.

◆ getUniqueID()

QString Digikam::ProgressManager::getUniqueID ( )

Use that number as the id string for your progressItem to ensure it is unique.

Returns
The string with the unique ID number.

◆ instance()

ProgressManager * Digikam::ProgressManager::instance ( )
static
Returns
The singleton instance of this class.

◆ isEmpty()

bool Digikam::ProgressManager::isEmpty ( ) const
Returns
true when there are no more progress items.

◆ progressItemAdded

void Digikam::ProgressManager::progressItemAdded ( ProgressItem )
signal

◆ progressItemCanceled

void Digikam::ProgressManager::progressItemCanceled ( ProgressItem )
signal

◆ progressItemCompleted

void Digikam::ProgressManager::progressItemCompleted ( ProgressItem )
signal

◆ progressItemLabel

void Digikam::ProgressManager::progressItemLabel ( ProgressItem ,
const QString &   
)
signal

◆ progressItemProgress

void Digikam::ProgressManager::progressItemProgress ( ProgressItem ,
unsigned int   
)
signal

◆ progressItemStatus

void Digikam::ProgressManager::progressItemStatus ( ProgressItem ,
const QString &   
)
signal

◆ progressItemThumbnail

void Digikam::ProgressManager::progressItemThumbnail ( ProgressItem ,
const QPixmap &   
)
signal

◆ progressItemUsesBusyIndicator

void Digikam::ProgressManager::progressItemUsesBusyIndicator ( ProgressItem ,
bool   
)
signal

◆ showProgressView

void Digikam::ProgressManager::showProgressView ( )
signal

Use emitShowProgressView() to trigger it.

◆ singleItem()

ProgressItem * Digikam::ProgressManager::singleItem ( ) const
Returns
the only top level progressitem when there's only one. Returns 0 if there is no item, or more than one top level item. Since this is used to calculate the overall progress, it will also return 0 if there is an item which uses a busy indicator, since that will invalidate the overall progress.

◆ slotAbortAll

void Digikam::ProgressManager::slotAbortAll ( )
slot

Bound to "Esc"

◆ slotStandardCancelHandler

void Digikam::ProgressManager::slotStandardCancelHandler ( ProgressItem item)
slot

Provided for convenience.

Parameters
itemthe canceled item.