KJob

Search for usage in LXR

#include <KJob>

Inheritance diagram for KJob:

Public Types

enum  { NoError = 0 , KilledJobError = 1 , UserDefinedError = 100 }
 
typedef QFlags< CapabilityCapabilities
 
enum  Capability { NoCapabilities = 0x0000 , Killable = 0x0001 , Suspendable = 0x0002 }
 
enum  KillVerbosity { Quietly , EmitResult }
 
enum  Unit {
  Bytes = 0 , Files , Directories , Items ,
  UnitsCount
}
 
- Public Types inherited from QObject
typedef  QObjectList
 

Properties

Capabilities capabilities
 
int error
 
QString errorString
 
QString errorText
 
ulong percent
 
- Properties inherited from QObject
 objectName
 

Signals

void description (KJob *job, const QString &title, const QPair< QString, QString > &field1=QPair< QString, QString >(), const QPair< QString, QString > &field2=QPair< QString, QString >())
 
void finished (KJob *job)
 
void infoMessage (KJob *job, const QString &message)
 
void percentChanged (KJob *job, unsigned long percent)
 
void processedAmountChanged (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 totalAmountChanged (KJob *job, KJob::Unit unit, qulonglong amount)
 
void totalSize (KJob *job, qulonglong size)
 
void warning (KJob *job, const QString &message)
 

Public Slots

bool kill (KJob::KillVerbosity verbosity=KJob::Quietly)
 
bool resume ()
 
bool suspend ()
 

Public Member Functions

 KJob (QObject *parent=nullptr)
 
 ~KJob () override
 
Capabilities capabilities () const
 
qint64 elapsedTime () const
 
int error () const
 
virtual QString errorString () const
 
QString errorText () const
 
bool exec ()
 
bool isAutoDelete () const
 
bool isFinishedNotificationHidden () const
 
bool isStartedWithExec () const
 
bool isSuspended () const
 
unsigned long percent () const
 
Q_SCRIPTABLE qulonglong processedAmount (Unit unit) const
 
void setAutoDelete (bool autodelete)
 
void setFinishedNotificationHidden (bool hide=true)
 
void setUiDelegate (KJobUiDelegate *delegate)
 
virtual Q_SCRIPTABLE void start ()=0
 
Q_SCRIPTABLE qulonglong totalAmount (Unit unit) const
 
KJobUiDelegateuiDelegate () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
QBindable< QStringbindableObjectName ()
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo () const const
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isQuickItemType () const const
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_GADGET_EXPORT (EXPORT_MACRO)
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_MOC_INCLUDE Q_MOC_INCLUDE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qobject_cast (const QObject *object)
 
qobject_cast (QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setObjectName (QAnyStringView name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool setProperty (const char *name, QVariant &&value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds interval, Qt::TimerType timerType)
 
QThreadthread () const const
 

Protected Member Functions

KCOREADDONS_NO_EXPORT 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)
 
bool isFinished () const
 
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 setProgressUnit (Unit unit)
 
void setTotalAmount (Unit unit, qulonglong amount)
 
void startElapsedTimer ()
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Protected Attributes

std::unique_ptr< KJobPrivate > const d_ptr
 

Additional Inherited Members

- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 

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, &KJob::result, this, &SomeClass::handleResult);
job->start();
}
The base class for all jobs.
Definition kjob.h:74
void result(KJob *job)
Emitted when the job is finished (except when killed with KJob::Quietly).
virtual Q_SCRIPTABLE void start()=0
Starts the job asynchronously.
QMetaObject::Connection connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)

(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
}
}
bool exec()
Executes the job synchronously.
Definition kjob.cpp:205

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

Member Typedef Documentation

◆ Capabilities

Stores a combination of Capability values.

Definition at line 111 of file kjob.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Definition at line 274 of file kjob.h.

◆ Capability

See also
Capabilities
Enumerator
NoCapabilities 

None of the capabilities exist.

Killable 

The job can be killed.

Suspendable 

The job can be suspended.

Definition at line 101 of file kjob.h.

◆ KillVerbosity

enum KJob::KillVerbosity

Definition at line 184 of file kjob.h.

◆ Unit

enum KJob::Unit

Describes the unit used in the methods that handle reporting the job progress info.

See also
totalAmount
Enumerator
Bytes 

Directory and file sizes in bytes.

Files 

The number of files handled by the job.

Directories 

The number of directories handled by the job.

Items 

The number of items (e.g.

both directories and files) handled by the job

Since
5.72
UnitsCount 

since 5.87, used internally only, do not use.

Definition at line 87 of file kjob.h.

Property Documentation

◆ capabilities

