This class offers an abstraction for representing and managing time-consuming jobs in your GCF applications.Typically jobs like downloads, uploads, copy, load and save are time-consuming jobs. You might want to offer the ability to showcase their job progress and also the ability to pause, resume or even cancel such jobs. More...

#include <GCF3/Job>

Public Member Functions
	AbstractJob (const QString &kind, QObject *parent=0)

	~AbstractJob ()

bool	isStarted () const

bool	isSuspended () const

bool	isComplete () const

GCF::Result	start ()

GCF::Result	cancel ()

GCF::Result	suspend ()

GCF::Result	resume ()

GCF::Result	retry ()

Protected Member Functions
virtual GCF::Result	startJob ()=0

virtual GCF::Result	cancelJob ()

virtual GCF::Result	suspendJob ()

virtual GCF::Result	resumeJob ()

void	setTitle (const QString &title)

void	setDescription (const QString &desc)

void	setIconUrl (const QString &iconUrl)

void	setIcon (const QVariant &icon)

void	setStatus (const QString &statusMsg)

void	setProgress (int val, const QString &msg=QString())

void	setError (const QString &errMsg, bool abort=false)

void	clearError ()

void	abort (const QString &msg)

void	done ()

Properties
QString	kind

QString	title

QString	description

QVariant	icon

QString	iconUrl

QString	status

int	progress

bool	hasError

QString	error

Detailed Description

The job can be started using start(). The suspend() and resume() methods help with suspend and resume of the job. You can call the cancel() method to cancel the job entirely. Once cancelled the job can be retried using retry().

Methods kind(), title(), description(), icon(), iconUrl() status(), progress() return various attributes of the job. Status query methods isSuspended(), isStarted(), isCompleted() and isRunning() help you to determine the state of the job. If an error was encountered during the execution, the hasError() method would return true and the error() method will return a string description of the error.

Instances of this class are automatically registered with a global job-list accessible from GCF::ApplicationServices::jobs(). You can include jobs into your own instance of GCF::JobListModel if you want. In which case the job will be available in both the global list and your local list.

If you are subclassing from this class, then you will need to keep the following in mind

reimplement the startJob() method to trigger the start of your job.
optionally reimplement suspendJob() and resumeJob() to support suspension and resume of your jobs.
optionally reimplement cancelJob() to offer means to cancel the job entirely
optionally reimplement retryJob() to offer means to customize the way in which a job gets retried after a cancel.
once your job is started (after call to startJob() ), you must notify progress updates by calling setProgress() regularly. You must notify job completion by calling the done() method. Jobs can be abruptly aborted using the abort() method. You can also notify non-critical error messages using the setError() method.

Constructor & Destructor Documentation

GCF::AbstractJob::AbstractJob	(	const QString &	kind,
		QObject *	parent = `0`
	)

Constructor. It takes the kind of task as parameter. kind is like category of the task. For example kind may be "Download" or "Upload".

Parameters

kind	categorization of job.

GCF::AbstractJob::~AbstractJob ( )

Destructor.

Member Function Documentation

bool GCF::AbstractJob::isStarted ( ) const

Returns: true if job has been started otherwise returns false.

bool GCF::AbstractJob::isSuspended ( ) const

Returns: whether the job is suspended or not. Job will be in suspended state when user has suspended the job by calling the method GCF::AbstractJob::suspend().

bool GCF::AbstractJob::isComplete ( ) const

Returns: true if the job has completed otherwise returns false. Job is completed when the GCF::AbstractJob::done() method is called.

GCF::Result GCF::AbstractJob::start ( )

Starts the job. If the job is already started or completed, then returns GCF::Result with status false and error message. Otherwise starts the job by using virtual function GCF::AbstractJob::startJob().

Returns: GCF::Result which information about starting of job was successful or not.

GCF::Result GCF::AbstractJob::cancel ( )

Cancels the job. If the job is already complete or has not yet started, then returns GCF::Result with status false and error message. Otherwise cancels the job by using virtual function GCF::AbstractJob::cancelJob().

Returns: GCF::Result which contains success or failure information with error messages.

GCF::Result GCF::AbstractJob::suspend ( )

