• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KDECore

KJob Class Reference

The base class for all jobs. More...

#include <kjob.h>

Inheritance diagram for KJob:
QObject KCompositeJob

List of all members.

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:

 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.

Definition at line 79 of file kjob.h.


Member Enumeration Documentation

anonymous enum
Enumerator:
NoError 
KilledJobError 
UserDefinedError 

Definition at line 229 of file kjob.h.

enum KJob::Capability
Enumerator:
NoCapabilities 
Killable 
Suspendable 

Definition at line 88 of file kjob.h.

enum KJob::KillVerbosity
Enumerator:
Quietly 
EmitResult 

Definition at line 158 of file kjob.h.

enum KJob::Unit
Enumerator:
Bytes 
Files 
Directories 

Definition at line 86 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 94 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 (  )  [protected, virtual]

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 165 of file kjob.cpp.

bool KJob::doResume (  )  [protected, virtual]

Resumes this job.

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

Definition at line 175 of file kjob.cpp.

bool KJob::doSuspend (  )  [protected, virtual]

Suspends this job.

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

Definition at line 170 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 310 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 297 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 323 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 211 of file kjob.cpp.

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:

   i18n( "Could not read\n%1" , errorText() );

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

Definition at line 221 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 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.

Definition at line 216 of file kjob.cpp.

bool KJob::exec (  ) 

Executes the job synchronously.

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

Definition at line 186 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.

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

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

Returns:
whether the job is deleted automatically after finishing.

Definition at line 344 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 99 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 104 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
unsigned long KJob::percent (  )  const

Returns the overall progress of this job.

Returns:
the overall progress of this job

Definition at line 236 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
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 226 of file kjob.cpp.

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

Definition at line 241 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().

Parameters:
errorText the error text
See also:
emitResult()

Definition at line 247 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 287 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 253 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 270 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 74 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.

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

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 231 of file kjob.cpp.

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 89 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 577 of file kjob.h.


The documentation for this class was generated from the following files:
  • kjob.h
  • kjob.cpp

KDECore

Skip menu "KDECore"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal