KDE 4.9 PyKDE API Reference

- KDE's Python API

# KJob Class Reference

`from PyKDE4.kdecore import *`

Inherits: QObject
Subclasses: KCompositeJob

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

     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
       }
     }

Subclasses must implement start(), which should trigger the execution of the job (although the work should be done asynchronously). errorString() should also be reimplemented by any subclasses that introduce new error codes.

@note: KJob and its subclasses are meant to be used in a fire-and-forget way. Jobs will delete themselves when they finish using deleteLater() (although this behaviour can be changed), so a job instance will disappear after the next event loop run.

## Enumerations

<anonymous> | { NoError, KilledJobError, UserDefinedError }
Capability | { NoCapabilities, Killable, Suspendable }
KillVerbosity | { Quietly, EmitResult }
Unit | { Bytes, Files, Directories }

## Signals

| description (KJob job, QString title, (QString,QString) field1=qMakePair(QString(),QString()), (QString,QString) field2=qMakePair(QString(),QString()))
| infoMessage (KJob job, QString plain, QString rich=QString())
| result (KJob job)
| warning (KJob job, QString plain, QString rich=QString())

## Methods

| __init__ (self, QObject parent=0)
KJob.Capabilities | capabilities (self)
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)
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)

## Signal Documentation

description | ( | KJob | job,
|  | QString | title,
|  | (QString,QString) | field1=qMakePair(QString(),QString()),
|  | (QString,QString) | 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<QString,QString>&, const QPair<QString,QString>&)"), target_slot)`

infoMessage | ( | KJob | job,
|  | QString | plain,
|  | QString | rich=QString()
| ) |  |  |

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

result | ( | KJob | job
| ) |  |  |

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

Signal syntax:
  `QObject.connect(source, SIGNAL("result(KJob*)"), target_slot)`

warning | ( | KJob | job,
|  | QString | plain,
|  | QString | rich=QString()
| ) |  |  |

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

## Method Documentation

__init__ | ( | self, |
|  | QObject | parent=0
| ) |  |  |

Creates a new KJob object.

Parameters:

  | parent | the parent QObject

KJob.Capabilities capabilities | ( |  | self ) |

Returns the capabilities of this job.

Returns:
  the capabilities that this job supports

See also:
  setCapabilities()

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

A human-readable error message.

This provides a translated, human-readable description of the error. Only call if error is not 0.

Subclasses should implement this to create a translated error message from the error code and error text. For example:

     if (error() == ReadFailed)
       i18n( "Could not read \"%1\"", errorText() );

Returns:
  a translated error message, providing error() is 0

QString errorText | ( |  | self ) |

Returns the error text if there has been an error.

Only call if error is not 0.

This is usually some extra data associated with the error, such as a URL. Use errorString() to get a human-readable, translated message.

Returns:
  a string to help understand the error

bool exec_ | ( |  | self ) |

Executes the job synchronously.

This will start a nested QEventLoop internally. Nested event loop can be dangerous and can have unintended side effects, you should avoid calling exec() whenever you can and use the asynchronous interface of KJob instead.

Should you indeed call this method, you need to make sure that all callers are reentrant, so that events delivered by the inner event loop don't cause non-reentrant functions to be called, which usually wreaks havoc.

Note that the event loop started by this method does not process user input events, which means your user interface will effectivly be blocked. Other events like paint or network events are still being processed. The advantage of not processing user input events is that the chance of accidental reentrancy is greatly reduced. Still you should avoid calling this function.

Returns:
  true if the job has been executed without error, false otherwise

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. Please notice that if verbosity is set to Quietly, signal result will NOT be emitted.

Returns:
  true if the operation is supported and succeeded, false otherwise

long percent | ( |  | self ) |

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

long processedAmount | ( | self, |
|  | KJob.Unit | unit
| ) |  |  |

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

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

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

You should define an (anonymous) enum of error codes, with values starting at KJob.UserDefinedError, and use those. For example,

     enum {
       InvalidFoo = UserDefinedError,
       BarNotFound
     };

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

Provides extra information about the error that cannot be determined directly from the error code. For example, a URL or filename. This string is not normally translatable.

Parameters:

  | errorText | the error text

See also:
  emitResult(), errorString(), setError()

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.

Warning: Never implement any synchronous workload in this method. This method should just trigger the job startup, not do any work itself. It is expected to be non-blocking.

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

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

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

## Enumeration Documentation

anonymous

Enumerator:

  NoError |
  KilledJobError |
  UserDefinedError |

Capability

Enumerator:

  NoCapabilities = 0x0000 |
  Killable = 0x0001 |
  Suspendable = 0x0002 |

KillVerbosity

Enumerator:

  Quietly |
  EmitResult |

Unit

Enumerator:

  Bytes |
  Files |
  Directories |