KJob

#include <KJob>

Inheritance diagram for KJob:

[legend]

Public Types
enum	{ NoError = 0, KilledJobError = 1, UserDefinedError = 100 }

typedef QFlags< Capability >	Capabilities

enum	Capability { NoCapabilities = 0x0000, Killable = 0x0001, Suspendable = 0x0002 }

enum	KillVerbosity { Quietly, EmitResult }

enum	Unit { Bytes = 0, Files, Directories, Items, UnitsCount }

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 &plain, const QString &rich=QString())

void	percent (KJob *job, unsigned long percent)

void	percentChanged (KJob *job, unsigned long percent)

void	processedAmount (KJob *job, KJob::Unit unit, qulonglong amount)

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	totalAmount (KJob *job, KJob::Unit unit, qulonglong amount)

void	totalAmountChanged (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 Slots
bool	kill (KillVerbosity verbosity=Quietly)

bool	resume ()

bool	suspend ()

Public Member Functions
	KJob (QObject *parent=nullptr)

	~KJob () override

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

KJobUiDelegate *	uiDelegate () const

Public Member Functions inherited from QObject
	QObject (QObject *parent)

bool	blockSignals (bool block)

const QObjectList &	children () 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 ()

void	dumpObjectInfo () const const

void	dumpObjectTree ()

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, 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

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_DISABLE_COPY (Class)

	Q_DISABLE_COPY_MOVE (Class)

	Q_DISABLE_MOVE (Class)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	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

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

T	qobject_cast (const QObject *object)

T	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	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () 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)

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

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Protected Attributes
const std::unique_ptr< KJobPrivate >	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)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Public Attributes inherited from QObject
typedef	QObjectList

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

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

Member Typedef Documentation

◆ Capabilities

typedef QFlags< Capability > KJob::Capabilities

Stores a combination of Capability values.

Definition at line 111 of file kjob.h.

Member Enumeration Documentation

◆ Capability

enum KJob::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.

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

Constructor & Destructor Documentation

◆ KJob()

KJob::KJob ( QObject * parent = nullptr )

explicit

Creates a new KJob object.

Parameters

parent the parent QObject

Definition at line 28 of file kjob.cpp.

◆ ~KJob()

KJob::~KJob ( )

override

Destroys a KJob object.

Definition at line 42 of file kjob.cpp.

Member Function Documentation

◆ capabilities()

Capabilities KJob::capabilities ( ) const

Returns the capabilities of this job.

Returns: the capabilities that this job supports

See also: setCapabilities()

◆ description