Suspends the job. If the job is already suspended, completed or has not yet started, then returns GCF::Result with status false and error message otherwise suspends the job by calling virtual function GCF::AbstractJob::suspendJob().

Returns: GCF::Result which contains success or failure information with error messages.

GCF::Result GCF::AbstractJob::resume ( )

Resumes the job. If the job is not already in suspended state, then it returns GCF::Result with status false and with proper error message. Otherwise resumes the job by calling virtual function GCF::AbstractJob::resumeJob().

Returns: GCF::Result which contains success or failure information with proper error messages.

GCF::Result GCF::AbstractJob::retry ( )

Retries to complete the job by calling virtual function GCF::AbstractJob::start() once again. If the job was not even started once, then it returns GCF::Result with status false and with proper messages.

Returns: GCF::Result which contains success or failure information with proper error messages.

GCF::AbstractJob::startJob ( )

protectedpure virtual

This is a pure virtual function. All jobs inheriting from AbstractJob should reimplement this function and start the processing of their task inside this method.

GCF::AbstractJob::cancelJob ( )

protectedvirtual

Classes inheriting from AbstractJob should reimplement this function to provide the cancelling option to their task.

GCF::AbstractJob::suspendJob ( )

protectedvirtual

Classes inheriting from AbstractJob should reimplement this function to provide the suspending option to their task.

GCF::AbstractJob::resumeJob ( )

protectedvirtual

Classes inheriting from AbstractJob should reimplement this function to provide the resume option to their task.

void GCF::AbstractJob::setTitle ( const QString & title )

protected

Sets the title of the job as title.

Parameters

title title of the job.

void GCF::AbstractJob::setDescription ( const QString & desc )

protected

Sets the description of the job as desc.

Parameters

desc	description of the job.

void GCF::AbstractJob::setIconUrl ( const QString & iconUrl )

protected

Sets the icon url of job as iconUrl.

Parameters

iconUrl icon url of the job.

void GCF::AbstractJob::setIcon ( const QVariant & icon )

protected

Sets the icon of job as icon.

Parameters

icon	icon of the job.

void GCF::AbstractJob::setStatus ( const QString & statusMsg )

protected

Sets the status message of job as statusMsg.

Parameters

statusMsg status message of the job.

void GCF::AbstractJob::setProgress	(	int	val,
		const QString &	msg = `QString()`
	)

protected

Sets the progress of job to value val and progress message 'msg'.

Parameters

val	progress value of job in percentage .
msg	progress message of job.

void GCF::AbstractJob::setError	(	const QString &	errMsg,
		bool	abort = `false`
	)

protected

Sets the error message of job as errMsg . In case if job was aborted, this method will also set the job to be complete.

Parameters

errMsg	error message of job.
abort	whether the job was aborted.

void GCF::AbstractJob::clearError ( )

protected

Clears the error message of job.

void GCF::AbstractJob::abort ( const QString & msg )

protected

Aborts the job and sets the error message as msg.

Parameters

msg	error message that needs to be set while aborting.

void GCF::AbstractJob::done ( )

protected

Sets the job as completed with progress information to 100 percent. It will also clear the errors. This method should be called when the job has been completed.

Property Documentation

QString GCF::AbstractJob::kind

read

Returns: the kind of job. Kind is the category of the task. For example kind may be "Download" or "Upload". By default it is an empty string.

QString GCF::AbstractJob::title

read

Returns: the title of job. By default it is an empty string.

QString GCF::AbstractJob::description

read

Returns: description of job. By default it is an empty string.

QVariant GCF::AbstractJob::icon

read

Returns: the icon of job. By default it returns QIcon().

QString GCF::AbstractJob::iconUrl

read

Returns: the icon url of job. By default it is an empty string.

QString GCF::AbstractJob::status

read

Returns: the status of job. By default it is an empty string.

int GCF::AbstractJob::progress

read

Returns: the current progress information of job. By default it is 0.

bool GCF::AbstractJob::hasError

read

Returns: true if the job has otherwise returns false.

QString GCF::AbstractJob::error

read

Returns: the error occurred while executing the job. By default it is an empty string.

Public Member Functions

Protected Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation