| 1 |
#pragma once |
| 2 |
|
| 3 |
#include <string> |
| 4 |
namespace lsp |
| 5 |
{ |
| 6 |
/** |
| 7 |
* The <code>IProgressMonitor</code> interface is implemented |
| 8 |
* by objects that monitor the progress of an activity; the methods |
| 9 |
* in this interface are invoked by code that performs the activity. |
| 10 |
* <p> |
| 11 |
* All activity is broken down into a linear sequence of tasks against |
| 12 |
* which progress is reported. When a task begins, a <code>beginTask(const wstring&, int) |
| 13 |
* </code> notification is reported, followed by any number and mixture of |
| 14 |
* progress reports (<code>worked()</code>) and subtask notifications |
| 15 |
* (<code>subTask(const wstring&)</code>). When the task is eventually completed, a |
| 16 |
* <code>done()</code> notification is reported. After the <code>done()</code> |
| 17 |
* notification, the progress monitor cannot be reused; i.e., <code> |
| 18 |
* beginTask(const wstring&, int)</code> cannot be called again after the call to |
| 19 |
* <code>done()</code>. |
| 20 |
* </p> |
| 21 |
* <p> |
| 22 |
* A request to cancel an operation can be signaled using the |
| 23 |
* <code>setCanceled</code> method. Operations taking a progress |
| 24 |
* monitor are expected to poll the monitor (using <code>isCanceled</code>) |
| 25 |
* periodically and abort at their earliest convenience. Operation can however |
| 26 |
* choose to ignore cancelation requests. |
| 27 |
* </p> |
| 28 |
* <p> |
| 29 |
* Since notification is synchronous with the activity itself, the listener should |
| 30 |
* provide a fast and robust implementation. If the handling of notifications would |
| 31 |
* involve blocking operations, or operations which might throw uncaught exceptions, |
| 32 |
* the notifications should be queued, and the actual processing deferred (or perhaps |
| 33 |
* delegated to a separate thread). |
| 34 |
* </p> |
| 35 |
* <p> |
| 36 |
* Clients may implement this interface. |
| 37 |
* </p> |
| 38 |
*/ |
| 39 |
class IProgressMonitor |
| 40 |
{ |
| 41 |
public: |
| 42 |
virtual ~IProgressMonitor() |
| 43 |
{ |
| 44 |
} |
| 45 |
|
| 46 |
/** Constant indicating an unknown amount of work. |
| 47 |
*/ |
| 48 |
|
| 49 |
static int const UNKNOWN = -1; |
| 50 |
|
| 51 |
/** |
| 52 |
* Notifies that the main task is beginning. This must only be called once |
| 53 |
* on a given progress monitor instance. |
| 54 |
* |
| 55 |
* @param name the name (or description) of the main task |
| 56 |
* @param totalWork the total number of work units into which |
| 57 |
* the main task is been subdivided. If the value is <code>UNKNOWN</code> |
| 58 |
* the implemenation is free to indicate progress in a way which |
| 59 |
* doesn't require the total number of work units in advance. |
| 60 |
*/ |
| 61 |
virtual void beginTask(void*, int totalWork) { |
| 62 |
|
| 63 |
}; |
| 64 |
/** |
| 65 |
* Notifies that the work is done; that is, either the main task is completed |
| 66 |
* or the user canceled it. This method may be called more than once |
| 67 |
* (implementations should be prepared to handle this case). |
| 68 |
*/ |
| 69 |
|
| 70 |
virtual void endTask(void*, int totalWork) |
| 71 |
{ |
| 72 |
} |
| 73 |
|
| 74 |
virtual void done(void*) = 0; |
| 75 |
|
| 76 |
/** |
| 77 |
* Internal method to handle scaling correctly. This method |
| 78 |
* must not be called by a client. Clients should |
| 79 |
* always use the method <code>worked(int)</code>. |
| 80 |
*/ |
| 81 |
virtual void internalWorked(double work) |
| 82 |
{ |
| 83 |
} |
| 84 |
/** |
| 85 |
* Returns whether cancelation of current operation has been requested. |
| 86 |
* Long-running operations should poll to see if cancelation |
| 87 |
* has been requested. |
| 88 |
* |
| 89 |
* @return <code>true</code> if cancellation has been requested, |
| 90 |
* and <code>false</code> otherwise |
| 91 |
* @see #setCanceled |
| 92 |
*/ |
| 93 |
virtual bool isCanceled() = 0; |
| 94 |
/** |
| 95 |
* Sets the cancel state to the given value. |
| 96 |
* |
| 97 |
* @param value <code>true</code> indicates that cancelation has |
| 98 |
* been requested (but not necessarily acknowledged); |
| 99 |
* <code>false</code> clears this flag |
| 100 |
* |
| 101 |
* @see #isCanceled |
| 102 |
*/ |
| 103 |
virtual void setCanceled(bool value) = 0; |
| 104 |
/** |
| 105 |
* Sets the task name to the given value. This method is used to |
| 106 |
* restore the task label after a nested operation was executed. |
| 107 |
* Normally there is no need for clients to call this method. |
| 108 |
* |
| 109 |
* @param name the name (or description) of the main task |
| 110 |
* @see #beginTask(java.lang.const wstring&, int) |
| 111 |
*/ |
| 112 |
virtual void setTaskName(void*) { |
| 113 |
|
| 114 |
}; |
| 115 |
/** |
| 116 |
* Notifies that a subtask of the main task is beginning. |
| 117 |
* Subtasks are optional; the main task might not have subtasks. |
| 118 |
* |
| 119 |
* @param name the name (or description) of the subtask |
| 120 |
*/ |
| 121 |
virtual void subTask(void*) |
| 122 |
{ |
| 123 |
} |
| 124 |
/** |
| 125 |
* Notifies that a given number of work unit of the main task |
| 126 |
* has been completed. Note that this amount represents an |
| 127 |
* installment, as opposed to a cumulative amount of work done |
| 128 |
* to date. |
| 129 |
* |
| 130 |
* @param work the number of work units just completed |
| 131 |
*/ |
| 132 |
virtual void worked(int work) { |
| 133 |
|
| 134 |
}; |
| 135 |
|
| 136 |
virtual void catch_exception(void*) = 0; |
| 137 |
}; |
| 138 |
} // namespace lsp |