Capabilities KJob::capabilities
read

Definition at line 80 of file kjob.h.

◆ error

int KJob::error
read

Definition at line 76 of file kjob.h.

◆ errorString

QString KJob::errorString
read

Definition at line 78 of file kjob.h.

◆ errorText

QString KJob::errorText
read

Definition at line 77 of file kjob.h.

◆ percent

ulong KJob::percent
read

Definition at line 79 of file kjob.h.

Constructor & Destructor Documentation

◆ KJob() [1/2]

KJob::KJob ( QObject * parent = nullptr)
explicit

Creates a new KJob object.

Parameters
parentthe parent QObject

Definition at line 29 of file kjob.cpp.

◆ ~KJob()

KJob::~KJob ( )
override

Destroys a KJob object.

Definition at line 43 of file kjob.cpp.

◆ KJob() [2/2]

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

Definition at line 36 of file kjob.cpp.

Member Function Documentation

◆ capabilities()

KJob::Capabilities KJob::capabilities ( ) const

Returns the capabilities of this job.

Returns
the capabilities that this job supports
See also
setCapabilities()

Definition at line 91 of file kjob.cpp.

◆ description

void KJob::description ( KJob * job,
const QString & title,
const QPair< QString, QString > & field1 = QPair< QStringQString >(),
const QPair< QString, QString > & field2 = QPair< QStringQString >() )
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
jobthe job that emitted this signal
titlethe general description of the job
field1first field (localized name and value)
field2second field (localized name and value)

◆ doKill()

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

Reimplemented in Akonadi::Job, KIO::Job, KIO::SimpleJob, and MailTransport::PrecommandJob.

Definition at line 184 of file kjob.cpp.

◆ doResume()

bool KJob::doResume ( )
protectedvirtual

Resumes this job.

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

Reimplemented in KIO::CopyJob, KIO::Job, KIO::SimpleJob, and KIO::TransferJob.

Definition at line 194 of file kjob.cpp.

◆ doSuspend()

bool KJob::doSuspend ( )
protectedvirtual

Suspends this job.

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

Reimplemented in KIO::CopyJob, KIO::Job, and KIO::SimpleJob.

Definition at line 189 of file kjob.cpp.

◆ elapsedTime()

qint64 KJob::elapsedTime ( ) const

The number of milliseconds the job has been running for.

Starting from the last start() call.

Sub-classes must call startElapsedTimer() from their start() implementation, to get elapsedTime() measurement. Otherwise this method will always return 0.

The time when paused is excluded.

Since
6.8

Definition at line 70 of file kjob.cpp.

◆ emitPercent()

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
processedAmountthe processed amount
totalAmountthe total amount
See also
percent()

Definition at line 361 of file kjob.cpp.

◆ emitResult()

void KJob::emitResult ( )
protected

Utility function to emit the result signal, and end 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 354 of file kjob.cpp.

◆ emitSpeed()

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
speedthe speed in bytes/s

Definition at line 368 of file kjob.cpp.

◆ error()

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

◆ errorString()

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());
}
QString i18n(const char *text, const TYPE &arg...)
Returns
a translated error message, providing error() is 0

Reimplemented in Akonadi::Job, and KIO::Job.

Definition at line 244 of file kjob.cpp.

◆ errorText()

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

◆ exec()

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 effectively 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 reentrance 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 205 of file kjob.cpp.

◆ finished

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.

Since 5.75 this signal is guaranteed to be emitted exactly once.

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
jobthe job that emitted this signal
See also
result

◆ infoMessage

void KJob::infoMessage ( KJob * job,
const QString & message )
signal

Emitted to display state information about this job.

Examples of message are "Resolving host", "Connecting to host...", etc.

Parameters
jobthe job that emitted this signal
messagethe info message

◆ isAutoDelete()

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

◆ isFinished()

bool KJob::isFinished ( ) const
protected

Returns if the job has been finished and has emitted the finished() signal.

Returns
if the job has been finished
See also
finished()
Since
5.75

Definition at line 274 of file kjob.cpp.

◆ isFinishedNotificationHidden()

bool KJob::isFinishedNotificationHidden ( ) const

Whether to not show a finished notification when a job's finished signal is emitted.

See also
setFinishedNotificationHidden()
Since
5.92

Definition at line 409 of file kjob.cpp.

◆ isStartedWithExec()

bool KJob::isStartedWithExec ( ) const

Returns true if this job was started with exec(), which starts a nested event-loop (with QEventLoop::ExcludeUserInputEvents, which blocks the GUI), otherwise returns false which indicates this job was started asynchronously with start().

