summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetetask.h
diff options
context:
space:
mode:
Diffstat (limited to 'kopete/libkopete/kopetetask.h')
-rw-r--r--kopete/libkopete/kopetetask.h162
1 files changed, 162 insertions, 0 deletions
diff --git a/kopete/libkopete/kopetetask.h b/kopete/libkopete/kopetetask.h
new file mode 100644
index 00000000..115e1ebe
--- /dev/null
+++ b/kopete/libkopete/kopetetask.h
@@ -0,0 +1,162 @@
+/*
+ kopetetask.h - Kopete Task
+
+ Copyright (c) 2004 by Richard Smith <kde@metafoo.co.uk>
+ Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
+
+ *************************************************************************
+ * *
+ * This library is free software; you can redistribute it and/or *
+ * modify it under the terms of the GNU Lesser General Public *
+ * License as published by the Free Software Foundation; either *
+ * version 2 of the License, or (at your option) any later version. *
+ * *
+ *************************************************************************
+*/
+
+#ifndef KOPETETASK_H
+#define KOPETETASK_H
+
+#include <qobject.h>
+#include <kdemacros.h>
+
+namespace Kopete
+{
+
+/**
+ * The base class for all tasks.
+ * For most tasks created in Kopete, the code looks like
+ *
+ * \code
+ * Kopete::Task *task = someobject->someoperation( some parameters );
+ * connect( task, SIGNAL( result( Kopete::Task * ) ),
+ * this, SLOT( slotResult( Kopete::Task * ) ) );
+ * \endcode
+ * (other connects, specific to the job)
+ *
+ * And slotResult is usually at least:
+ *
+ * \code
+ * if ( !task->succeeded() )
+ * Kopete::UI::Global::showTaskError( task );
+ * \endcode
+ *
+ * Much of the ideas (and some of the documentation and function names) for this
+ * class come from KIO::Job.
+ * @author Richard Smith <kde@metafoo.co.uk>
+ */
+class Task : public QObject
+{
+ Q_OBJECT
+
+protected:
+ Task();
+public:
+ ~Task();
+
+ /**
+ * Returns whether the task completed successfully.
+ * Only call this method from the slot connected to result().
+ * @return if the task succeeded, returns true, otherwise returns false.
+ */
+ bool succeeded() const;
+ /**
+ * 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.
+ *
+ * Use this to display the error yourself, but for a dialog box
+ * use Kopete::UI::Global::showTaskError. Do not call it if succeeded()
+ * returns true.
+ * @return the error message and if there is no error, a message
+ * telling the user that the app is broken, so check with
+ * succeeded() whether there is an error.
+ */
+ const QString &errorString() const;
+
+ /** Flags for the abort() function */
+ enum AbortFlags { AbortNormal = 0, AbortEmitResult = 1 };
+public slots:
+ /**
+ * Abort this task.
+ * This aborts all subtasks and deletes the task.
+ *
+ * @param flags a combination of flags from AbortFlags. If AbortEmitResult is
+ * set, Job will emit the result signal. AbortEmitResult is removed
+ * from the flags passed to the abort function of subtasks.
+ */
+ virtual void abort( int flags = AbortNormal );
+
+signals:
+ /**
+ * Emitted when the task is finished, in any case (completed, canceled,
+ * failed...). Use error() to find the result.
+ * @param task the task that emitted this signal
+ */
+ void result( Kopete::Task *task );
+ /**
+ * Emitted to display status information about this task.
+ * Examples of messages are:
+ * "Removing ICQ contact Joe from server-side list",
+ * "Loading account plugin", etc.
+ * @param task the task that emitted this signal
+ * @param message the info message
+ */
+ void statusMessage( Kopete::Task *task, const QString &message );
+
+protected:
+ /**
+ * Add a task that has to be completed before a result is emitted. This
+ * obviously should not be called after the finish signal is emitted by
+ * the subtask.
+ *
+ * @param task the subtask to add
+ */
+ virtual void addSubtask( Task *task );
+
+ enum RemoveSubtaskIfLast { IfLastDoNothing, IfLastEmitResult };
+ /**
+ * Mark a sub job as being done. If it's the last to
+ * wait on the job will emit a result - jobs with
+ * two steps might want to override slotResult
+ * in order to avoid calling this method.
+ *
+ * @param task the subjob to add
+ * @param actionIfLast the action to take if this is the last subtask.
+ * If set to IfLastEmitResult, the error information from @p task
+ * will be copied to this object, and emitResult() will be called.
+ */
+ virtual void removeSubtask( Task *task, RemoveSubtaskIfLast actionIfLast = IfLastEmitResult );
+
+ enum Result { ResultFailed = 0, ResultSucceeded = 1 };
+ /**
+ * Utility function to emit the result signal, and suicide this job.
+ * Sets the stored result and error message to @p result and @p errorMessage.
+ * You should call this instead of emitting the result() signal yourself.
+ */
+ void emitResult( Result result = ResultSucceeded, const QString &errorMessage = QString::null );
+
+protected slots:
+ /**
+ * Called whenever a subtask finishes.
+ * The default implementation checks for errors and propagates
+ * them to this task, then calls removeSubtask().
+ * Override if you want to provide a different @p actionIfLast to
+ * removeSubtask, or want to perform some other processing in response
+ * to a subtask finishing
+ * @param task the subtask that finished
+ * @see result()
+ */
+ virtual void slotResult( Kopete::Task *task );
+
+private:
+ class Private;
+ Private *d;
+};
+
+}
+
+#endif
+
+// vim: set noet ts=4 sts=4 sw=4: