An interface through which you can communicate with a task. Qtilities::Core::Task is a ready to use implementation of this interface. More...
#include <ITask.h>
Public Types | |
enum | SubTaskPerformanceIndication { SubTaskNoPerformanceIndication = 0, SubTaskTimeFromTaskStart = 1 } |
Indicates how sub tasks are timed. More... | |
enum | TaskBusyState { TaskBusyClean = 0, TaskBusyWithWarnings = 1, TaskBusyWithErrors = 2 } |
The possible busy states of the task. More... | |
enum | TaskRemoveAction { TaskDeleteWhenRemoved = 0, TaskHideWhenRemoved = 1 } |
Indicates what should happen to the task when the user click's on the "Remove Task" button in a Qtilities::CoreGui::SingleTaskWidget. The "Stop Task" becomes the "Remove Task" button when the task was stopped or completed. More... | |
enum | TaskResult { TaskNoResult = 0, TaskSuccessful = 1, TaskSuccessfulWithWarnings = 2, TaskSuccessfulWithErrors = 3, TaskResultFromBusyStateFailOnError = 4, TaskResultFromBusyStateSuccessOnError = 5, TaskFailed = 6 } |
The possible results of a completed task. More... | |
enum | TaskState { TaskNotStarted = 1, TaskBusy = 2, TaskPaused = 4, TaskStopped = 8, TaskCompleted = 16, TaskIdle = TaskNotStarted | TaskCompleted | TaskStopped } |
The possible states in which a task might find itself. More... | |
enum | TaskStopAction { TaskDeleteWhenStopped = 0, TaskHideWhenStopped = 1, TaskDoNothingWhenStopped = 2 } |
Indicates what should happen to the task when the user stops it in a Qtilities::CoreGui::SingleTaskWidget. More... | |
enum | TaskStopConfirmation { TaskStopConfirmationNone = 0, TaskStopConfirmationMsgBox = 1 } |
Indicates if an confirmation message is required when an user stops the task in a Qtilities::CoreGui::SingleTaskWidget. More... | |
enum | TaskType { TaskLocal = 0, TaskGlobal = 1 } |
The possible types of tasks. More... |
Public Member Functions | |
virtual TaskBusyState | busyState () const =0 |
The busy state of the task. | |
virtual void | busyStateChanged (TaskBusyState new_busy_state, TaskBusyState old_busy_state) const =0 |
Signal emitted when the busy state of the task changes. | |
virtual bool | canPause () const |
Indicates if users can pause the task. | |
virtual void | canPauseChanged (bool new_value) const =0 |
Signal emitted when a task's ability to be paused changed. | |
virtual bool | canStart () const |
Indicates if users can start the task. | |
virtual void | canStartChanged (bool new_value) const =0 |
Signal emitted when a task's ability to be started changed. | |
virtual bool | canStop () const |
Indicates if users can stop the task. | |
virtual void | canStopChanged (bool new_value) const =0 |
Signal emitted when a task's ability to be stopped changed. | |
virtual void | clearLog () |
Clears the task's log. | |
virtual bool | clearLogOnStart () const |
When true, the task's log will be cleared everytime the task is started. | |
virtual int | currentProgress () const |
Returns the number of subtasks completed. | |
virtual AbstractLoggerEngine * | customLoggerEngine () const |
Returns the custom logger engine used by this task. | |
virtual void | displayedNameChanged (const QString &displayed_name) const =0 |
Signal emitted when the task's displayed name changes. | |
virtual QString | displayName () const |
Returns the display name for the task. The display name will typically be set just before emitting taskStarted() and contain a little bit more information than taskName(). | |
virtual int | elapsedTime () const =0 |
Returns the elapsed time in miliseconds of the last time the task was run. | |
bool | elapsedTimeChangedNotificationsEnabled () const |
Indicates if elapsed time changed notifications through taskElapsedTimeChanged() are enabled. | |
virtual QString | elapsedTimeString (int msec=-1, const QString &format="hh:mm:ss.zzz") const |
Returns the elapsed time of the task as a string. | |
int | getWidgetLoggerEngineDisplaysFlag () const |
Gets the (int) WidgetLoggerEngine::MessageDisplaysFlag used when assigning logger engines to tasks. | |
virtual QStringList | lastErrorMessages (int count=-1) const =0 |
Returns the last error logged in the task while it was busy. | |
virtual int | lastErrorMessagesStackSize () const =0 |
Gets the last error logged stack size. | |
virtual void | logError (const QString &message)=0 |
Convenience function to log an error in the task log. | |
virtual AbstractLoggerEngine * | loggerEngine () const |
Returns a reference to the logger engine logging activities of this task. When loggingEnabled() is false, this function will always return 0. | |
virtual bool | loggingEnabled () const |
Indicates if the activities of this task is logged. | |
virtual void | logMessage (const QString &message, Logger::MessageType type=Logger::Info)=0 |
Logs a message to this task. | |
virtual void | logWarning (const QString &message)=0 |
Convenience function to log a warning in the task log. | |
virtual void | newMessageLogged (const QString &message, Logger::MessageType) const =0 |
Signal emitted when the new messages are logged in this task. | |
virtual int | numberOfSubTasks () const |
Returns the number of subtasks associated with the task. | |
virtual ITask * | parentTask () const =0 |
The parent task of this task. | |
virtual void | pause () |
Pauses the task from the user interface. | |
virtual void | removeCustomLoggerEngine () |
Removes the current custom logger engine from this task. | |
virtual void | removeParentTask ()=0 |
Removes the parent task of this task. | |
virtual TaskResult | result () const =0 |
The result of the task. | |
virtual void | resume () |
Resumes the task after it has been paused. | |
virtual void | setClearLogOnStart (bool clear_log_on_start=true) const =0 |
Sets if the log must be cleared when the task is started. | |
virtual void | setCustomLoggerEngine (AbstractLoggerEngine *engine, bool use_only_this_engine=false) |
Sets a custom logger engine to be used by this task. | |
virtual void | setDisplayName (const QString &display_name)=0 |
Sets the display name of the task. | |
virtual void | setLastErrorMessagesStackSize (int size)=0 |
Sets the last error logged stack size. | |
virtual void | setLastRunTime (int msec)=0 |
This function allows you to overwrite the last run time of the task. | |
virtual void | setLogContext (Logger::MessageContextFlags message_context)=0 |
Sets the default message logging context flags of this task. | |
virtual void | setLoggerEngine (AbstractLoggerEngine *engine) |
Sets the logger engine to be used by this task. | |
virtual void | setParentTask (ITask *parent_task)=0 |
Sets the parent task of this task. | |
virtual void | setSubTaskPerformanceIndication (SubTaskPerformanceIndication performance_indication)=0 |
Sets what performance measures are used for sub tasks. | |
virtual void | setTaskRemoveAction (TaskRemoveAction task_remove_action)=0 |
Sets the task's remove action. | |
virtual void | setTaskStopAction (TaskStopAction task_stop_action)=0 |
Sets the task's stop action. | |
virtual void | setTaskStopConfirmation (TaskStopConfirmation task_stop_confirmation)=0 |
Sets the task's stop configuration action. | |
virtual void | setTaskType (TaskType task_type)=0 |
Sets the task type. | |
void | setWidgetLoggerEngineDisplaysFlag (int message_display_flags) |
Sets the (int) WidgetLoggerEngine::MessageDisplaysFlag used when assigning logger engines to tasks. | |
virtual void | start () |
Starts the task from the user interface. | |
virtual TaskState | state () const =0 |
The state of the task. | |
virtual void | stateChanged (TaskState new_state, TaskState old_state) const =0 |
Signal emitted when the task's state changes. | |
virtual void | stop () |
Stops the task from the user interface. | |
virtual void | subTaskCompleted (int number_task_completed=1, const QString &message=QString(), Logger::MessageType type=Logger::Info) const =0 |
Signal emitted when subtasks are completed in order to show the correct progress information. | |
virtual SubTaskPerformanceIndication | subTaskPerformanceIndication () const |
Gets what performance measures are used for sub tasks. | |
virtual void | taskAboutToComplete () const =0 |
Signal emitted when the task is about to be completed. | |
virtual void | taskAboutToPause () const =0 |
Signal emitted when the task is about to be paused. | |
virtual void | taskAboutToResume () const =0 |
Signal emitted when the task is about to be resumed from a paused state. | |
virtual void | taskAboutToStart () const =0 |
Signal emitted when the task is about to be started. | |
virtual void | taskAboutToStop () const =0 |
Signal emitted when the task is about to be stopped. | |
virtual void | taskCompleted (ITask::TaskResult result, const QString &message=QString(), Logger::MessageType type=Logger::Info) const =0 |
Signal emitted when the task started. | |
virtual void | taskElapsedTimeChanged (int msec) const =0 |
Signal emitted when the task's elapsed time changes. | |
int | taskID () const |
The ID of this task. | |
virtual QString | taskName () const =0 |
The name of the task. | |
virtual void | taskPaused () const =0 |
Signal emitted when the task is paused. | |
virtual TaskRemoveAction | taskRemoveAction () const |
Indicates what should happen to the task when the user click's on the "Remove Task" button in a Qtilities::CoreGui::SingleTaskWidget. | |
virtual void | taskResumed () const =0 |
Signal emitted when the task is resumed after it was paused. | |
virtual void | taskStarted (int expected_subtasks=-1, const QString &message=QString(), Logger::MessageType type=Logger::Info) const =0 |
Signal emitted when the task started. | |
virtual TaskStopAction | taskStopAction () const |
Indicates what should happen to the task when the user click's on the "Stop Task" button in a Qtilities::CoreGui::SingleTaskWidget. | |
virtual TaskStopConfirmation | taskStopConfirmation () const |
Indicates what should happen to the task when the user click's on the "Stop Task" button in a Qtilities::CoreGui::SingleTaskWidget. | |
virtual void | taskStopped () const =0 |
Signal emitted when the task is stopped during execution. | |
virtual void | taskSubTaskAboutToComplete () const =0 |
Signal emitted when a sub task is about to be completed. | |
virtual TaskType | taskType () const |
The type of this task. | |
virtual void | taskTypeChanged (TaskType new_task_type) const =0 |
Signal emitted when the task's type changes. | |
void | toggleElapsedTimeChangedNotifications (bool is_enabled) |
Enables elapsed time changed notifications through taskElapsedTimeChanged(). | |
Public Member Functions inherited from Qtilities::Core::Interfaces::IObjectBase | |
virtual QObject * | objectBase ()=0 |
Returns the QObject* base of the interface. | |
virtual const QObject * | objectBase () const =0 |
Returns a const QObject* base of the interface. | |
QString | objectOriginID () const |
Allows interfaces to provide some sort of source identification. | |
void | setObjectOriginID (const QString &object_origin_id) |
Allows setting of the object source ID of this interface implementation. |
Static Public Member Functions | |
static void | logMessageToTask (const QString &message, ITask *task=0, Logger::MessageType type=Logger::Info) |
Message logging function which directs messages aimed for a task to the task if the task exists, or to the logger as system wide messages if the task does not exist. | |
static void | logPriorityMessageToTask (const QString &message, ITask *task=0, Logger::MessageType type=Logger::Info) |
Message logging function which logs the message as a priority message and directs messages aimed for a task to the task if the task exists, or to the logger as system wide messages if the task does not exist. |
Friends | |
class | Qtilities::Core::TaskManager |
An interface through which you can communicate with a task. Qtilities::Core::Task is a ready to use implementation of this interface.
See the Tasking article for more information on tasking.
This class was added in Qtilities v1.0.
Indicates how sub tasks are timed.
The possible busy states of the task.
Indicates what should happen to the task when the user click's on the "Remove Task" button in a Qtilities::CoreGui::SingleTaskWidget. The "Stop Task" becomes the "Remove Task" button when the task was stopped or completed.
TaskDeleteWhenRemoved |
Delete the task when the "Remove Task" button is pressed. |
TaskHideWhenRemoved |
Hide the task's Qtilities::CoreGui::SingleTaskWidget when the "Remove Task" button is pressed. |
The possible results of a completed task.
The possible states in which a task might find itself.
Indicates what should happen to the task when the user stops it in a Qtilities::CoreGui::SingleTaskWidget.
TaskDeleteWhenStopped |
Delete the task when it is stopped while it was running. |
TaskHideWhenStopped |
Hide the task's Qtilities::CoreGui::SingleTaskWidget when the task when it is stopped while it was running. |
TaskDoNothingWhenStopped |
Do nothing when it is stopped. This will give the user the chance to review the task log. |
Indicates if an confirmation message is required when an user stops the task in a Qtilities::CoreGui::SingleTaskWidget.
The possible types of tasks.
TaskLocal |
A local task, thus its progress should not be shown in Qtilities::CoreGui::TaskSummaryWidget. |
TaskGlobal |
A global task, thus its progress should be shown in Qtilities::CoreGui::TaskSummaryWidget. |
|
pure virtual |
|
pure virtual |
Signal emitted when the busy state of the task changes.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when a task's ability to be paused changed.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when a task's ability to be started changed.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when a task's ability to be stopped changed.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Returns the number of subtasks completed.
Default implementation returns 0, thus no sub tasks.
Reimplemented in Qtilities::Core::Task.
|
inlinevirtual |
Returns the custom logger engine used by this task.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task's displayed name changes.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Returns the display name for the task. The display name will typically be set just before emitting taskStarted() and contain a little bit more information than taskName().
The default implementation will just return the task name for the task. However in many cases its possible to provide a more detailed name to display in any task widget.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Returns the elapsed time in miliseconds of the last time the task was run.
When a task was paused, the timer will continue to time for the duration that the task was paused.
When the task has not been run 0 is returned. When busy the function will return the elapsed time when the function is called. When the task is completed, the function will return the total time the task took to complete.
This function was added in Qtilities v1.1.
Implemented in Qtilities::Core::Task.
|
inline |
Indicates if elapsed time changed notifications through taskElapsedTimeChanged() are enabled.
Disabled by default.
|
inlinevirtual |
Returns the elapsed time of the task as a string.
msec | The time in miliseconds to format. When -1 (default) the current elapsed time of the task is used. |
format | The format to use, see QTime::toString(const QString& format) for details. |
This function was added in Qtilities v1.1.
|
inline |
Gets the (int) WidgetLoggerEngine::MessageDisplaysFlag used when assigning logger engines to tasks.
The default is WidgetLoggerEngine::DefaultDisplays.
This function was added in Qtilities v1.2.
|
pure virtual |
Returns the last error logged in the task while it was busy.
count | The number of messages to return. Note that the maximum returnable number of messages are defined by errorMessageStackSize(). Also, if the number of error messages that were logged at the time this function is called is less than the count specified, only the number of currently logged messages will be returned. When -1 (default) all messages in the stack are returned. |
This function was added in Qtilities v1.4.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Gets the last error logged stack size.
The default is 10.
This function was added in Qtilities v1.4.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Returns a reference to the logger engine logging activities of this task. When loggingEnabled() is false, this function will always return 0.
Reimplemented in Qtilities::Core::Task.
|
inlinevirtual |
Indicates if the activities of this task is logged.
False by default.
Reimplemented in Qtilities::Core::Task.
|
inlinestatic |
Message logging function which directs messages aimed for a task to the task if the task exists, or to the logger as system wide messages if the task does not exist.
In some cases a function gets a task to log its messages to as a parameter. There is off course the possibility that whatever is calling the function does not pass a valid task. In those cases it is still desirable to log the messages of the function somewhere.
Thus function automatically directs messages to the correct place. For example:
If no task was passed to the function, the messages will be logged as system wide messages to the logger. If a valid task was received the message will be logged to the task.
This function was added in Qtilities v1.1.
|
inlinestatic |
Message logging function which logs the message as a priority message and directs messages aimed for a task to the task if the task exists, or to the logger as system wide messages if the task does not exist.
This function is the same as logMessage(), except that the message is also logged as a priority message. This is usefull in some scenarios, for example: When loading a project and the loading fails, we want to log this message as a priority message in order to appear in the QtilitiesMainWindow priority message area, but we also want to capture the message in the task log.
For example:
This function was added in Qtilities v1.1.
|
pure virtual |
Signal emitted when the new messages are logged in this task.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Returns the number of subtasks associated with the task.
Default implementation returns -1, thus no sub tasks.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
The parent task of this task.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Pauses the task from the user interface.
In Qtilities::Core::Task, the task will emit pauseTaskRequest() which must be handled by the process represented by Task. Qtilities::Core::QtilitiesProcess is a good example of this.
The task can be resumed through resume().
The default implementation of ITask does nothing.
Reimplemented in Qtilities::Core::Task.
|
inlinevirtual |
Removes the current custom logger engine from this task.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Removes the parent task of this task.
Implemented in Qtilities::Core::Task.
|
pure virtual |
|
inlinevirtual |
Resumes the task after it has been paused.
In Qtilities::Core::Task, the task will emit resumeTaskRequest() which must be handled by the process represented by Task. Qtilities::Core::QtilitiesProcess is a good example of this.
The default implementation of ITask does nothing.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Sets if the log must be cleared when the task is started.
True by default.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Sets a custom logger engine to be used by this task.
The task will not take ownership of the custom logger engine.
use_only_this_engine | When true, the task's own logger engine will be deleted and only the custom engine will be used to log messages. |
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Sets the last error logged stack size.
size | The new size of the last error messages stack. |
This function was added in Qtilities v1.4.
Implemented in Qtilities::Core::Task.
|
pure virtual |
This function allows you to overwrite the last run time of the task.
setElapsedTime This is usefull when you need to restore the state of a task for example.
msec | The new elapsed time in msec. |
This function was added in Qtilities v1.2.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Sets the default message logging context flags of this task.
Default is Logger::EngineSpecificMessages.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Sets the logger engine to be used by this task.
When logging is enabled this function will be called automatically by Qtilities::CoreGui::TaskManagerGui when the task is registered in the global object pool.
If you want this task's messages to be logged in a different logger engine you should call setCustomLoggerEngine(). An example where this is usefull is when you want to log the messages of a task in the log of another task. In that case, call setCustomLoggerEngine() with the loggerEngine() of the task where the messages should be logged.
The task will take ownership of the logger engine. This function can only be called once. Thus, if the task already has a logger engine calling this function will do nothing. To use a custom logger engine, see setCustomLoggerEngine().
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Sets the parent task of this task.
Allows you to make this task a subtask of another task. What this basically means is that messages from this task will be logged to the parent task and the parent task's busy state will also track the busy state of this task.
If you don't want the busy state to be tracked (thus only want to get the messages of this task in the log of a different task, use setCustomLoggerEngine() instead.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Sets what performance measures are used for sub tasks.
This function was added in Qtilities v1.1.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Sets the task's stop configuration action.
This function was added in Qtilities v1.3.
Implemented in Qtilities::Core::Task.
|
inline |
Sets the (int) WidgetLoggerEngine::MessageDisplaysFlag used when assigning logger engines to tasks.
This function was added in Qtilities v1.2.
|
inlinevirtual |
Starts the task from the user interface.
The slot called when the user starts the task from it's Qtilities::CoreGui::SingleTaskWidget. Programmatically, you should use startTask() instead of start(). In Qtilities::Core::Task, the task will emit startTaskRequest() which must be handled by the task represented by Task. Qtilities::Core::QtilitiesProcess is a good example of this.
The default implementation of ITask does nothing.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
|
pure virtual |
Signal emitted when the task's state changes.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Stops the task from the user interface.
In Qtilities::Core::Task, the task will emit stopTaskRequest() which must be handled by the process represented by Task. Qtilities::Core::QtilitiesProcess is a good example of this.
The default implementation of ITask does nothing.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when subtasks are completed in order to show the correct progress information.
number_task_completed | The number of subtasks completed, 1 by default. |
subtask_message | A message which describes the subtask(s) completed. |
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Gets what performance measures are used for sub tasks.
Default is SubTaskTimeFromTaskStart.
This function was added in Qtilities v1.1.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is about to be completed.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is about to be paused.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is about to be resumed from a paused state.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is about to be started.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is about to be stopped.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task started.
result | The result of the task. |
message | A message which describes the completion of the task. |
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task's elapsed time changes.
This function is only emitted while the task is busy, and when elapsed time change notifications are enabled. See toggleElapsedTimeChangedNotifications(). When enabled, it will emit every second while the task is busy.
The | elapsed time in miliseconds of the task at the time that the signal was emitted. You can format the received msec value to a string using elapsedTimeString(). |
This function is only emitted while the task is busy.
Implemented in Qtilities::Core::Task.
|
pure virtual |
The name of the task.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is paused.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Indicates what should happen to the task when the user click's on the "Remove Task" button in a Qtilities::CoreGui::SingleTaskWidget.
Default is TaskHideWhenRemoved.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is resumed after it was paused.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task started.
expected_subtasks | The number of subtasks which must be completed in order for this task to complete. If you don't provide the number of subtasks, progress for the task will be shown as a progress bar as a busy indicator. See QProgressBar for more information on this. If you do provide the number of subtasks, the progress be updated everytime subtaskCompleted() is emitted. |
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
Indicates what should happen to the task when the user click's on the "Stop Task" button in a Qtilities::CoreGui::SingleTaskWidget.
Default is TaskDoNothingWhenStopped.
Reimplemented in Qtilities::Core::Task.
|
inlinevirtual |
Indicates what should happen to the task when the user click's on the "Stop Task" button in a Qtilities::CoreGui::SingleTaskWidget.
Default is TaskStopConfirmationMsgBox.
This function was added in Qtilities v1.3.
Reimplemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when the task is stopped during execution.
Implemented in Qtilities::Core::Task.
|
pure virtual |
Signal emitted when a sub task is about to be completed.
Implemented in Qtilities::Core::Task.
|
inlinevirtual |
|
pure virtual |
Signal emitted when the task's type changes.
Implemented in Qtilities::Core::Task.
|
inline |
Enables elapsed time changed notifications through taskElapsedTimeChanged().
Disabled by default.
Qtilities : Reference Documentation | Back to top |
Copyright © 2009-2013, Jaco Naudé
|