KDECore
KJob Class Reference
The base class for all jobs. More...
#include <kjob.h>

Public Types | |
enum | { NoError = 0, KilledJobError = 1, UserDefinedError = 100 } |
enum | Capability { NoCapabilities = 0x0000, Killable = 0x0001, Suspendable = 0x0002 } |
enum | KillVerbosity { Quietly, EmitResult } |
enum | Unit { Bytes, Files, Directories } |
Public Slots | |
bool | kill (KillVerbosity verbosity=Quietly) |
bool | resume () |
bool | suspend () |
Signals | |
void | description (KJob *job, const QString &title, const QPair< QString, QString > &field1=qMakePair(QString(), QString()), const QPair< QString, QString > &field2=qMakePair(QString(), QString())) |
void | finished (KJob *job) |
void | infoMessage (KJob *job, const QString &plain, const QString &rich=QString()) |
void | percent (KJob *job, unsigned long percent) |
void | processedAmount (KJob *job, KJob::Unit unit, qulonglong amount) |
void | processedSize (KJob *job, qulonglong size) |
void | result (KJob *job) |
void | resumed (KJob *job) |
void | speed (KJob *job, unsigned long speed) |
void | suspended (KJob *job) |
void | totalAmount (KJob *job, KJob::Unit unit, qulonglong amount) |
void | totalSize (KJob *job, qulonglong size) |
void | warning (KJob *job, const QString &plain, const QString &rich=QString()) |
Public Member Functions | |
Capabilities | capabilities () const |
int | error () const |
virtual QString | errorString () const |
QString | errorText () const |
bool | exec () |
bool | isAutoDelete () const |
bool | isSuspended () const |
KJob (QObject *parent=0) | |
unsigned long | percent () const |
qulonglong | processedAmount (Unit unit) const |
void | setAutoDelete (bool autodelete) |
void | setUiDelegate (KJobUiDelegate *delegate) |
virtual void | start ()=0 |
qulonglong | totalAmount (Unit unit) const |
KJobUiDelegate * | uiDelegate () const |
virtual | ~KJob () |
Protected Member Functions | |
virtual bool | doKill () |
virtual bool | doResume () |
virtual bool | doSuspend () |
void | emitPercent (qulonglong processedAmount, qulonglong totalAmount) |
void | emitResult () |
void | emitSpeed (unsigned long speed) |
KJob (KJobPrivate &dd, QObject *parent) | |
void | setCapabilities (Capabilities capabilities) |
void | setError (int errorCode) |
void | setErrorText (const QString &errorText) |
void | setPercent (unsigned long percentage) |
void | setProcessedAmount (Unit unit, qulonglong amount) |
void | setTotalAmount (Unit unit, qulonglong amount) |
Protected Attributes | |
KJobPrivate *const | d_ptr |
Detailed Description
The base class for all jobs.
For all jobs created in an application, the code looks like
void SomeClass::methodWithAsynchronousJobCall() { KJob * job = someoperation( some parameters ); connect( job, SIGNAL( result( KJob * ) ), this, SLOT( handleResult( KJob * ) ) ); job->start(); }
(other connects, specific to the job)
And handleResult is usually at least:
With the synchronous interface the code looks like
void SomeClass::methodWithSynchronousJobCall() { KJob *job = someoperation( some parameters ); if ( !job->exec() ) { // An error occurred } else { // Do something } }
- Note:
- : KJob and its subclasses is meant to be used in a fire-and-forget way. It's deleting itself when it has finished using deleteLater() so the job instance disappears after the next event loop run.
Definition at line 79 of file kjob.h.
Member Enumeration Documentation
anonymous enum |
enum KJob::Capability |
enum KJob::KillVerbosity |
enum KJob::Unit |
Constructor & Destructor Documentation
KJob::KJob | ( | QObject * | parent = 0 |
) | [explicit] |
KJob::KJob | ( | KJobPrivate & | dd, | |
QObject * | parent | |||
) | [protected] |
Member Function Documentation
KJob::Capabilities KJob::capabilities | ( | ) | const |
Returns the capabilities of this job.
- Returns:
- the capabilities that this job supports
- See also:
- setCapabilities()
void KJob::description | ( | KJob * | job, | |
const QString & | title, | |||
const QPair< QString, QString > & | field1 = qMakePair(QString(), QString()) , |
|||
const QPair< QString, QString > & | field2 = qMakePair(QString(), QString()) | |||
) | [signal] |
Emitted to display general description of this job.
A description has a title and two optional fields which can be used to complete the description.
Examples of titles are "Copying", "Creating resource", etc. The fields of the description can be "Source" with an URL, and, "Destination" with an URL for a "Copying" description.
- Parameters:
-
job the job that emitted this signal title the general description of the job field1 first field (localized name and value) field2 second field (localized name and value)
bool KJob::doKill | ( | ) | [protected, virtual] |
bool KJob::doResume | ( | ) | [protected, virtual] |
bool KJob::doSuspend | ( | ) | [protected, virtual] |
void KJob::emitPercent | ( | qulonglong | processedAmount, | |
qulonglong | totalAmount | |||
) | [protected] |
void KJob::emitResult | ( | ) | [protected] |
Utility function to emit the result signal, and suicide this job.
It first notifies the observers to hide the progress for this job using the finished() signal.
- Note:
- : Deletes this job using deleteLater().
- See also:
- result()
- finished()
void KJob::emitSpeed | ( | unsigned long | speed | ) | [protected] |
int KJob::error | ( | ) | const |
QString KJob::errorString | ( | ) | const [virtual] |
Converts an error code and a non-i18n error message into an error message in the current language.
The low level (non-i18n) error message (usually a url) is put into the translated error message using 1.
Example for errid == ERR_CANNOT_OPEN_FOR_READING:
Only call if error is not 0.
- Returns:
- the error message and if there is no error, a message telling the user that the app is broken, so check with error() whether there is an error
QString KJob::errorText | ( | ) | const |
bool KJob::exec | ( | ) |
void KJob::finished | ( | KJob * | job | ) | [signal] |
Emitted when the job is finished, in any case.
It is used to notify observers that the job is terminated and that progress can be hidden.
This is a private signal, it can't be emitted directly by subclasses of KJob, use emitResult() instead.
Client code is not supposed to connect to this signal, signal result should be used instead.
- Parameters:
-
job the job that emitted this signal
For internal use only.
void KJob::infoMessage | ( | KJob * | job, | |
const QString & | plain, | |||
const QString & | rich = QString() | |||
) | [signal] |
Emitted to display state information about this job.
Examples of message are "Resolving host", "Connecting to host...", etc.
- Parameters:
-
job the job that emitted this signal plain the info message rich the rich text version of the message, or QString() is none is available
bool KJob::isAutoDelete | ( | ) | const |
bool KJob::isSuspended | ( | ) | const |
bool KJob::kill | ( | KillVerbosity | verbosity = Quietly |
) | [slot] |
Aborts this job.
This kills and deletes the job.
- Parameters:
-
verbosity if equals to EmitResult, Job will emit signal result and ask uiserver to close the progress window. verbosity
is set to EmitResult for subjobs. Whether applications should call with Quietly or EmitResult depends on whether they rely on result being emitted or not. Please notice that ifverbosity
is set to Quietly, signal result will NOT be emitted.
- Returns:
- true if the operation is supported and succeeded, false otherwise
void KJob::percent | ( | KJob * | job, | |
unsigned long | percent | |||
) | [signal] |
Progress signal showing the overall progress of the job This is valid for any kind of job, and allows using a a progress bar very easily.
(see KProgressBar). Note that this signal is not emitted for finished jobs.
This is a private signal, it can't be emitted directly by subclasses of KJob, use emitPercent(), setPercent() setTotalAmount() or setProcessedAmount() instead.
- Parameters:
-
job the job that emitted this signal percent the percentage
unsigned long KJob::percent | ( | ) | const |
void KJob::processedAmount | ( | KJob * | job, | |
KJob::Unit | unit, | |||
qulonglong | amount | |||
) | [signal] |
Regularly emitted to show the progress of this job by giving the current amount.
The unit of this amount is sent too. It can be emitted several times if the job manages several different units.
This is a private signal, it can't be emitted directly by subclasses of KJob, use setProcessedAmount() instead.
- Parameters:
-
job the job that emitted this signal unit the unit of the processed amount amount the processed amount
qulonglong KJob::processedAmount | ( | Unit | unit | ) | const |
void KJob::processedSize | ( | KJob * | job, | |
qulonglong | size | |||
) | [signal] |
Regularly emitted to show the progress of this job (current data size in bytes for transfers, entries listed, etc.
).
This is a private signal, it can't be emitted directly by subclasses of KJob, use setProcessedAmount() instead.
- Parameters:
-
job the job that emitted this signal size the processed size
void KJob::result | ( | KJob * | job | ) | [signal] |
Emitted when the job is finished (except when killed with KJob::Quietly).
Use error to know if the job was finished with error.
This is a private signal, it can't be emitted directly by subclasses of KJob, use emitResult() instead.
Please connect to this signal instead of finished.
- Parameters:
-
job the job that emitted this signal
- See also:
- kill
bool KJob::resume | ( | ) | [slot] |
void KJob::resumed | ( | KJob * | job | ) | [signal] |
Emitted when the job is resumed.
This is a private signal, it can't be emitted directly by subclasses of KJob.
- Parameters:
-
job the job that emitted this signal
void KJob::setAutoDelete | ( | bool | autodelete | ) |
set the auto-delete property of the job.
If autodelete
is set to false the job will not delete itself once it is finished.
The default for any KJob is to automatically delete itself.
- Parameters:
-
autodelete set to false to disable automatic deletion of the job.
void KJob::setCapabilities | ( | Capabilities | capabilities | ) | [protected] |
Sets the capabilities for this job.
- Parameters:
-
capabilities are the capabilities supported by this job
- See also:
- capabilities()
void KJob::setError | ( | int | errorCode | ) | [protected] |
Sets the error code.
It should be called when an error is encountered in the job, just before calling emitResult().
- Parameters:
-
errorCode the error code
- See also:
- emitResult()
void KJob::setErrorText | ( | const QString & | errorText | ) | [protected] |
Sets the error text.
It should be called when an error is encountered in the job, just before calling emitResult().
- Parameters:
-
errorText the error text
- See also:
- emitResult()
void KJob::setPercent | ( | unsigned long | percentage | ) | [protected] |
void KJob::setProcessedAmount | ( | Unit | unit, | |
qulonglong | amount | |||
) | [protected] |
Sets the processed size.
The processedAmount() and percent() signals are emitted if the values changed. The percent() signal is emitted only for the progress unit.
- Parameters:
-
unit the unit of the new processed amount amount the new processed amount
void KJob::setTotalAmount | ( | Unit | unit, | |
qulonglong | amount | |||
) | [protected] |
Sets the total size.
The totalSize() and percent() signals are emitted if the values changed. The percent() signal is emitted only for the progress unit.
- Parameters:
-
unit the unit of the new total amount amount the new total amount
void KJob::setUiDelegate | ( | KJobUiDelegate * | delegate | ) |
Attach a UI delegate to this job.
If the job had another UI delegate, it's automatically deleted. Once attached to the job, the UI delegate will be deleted with the job.
- Parameters:
-
delegate the new UI delegate to use
- See also:
- KJobUiDelegate
void KJob::speed | ( | KJob * | job, | |
unsigned long | speed | |||
) | [signal] |
Emitted to display information about the speed of this job.
This is a private signal, it can't be emitted directly by subclasses of KJob, use emitSpeed() instead.
- Parameters:
-
job the job that emitted this signal speed the speed in bytes/s
virtual void KJob::start | ( | ) | [pure virtual] |
Starts the job asynchronously.
When the job is finished, result() is emitted.
This is the method all subclasses need to implement. It should setup and trigger the workload of the job. It should not do any work itself. This includes all signals and terminating the job, e.g. by emitResult(). The workload, which could be another method of the subclass, is to be triggered using the event loop, e.g. by code like:
void ExampleJob::start() { QTimer::singleShot( 0, this, SLOT( doWork() ) ); }
bool KJob::suspend | ( | ) | [slot] |
void KJob::suspended | ( | KJob * | job | ) | [signal] |
Emitted when the job is suspended.
This is a private signal, it can't be emitted directly by subclasses of KJob.
- Parameters:
-
job the job that emitted this signal
void KJob::totalAmount | ( | KJob * | job, | |
KJob::Unit | unit, | |||
qulonglong | amount | |||
) | [signal] |
Emitted when we know the amount the job will have to process.
The unit of this amount is sent too. It can be emitted several times if the job manages several different units.
This is a private signal, it can't be emitted directly by subclasses of KJob, use setTotalAmount() instead.
- Parameters:
-
job the job that emitted this signal unit the unit of the total amount amount the total amount
qulonglong KJob::totalAmount | ( | Unit | unit | ) | const |
void KJob::totalSize | ( | KJob * | job, | |
qulonglong | size | |||
) | [signal] |
Emitted when we know the size of this job (data size in bytes for transfers, number of entries for listings, etc).
This is a private signal, it can't be emitted directly by subclasses of KJob, use setTotalAmount() instead.
- Parameters:
-
job the job that emitted this signal size the total size
KJobUiDelegate * KJob::uiDelegate | ( | ) | const |
Emitted to display a warning about this job.
- Parameters:
-
job the job that emitted this signal plain the warning message rich the rich text version of the message, or QString() is none is available
Member Data Documentation
KJobPrivate* const KJob::d_ptr [protected] |
The documentation for this class was generated from the following files: