KJob Class Reference

#include <kjob.h>

Inheritance diagram for KJob:

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
	KJob (QObject *parent=0)
virtual	~KJob ()
Capabilities	capabilities () const
int	error () const
virtual QString	errorString () const
QString	errorText () const
bool	exec ()
bool	isAutoDelete () const
bool	isSuspended () const
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

Protected Member Functions
	KJob (KJobPrivate &dd, QObject *parent)
virtual bool	doKill ()
virtual bool	doResume ()
virtual bool	doSuspend ()
void	emitPercent (qulonglong processedAmount, qulonglong totalAmount)
void	emitResult ()
void	emitSpeed (unsigned long speed)
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:

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.

Definition at line 84 of file kjob.h.

Member Enumeration Documentation

anonymous enum

Enumerator
NoError
KilledJobError
UserDefinedError

Definition at line 254 of file kjob.h.

enum KJob::Capability

Enumerator
NoCapabilities
Killable
Suspendable

Definition at line 93 of file kjob.h.

enum KJob::KillVerbosity

Enumerator
Quietly
EmitResult

Definition at line 168 of file kjob.h.

enum KJob::Unit

Enumerator
Bytes
Files
Directories

Definition at line 91 of file kjob.h.

Constructor & Destructor Documentation

KJob::KJob ( QObject *  parent = 0 )

explicit

Creates a new KJob object.

Parameters

parent

the parent QObject

Definition at line 49 of file kjob.cpp.

KJob::~KJob ( )

virtual

Destroys a KJob object.

Definition at line 65 of file kjob.cpp.

KJob::KJob ( KJobPrivate &  dd, QObject *  parent  )

protected

Definition at line 57 of file kjob.cpp.

Member Function Documentation

KJob::Capabilities KJob::capabilities

(

)

const

Returns the capabilities of this job.

Returns

the capabilities that this job supports

See also

setCapabilities()

Definition at line 98 of file kjob.cpp.

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

protectedvirtual

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

Definition at line 171 of file kjob.cpp.

bool KJob::doResume ( )

protectedvirtual

Resumes this job.

Returns

true if the operation is supported and succeeded, false otherwise

Definition at line 181 of file kjob.cpp.

bool KJob::doSuspend ( )

protectedvirtual

Suspends this job.

Returns

true if the operation is supported and succeeded, false otherwise

Definition at line 176 of file kjob.cpp.

void KJob::emitPercent ( qulonglong  processedAmount, qulonglong  totalAmount  )

protected

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

Definition at line 324 of file kjob.cpp.

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

Definition at line 306 of file kjob.cpp.

void KJob::emitSpeed ( unsigned long  speed )

protected

Utility function for inherited jobs.

Emits the speed signal and starts the timer for removing that info

Parameters

speed

the speed in bytes/s

Definition at line 337 of file kjob.cpp.

int KJob::error

(

)

const

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.

Definition at line 220 of file kjob.cpp.

QString KJob::errorString ( ) const

virtual

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

Definition at line 230 of file kjob.cpp.

QString KJob::errorText

(

)

const

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

Definition at line 225 of file kjob.cpp.

bool KJob::exec

(

)

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

Definition at line 192 of file kjob.cpp.

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.

In general, to be notified of a job's completion, client code should connect to result() rather than finished(), so that kill(Quietly) is indeed quiet. However if you store a list of jobs and they might get killed silently, then you must connect to this instead of result(), to avoid dangling pointers in your list.

Parameters

job	the job that emitted this signal

See also

result

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

Returns whether this job automatically deletes itself once the job is finished.

Returns

whether the job is deleted automatically after finishing.

Definition at line 358 of file kjob.cpp.

bool KJob::isSuspended

(

)

const

Returns if the job was suspended with the suspend() call.

Returns

if the job was suspended

See also

suspend() resume()

Definition at line 103 of file kjob.cpp.

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

Returns

true if the operation is supported and succeeded, false otherwise

Definition at line 108 of file kjob.cpp.

unsigned long KJob::percent

(

)

const

Returns the overall progress of this job.

Returns

the overall progress of this job

Definition at line 245 of file kjob.cpp.

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

qulonglong KJob::processedAmount

(

Unit

unit

)

const

Returns the processed amount of a given unit for this job.

Parameters

unit	the unit of the requested amount

Returns

the processed size

Definition at line 235 of file kjob.cpp.

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

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

Resumes this job.

Returns

true if the operation is supported and succeeded, false otherwise

Definition at line 154 of file kjob.cpp.

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.

Definition at line 364 of file kjob.cpp.

void KJob::setCapabilities ( Capabilities  capabilities )

protected

Sets the capabilities for this job.

Parameters

capabilities

are the capabilities supported by this job

See also

capabilities()

Definition at line 186 of file kjob.cpp.

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

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

Definition at line 250 of file kjob.cpp.

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

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

Definition at line 256 of file kjob.cpp.

void KJob::setPercent ( unsigned long  percentage )

protected

Sets the overall progress of the job.

The percent() signal is emitted if the value changed.

Parameters

percentage

the new overall progress

Definition at line 296 of file kjob.cpp.

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

Definition at line 262 of file kjob.cpp.

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

Definition at line 279 of file kjob.cpp.

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

Definition at line 78 of file kjob.cpp.

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.

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 KJob::suspend ( )

slot

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

Definition at line 137 of file kjob.cpp.

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

qulonglong KJob::totalAmount

(

Unit

unit

)

const

Returns the total amount of a given unit for this job.

Parameters

unit	the unit of the requested amount

Returns

the total size

Definition at line 240 of file kjob.cpp.

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

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

Retrieves the delegate attached to this job.

Returns

the delegate attached to this job, or 0 if there's no such delegate

Definition at line 93 of file kjob.cpp.

void KJob::warning ( KJob *  job, const QString &  plain, const QString &  rich = QString()  )

signal

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

Definition at line 627 of file kjob.h.

---

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

• kjob.h
• kjob.cpp