CXCProgress

alpha version, October 2000

<<<sorry, this document is slightly out of date. Temporarily, check it please against the header file; we shall soon provide a documentation upgrade>>>

The CXCProgress object, provided by the framework, supplies to the conversion object a user interface:

-void start(double min,double max); -void start(double max); -double current;

The first group of messages is related to the progress indication. The start method must be called as the very first one; it sets the progress indicator to show values from the min (as the start, empty position) to the max (as the final, full position). In case the min is greater or equal to max (or if the max equals exactly to (unsigned)-1, to recognize the CXCUnknownSize value--see the CXCStreamData class), the progress indicator will be valueless, ie. it will not show the progress as such, but just the fact the program is working (ie. it changes to a busy indicator). Even so, it is strongly recommended to use the skipTo or step methods regularly, see below.

In the quite common case the min value is zero, you can use the alternative start method with only one argument. Should you ever need to check the current state of the progress, you can use the current method.

Note that all the progress values are double; it works well for integer progress values, but allows you to progress, say, from 0.3 to 0.8, should you ever need to, without explicit recalculations.

-void skipTo(double newCurrent); -void step(double step=1.0);

Both the skipTo and step methods change the progress indicator value, the former to an absolute value, the latter increments the current value (obtainable using the current method). Both of them can indicate a user break by generating an exception (skipping thus out of the doConvert method automatically, unless you use the X_DURING harness). The user break support is why these methods should be called even if the valueless indicator is used.

In case you do use the X_DURING harness inside the doConvert method, and if you call skipTo or step inside the X_DURING harness, take care to raise a "XCConversionAbortedException" exception, should it occur, so that the break support continues working properly. The exception name is defined as a macro XCConversionAbortedException:

@implementation Conv ... -void doConvert { ... X_DURING ... [_progress step]; ... X_HANDLER if ([[localException name] isEqual:XCConversionAbortedException]) [localException raise]; ... X_ENDHANDLER ... } @end

Note: you can use the CXDialog services to open an information or query alert, or even to open a dialogue defined more or less the same way as the details dialogue.

Have in mind, though, that the usage of alerts and/or dialogues during the conversion is and always will be strongly discommended: do not use them, unless absolutely essential. The reason is that the user should be able to set the conversion attributes at start (via the details dialogue), and let the rest run unattended.