void KJob::description	(	KJob *	job,
		const QString &	title,
		const QPair< QString, QString > &	field1 = `QPair< QString, QString >()`,
		const QPair< QString, QString > &	field2 = `QPair< 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)

◆ 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 KIO::Job, KIO::SimpleJob, MailTransport::PrecommandJob, and Akonadi::Job.

Definition at line 156 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 166 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 161 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

processedAmount	the processed amount
totalAmount	the total amount

See also: percent()

Definition at line 342 of file kjob.cpp.

◆ emitResult()

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

speed the speed in bytes/s

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

◆ errorString()

virtual 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

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

◆ 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

◆ 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 177 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

job	the job that emitted this signal

See also: result

◆ infoMessage

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 – do not use, it's ignored

◆ 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 381 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 246 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 399 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 405 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 79 of file kjob.cpp.

◆ kill

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

◆ percent() [1/2]

unsigned long KJob::percent ( ) const

Returns the overall progress of this job.

Returns: the overall progress of this job

◆ percent [2/2]

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.

Note: This is a private signal, it shouldn'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

Deprecated:: since 5.80, use the KJob::percentChanged(KJob *, unsigned long) signal instead.

◆ 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

job	the job that emitted this signal
percent	the percentage

Since: 5.80

◆ processedAmount [1/2]

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.

Note: This is a private signal, it shouldn'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

Deprecated:: since 5.80, use the KJob::processedAmountChanged(KJob *, KJob::Unit, qulonglong) signal instead

◆ processedAmount() [2/2]

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

job	the job that emitted this signal
unit	the unit of the processed amount
amount	the 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

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

job	the 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 141 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

job	the 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

autodelete set to false to disable automatic deletion of the job.

Definition at line 387 of file kjob.cpp.

◆ setCapabilities()

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

protected

Sets the capabilities for this job.

Parameters

capabilities are the capabilities supported by this job

See also: capabilities()

Definition at line 171 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

errorCode the error code

See also: emitResult()

Definition at line 251 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

errorText the error text

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

Definition at line 257 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 393 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

percentage the new overall progress

Definition at line 323 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

unit	the unit of the new processed amount
amount	the new processed amount

Definition at line 263 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 317 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

unit	the unit of the new total amount
amount	the new total amount

Definition at line 290 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

delegate the new UI delegate to use

See also: KJobUiDelegate

Definition at line 53 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

job	the job that emitted this signal
speed	the 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 KListOpenFilesJob, KNSCore::KPackageJob, Akonadi::MessageQueueJob, KAuth::ExecuteJob, Plasma::ServiceJob, MessageComposer::AliasesExpandJob, MessageCore::AttachmentCompressJob, MessageCore::AttachmentLoadJob, MessageComposer::ContentJobBase, MessageComposer::DistributionListExpandJob, MessageComposer::EmailAddressResolveJob, 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, KIO::ApplicationLauncherJob, KIO::CommandLauncherJob, KIO::DeleteOrTrashJob, KIO::FavIconRequestJob, KEMailClientLauncherJob, KTerminalLauncherJob, KIO::MimeTypeFinderJob, KIO::NameFinderJob, KIO::OpenFileManagerWindowJob, KIO::OpenUrlJob, KDAV::DavCollectionDeleteJob, KDAV::DavCollectionModifyJob, KDAV::DavCollectionsFetchJob, KDAV::DavCollectionsMultiFetchJob, KDAV::DavItemCreateJob, KDAV::DavItemDeleteJob, KDAV::DavItemFetchJob, KDAV::DavItemModifyJob, KDAV::DavItemsFetchJob, KDAV::DavItemsListJob, KDAV::DavPrincipalHomeSetsFetchJob, KDAV::DavPrincipalSearchJob, MailTransport::PrecommandJob, MailTransport::TransportJob, Akonadi::AgentInstanceCreateJob, Akonadi::Job, Akonadi::PartFetcher, Akonadi::RecursiveItemFetchJob, Akonadi::AddContactJob, Akonadi::AddEmailAddressJob, Akonadi::ContactGroupExpandJob, and Akonadi::OpenEmailAddressJob.

◆ 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 126 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

job	the job that emitted this signal

◆ totalAmount [1/2]

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.

Note: This is a private signal, it shouldn'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

Deprecated:: since 5.80, use the KJob::totalAmountChanged(KJob *, KJob::Unit, qulonglong) signal instead

◆ totalAmount() [2/2]

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.

◆ 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

job	the job that emitted this signal
unit	the unit of the total amount
amount	the 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

job	the job that emitted this signal
size	the 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 69 of file kjob.cpp.

◆ warning

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

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

KJob::start

virtual Q_SCRIPTABLE void start()=0

Starts the job asynchronously.

KJob::result

void result(KJob *job)

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

QTimer::singleShot

singleShot

QObject::connect

QMetaObject::Connection connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)

start

Q_SCRIPTABLE Q_NOREPLY void start()

i18n

QString i18n(const char *text, const TYPE &arg...)

KJob

Definition: kjob.h:73

KJob::exec

bool exec()

Executes the job synchronously.

Definition: kjob.cpp:177

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KCoreAddons

KJob

Public Types

Properties

Signals

Public Slots

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Capabilities

Member Enumeration Documentation

◆ Capability

◆ Unit

Constructor & Destructor Documentation

◆ KJob()

◆ ~KJob()

Member Function Documentation

◆ capabilities()

◆ description

◆ doKill()

◆ doResume()

◆ doSuspend()

◆ emitPercent()

◆ emitResult()

◆ emitSpeed()

◆ error()

◆ errorString()

◆ errorText()

◆ exec()

◆ finished

◆ infoMessage

◆ isAutoDelete()

◆ isFinished()

◆ isFinishedNotificationHidden()

◆ isStartedWithExec()

◆ isSuspended()

◆ kill

◆ percent() [1/2]

◆ percent [2/2]

◆ percentChanged

◆ processedAmount [1/2]

◆ processedAmount() [2/2]

◆ processedAmountChanged

◆ processedSize

◆ result

◆ resume

◆ resumed

◆ setAutoDelete()

◆ setCapabilities()

◆ setError()

◆ setErrorText()

◆ setFinishedNotificationHidden()

◆ setPercent()

◆ setProcessedAmount()

◆ setProgressUnit()

◆ setTotalAmount()

◆ setUiDelegate()

◆ speed

◆ start()

◆ suspend

◆ suspended

◆ totalAmount [1/2]

◆ totalAmount() [2/2]

◆ totalAmountChanged

◆ totalSize

◆ uiDelegate()

◆ warning