KJob Class Reference
from PyKDE4.kdecore import *
Inherits: QObject
Subclasses: KCompositeJob
Detailed Description
- Abstract class:
- This class can be used as a base class for new classes, but can not be instantiated directly.
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:
void SomeClass.handleResult( KJob *job ) { if ( job->error() ) doSomething(); }
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.
Enumerations | |
Capability | { NoCapabilities, Killable, Suspendable } Typesafe wrapper: Capabilities |
KillVerbosity | { Quietly, EmitResult } |
Unit | { Bytes, Files, Directories } |
anonymous | { NoError, KilledJobError, UserDefinedError } |
Signals | |
description (KJob job, QString title, QPair | |
infoMessage (KJob job, QString plain, QString rich=QString()) | |
warning (KJob job, QString plain, QString rich=QString()) | |
Methods | |
__init__ (self, QObject parent=0) | |
__init__ (self, KJobPrivate dd, QObject parent) | |
KJob.Capabilities | capabilities (self) |
description (self, KJob job, QString title, QPair | |
bool | doKill (self) |
bool | doResume (self) |
bool | doSuspend (self) |
emitPercent (self, long processedAmount, long totalAmount) | |
emitResult (self) | |
emitSpeed (self, long speed) | |
int | error (self) |
QString | errorString (self) |
QString | errorText (self) |
bool | exec_ (self) |
infoMessage (self, KJob job, QString plain, QString rich=QString()) | |
bool | isAutoDelete (self) |
bool | isSuspended (self) |
bool | kill (self, KJob.KillVerbosity verbosity=KJob.Quietly) |
long | percent (self) |
long | processedAmount (self, KJob.Unit unit) |
bool | resume (self) |
setAutoDelete (self, bool autodelete) | |
setCapabilities (self, KJob.Capabilities capabilities) | |
setError (self, int errorCode) | |
setErrorText (self, QString errorText) | |
setPercent (self, long percentage) | |
setProcessedAmount (self, KJob.Unit unit, long amount) | |
setTotalAmount (self, KJob.Unit unit, long amount) | |
setUiDelegate (self, KJobUiDelegate delegate) | |
start (self) | |
bool | suspend (self) |
long | totalAmount (self, KJob.Unit unit) |
KJobUiDelegate | uiDelegate (self) |
warning (self, KJob job, QString plain, QString rich=QString()) |
Method Documentation
__init__ | ( | self, | ||
QObject | parent=0 | |||
) |
Creates a new KJob object.
- Parameters:
-
parent the parent QObject
__init__ | ( | self, | ||
KJobPrivate | dd, | |||
QObject | parent | |||
) |
KJob.Capabilities capabilities | ( | self ) |
Returns the capabilities of this job.
- Returns:
- the capabilities that this job supports
- See also:
- setCapabilities()
description | ( | self, | ||
KJob | job, | |||
QString | title, | |||
QPair |
field1=qMakePair(QString(),QString()), | |||
QPair |
field2=qMakePair(QString(),QString()) | |||
) |
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)
- Signal syntax:
QObject.connect(source, SIGNAL("description(KJob*, const QString&, const QPair
&, const QPair &)"), target_slot)
bool doKill | ( | self ) |
Aborts this job quietly. This simply kills the job, no error reporting or job deletion should be involved.
- Returns:
- true if the operation is supported and succeeded, false otherwise
bool doResume | ( | self ) |
Resumes this job.
- Returns:
- true if the operation is supported and succeeded, false otherwise
bool doSuspend | ( | self ) |
Suspends this job.
- Returns:
- true if the operation is supported and succeeded, false otherwise
emitPercent | ( | self, | ||
long | processedAmount, | |||
long | totalAmount | |||
) |
Utility function for inherited jobs. Emits the percent signal if bigger than previous value, after calculating it from the parameters.
- Parameters:
-
processedAmount the processed amount totalAmount the total amount
- See also:
- percent()
emitResult | ( | self ) |
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()
- See also:
- finished()
emitSpeed | ( | self, | ||
long | speed | |||
) |
Utility function for inherited jobs. Emits the speed signal and starts the timer for removing that info
- Parameters:
-
speed the speed in bytes/s
int error | ( | self ) |
Returns the error code, if there has been an error. Only call this method from the slot connected to result().
- Returns:
- the error code for this job, 0 if no error.
QString errorString | ( | self ) |
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:
i18n( "Could not read\n%1" , errorText() );Do not call it 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 errorText | ( | self ) |
Returns the error text if there has been an error. Only call if error is not 0. This is really internal, better use errorString.
- Returns:
- a string to help understand the error, usually the url related to the error. Only valid if error() is not 0.
bool exec_ | ( | self ) |
Executes the job synchronously.
- Returns:
- true if the job has been executed without error, false otherwise
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
- Signal syntax:
QObject.connect(source, SIGNAL("infoMessage(KJob*, const QString&, const QString&)"), target_slot)
bool isAutoDelete | ( | self ) |
Returns whether this job automatically deletes itself once the job is finished.
- Returns:
- whether the job is deleted automatically after finishing.
bool isSuspended | ( | self ) |
Returns if the job was suspended with the suspend() call.
- Returns:
- if the job was suspended
- See also:
- suspend() resume()
bool kill | ( | self, | ||
KJob.KillVerbosity | verbosity=KJob.Quietly | |||
) |
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.
- Returns:
- true if the operation is supported and succeeded, false otherwise
long percent | ( | self ) |
Returns the overall progress of this job.
- Returns:
- the overall progress of this job
long processedAmount | ( | self, | ||
KJob.Unit | unit | |||
) |
Returns the processed amount of a given unit for this job.
- Parameters:
-
unit the unit of the requested amount
- Returns:
- the processed size
bool resume | ( | self ) |
Resumes this job.
- Returns:
- true if the operation is supported and succeeded, false otherwise
setAutoDelete | ( | self, | ||
bool | autodelete | |||
) |
set the auto-delete property of the job. If autodelete is set to false the job will not delete itself once its finished.
The default for any KJob is to automatically delete itself.
- Parameters:
-
autodelete set to false to disable automatic deletion of the job.
setCapabilities | ( | self, | ||
KJob.Capabilities | capabilities | |||
) |
Sets the capabilities for this job.
- Parameters:
-
capabilities are the capabilities supported by this job
- See also:
- capabilities()
setError | ( | self, | ||
int | errorCode | |||
) |
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()
setErrorText | ( | self, | ||
QString | errorText | |||
) |
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()
setPercent | ( | self, | ||
long | percentage | |||
) |
Sets the overall progress of the job. The percent() signal is emitted if the value changed.
- Parameters:
-
percentage the new overall progress
setProcessedAmount | ( | self, | ||
KJob.Unit | unit, | |||
long | amount | |||
) |
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
setTotalAmount | ( | self, | ||
KJob.Unit | unit, | |||
long | amount | |||
) |
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
setUiDelegate | ( | self, | ||
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
start | ( | self ) |
- Abstract method:
- This method is abstract and can be overridden but not called directly.
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 suspend | ( | self ) |
Suspends this job. The job should be kept in a state in which it is possible to resume it.
- Returns:
- true if the operation is supported and succeeded, false otherwise
long totalAmount | ( | self, | ||
KJob.Unit | unit | |||
) |
Returns the total amount of a given unit for this job.
- Parameters:
-
unit the unit of the requested amount
- Returns:
- the total size
KJobUiDelegate uiDelegate | ( | self ) |
Retrieves the delegate attached to this job.
- Returns:
- the delegate attached to this job, or 0 if there's no such delegate
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
- Signal syntax:
QObject.connect(source, SIGNAL("warning(KJob*, const QString&, const QString&)"), target_slot)
Enumeration Documentation
Capability |
- Note:
- It is necessary to wrap members of this enumeration in a
Capabilities
instance when passing them to a method as group of flags. For example:Capabilities( NoCapabilities | Killable)
- Enumerator:
-
NoCapabilities = 0x0000 Killable = 0x0001 Suspendable = 0x0002
KillVerbosity |
- Enumerator:
-
Quietly EmitResult
Unit |
- Enumerator:
-
Bytes Files Directories
anonymous |
- Enumerator:
-
NoError = 0 KilledJobError = 1 UserDefinedError = 100