This is useful for code that for example shows a dialog to ask the user a question, and that would be no-op since the user cannot interact with the dialog.

Since
5.95

Definition at line 415 of file kjob.cpp.

◆ isSuspended()

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

◆ kill

bool KJob::kill ( KJob::KillVerbosity verbosity = KJob::Quietly)
slot

Aborts this job.

This kills and deletes the job.

Parameters
verbosityif 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 123 of file kjob.cpp.

◆ percent()

unsigned long KJob::percent ( ) const

Returns the overall progress of this job.

Returns
the overall progress of this job

Definition at line 269 of file kjob.cpp.

◆ percentChanged

void KJob::percentChanged ( 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 progress bar very easily. (see KProgressBar).

Note that this signal is not emitted for finished jobs.

Note
This is a private signal, it shouldn't be emitted directly by subclasses of KJob, use emitPercent(), setPercent() setTotalAmount() or setProcessedAmount() instead.
Parameters
jobthe job that emitted this signal
percentthe percentage
Since
5.80

◆ processedAmount()

qulonglong KJob::processedAmount ( Unit unit) const

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

Parameters
unitthe unit of the requested amount
Returns
the processed size

Definition at line 249 of file kjob.cpp.

◆ processedAmountChanged

void KJob::processedAmountChanged ( 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.

Note
This is a private signal, it shouldn't be emitted directly by subclasses of KJob, use setProcessedAmount() instead.
Parameters
jobthe job that emitted this signal
unitthe unit of the processed amount
amountthe processed amount
Since
5.80

◆ processedSize

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

Note
This is a private signal, it shouldn't be emitted directly by subclasses of KJob, use setProcessedAmount() instead.
Parameters
jobthe job that emitted this signal
sizethe processed size

◆ result

void KJob::result ( KJob * job)
signal

Emitted when the job is finished (except when killed with KJob::Quietly).

Since 5.75 this signal is guaranteed to be emitted at most once.

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
jobthe job that emitted this signal
See also
kill

◆ resume

bool KJob::resume ( )
slot

Resumes this job.

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

Definition at line 162 of file kjob.cpp.

◆ resumed

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
jobthe job that emitted this signal

◆ setAutoDelete()

void KJob::setAutoDelete ( bool autodelete)

Sets 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, which implies that the job was created on the heap (using new). If the job is created on the stack (which isn't the typical use-case for a job) then you must set auto-delete to false, otherwise you could get a crash when the job finishes and tries to delete itself.

Note
If you set auto-delete to false then you need to kill the job manually, ideally by calling kill().
Parameters
autodeleteset to false to disable automatic deletion of the job.

Definition at line 397 of file kjob.cpp.

◆ setCapabilities()

void KJob::setCapabilities ( KJob::Capabilities capabilities)
protected

Sets the capabilities for this job.

Parameters
capabilitiesare the capabilities supported by this job
See also
capabilities()

Definition at line 199 of file kjob.cpp.

◆ setError()

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
errorCodethe error code
See also
emitResult()

Definition at line 279 of file kjob.cpp.

◆ setErrorText()

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
errorTextthe error text
See also
emitResult(), errorString(), setError()

Definition at line 285 of file kjob.cpp.

◆ setFinishedNotificationHidden()

void KJob::setFinishedNotificationHidden ( bool hide = true)

This method can be used to indicate to classes listening to signals from a job that they should ideally show a progress bar, but not a finished notification.

For example when opening a remote URL, a job will emit the progress of the download, which can be used to show a progress dialog or a Plasma notification, then when the job is done it'll emit e.g. the finished signal. Showing the user the progress dialog is useful, however the dialog/notification about the download being finished isn't of much interest, because the user can see the application that invoked the job opening the actual file that was downloaded.

Since
5.92

Definition at line 403 of file kjob.cpp.

◆ setPercent()

void KJob::setPercent ( unsigned long percentage)
protected

Sets the overall progress of the job.

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

The job takes care of this if you call setProcessedAmount in Bytes (or the unit set by setProgressUnit). This method allows you to set your own progress, as an alternative.

Parameters
percentagethe new overall progress

Definition at line 345 of file kjob.cpp.

◆ setProcessedAmount()

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
unitthe unit of the new processed amount
amountthe new processed amount

Definition at line 291 of file kjob.cpp.

◆ setProgressUnit()

void KJob::setProgressUnit ( Unit unit)
protected

Sets the unit that will be used internally to calculate the progress percentage.

The default progress unit is Bytes.

Since
5.76

Definition at line 339 of file kjob.cpp.

◆ setTotalAmount()

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
unitthe unit of the new total amount
amountthe new total amount

Definition at line 315 of file kjob.cpp.

◆ setUiDelegate()

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
delegatethe new UI delegate to use
See also
KJobUiDelegate

Definition at line 54 of file kjob.cpp.

◆ speed

void KJob::speed ( KJob * job,
unsigned long speed )
signal

Emitted to display information about the speed of this job.

Note
This is a private signal, it shouldn't be emitted directly by subclasses of KJob, use emitSpeed() instead.
Parameters
jobthe job that emitted this signal
speedthe speed in bytes/s

◆ start()

virtual Q_SCRIPTABLE 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, &ExampleJob::doWork);
}

Implemented in Akonadi::AddContactJob, Akonadi::AddEmailAddressJob, Akonadi::AgentInstanceCreateJob, Akonadi::ContactGroupExpandJob, Akonadi::Job, Akonadi::MessageQueueJob, Akonadi::OpenEmailAddressJob, Akonadi::PartFetcher, Akonadi::RecursiveItemFetchJob, KAuth::ExecuteJob, KDAV2::DavCollectionCreateJob, KDAV2::DavCollectionDeleteJob, KDAV2::DavCollectionFetchJob, KDAV2::DavCollectionModifyJob, KDAV2::DavCollectionsFetchJob, KDAV2::DavCollectionsMultiFetchJob, KDAV2::DavDiscoveryJob, KDAV2::DavItemCreateJob, KDAV2::DavItemDeleteJob, KDAV2::DavItemFetchJob, KDAV2::DavItemModifyJob, KDAV2::DavItemsFetchJob, KDAV2::DavItemsListJob, KDAV2::DavPrincipalHomeSetsFetchJob, KDAV2::DavPrincipalSearchJob, KDAV::DavCollectionDeleteJob, KDAV::DavCollectionModifyJob, KDAV::DavCollectionsFetchJob, KDAV::DavCollectionsMultiFetchJob, KDAV::DavItemCreateJob, KDAV::DavItemDeleteJob, KDAV::DavItemFetchJob, KDAV::DavItemModifyJob, KDAV::DavItemsFetchJob, KDAV::DavItemsListJob, KDAV::DavPrincipalHomeSetsFetchJob, KDAV::DavPrincipalSearchJob, KEMailClientLauncherJob, KIO::ApplicationLauncherJob, KIO::CommandLauncherJob, KIO::DeleteOrTrashJob, KIO::FavIconRequestJob, KIO::MimeTypeFinderJob, KIO::NameFinderJob, KIO::OpenFileManagerWindowJob, KIO::OpenUrlJob, KListOpenFilesJob, KTerminalLauncherJob, MailTransport::PrecommandJob, MailTransport::TransportJob, MessageComposer::AliasesExpandJob, MessageComposer::ContentJobBase, MessageComposer::DistributionListExpandJob, MessageComposer::EmailAddressResolveJob, MessageCore::AttachmentCompressJob, MessageCore::AttachmentLoadJob, and Plasma5Support::ServiceJob.

◆ startElapsedTimer()

void KJob::startElapsedTimer ( )
protected

Starts the internal elapsed time measurement timer.

Sub-classes must call startElapsedTimer() from their start() implementation, to get elapsedTime() measurement. Otherwise elapsedTimer() method will always return 0.

Since
6.8

Definition at line 76 of file kjob.cpp.

◆ suspend

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

◆ suspended

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
jobthe job that emitted this signal

◆ totalAmount()

qulonglong KJob::totalAmount ( Unit unit) const

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

Parameters
unitthe unit of the requested amount
Returns
the total size

Definition at line 259 of file kjob.cpp.

◆ totalAmountChanged

void KJob::totalAmountChanged ( 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.

Note
This is a private signal, it shouldn't be emitted directly by subclasses of KJob, use setTotalAmount() instead.
Parameters
jobthe job that emitted this signal
unitthe unit of the total amount
amountthe total amount
Since
5.80

◆ totalSize

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

Note
This is a private signal, it shouldn't be emitted directly by subclasses of KJob, use setTotalAmount() instead.
Parameters
jobthe job that emitted this signal
sizethe total size

◆ uiDelegate()

KJobUiDelegate * KJob::uiDelegate ( ) const

Retrieves the delegate attached to this job.

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

Definition at line 86 of file kjob.cpp.

◆ warning

void KJob::warning ( KJob * job,
const QString & message )
signal

Emitted to display a warning about this job.

Parameters
jobthe job that emitted this signal
messagethe warning message

Member Data Documentation

◆ d_ptr

std::unique_ptr<KJobPrivate> const KJob::d_ptr
protected

Definition at line 775 of file kjob.h.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 22 2024 12:07:13 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.