Decoding a data file can sometimes take a long time. Lucy provides a standard mechanism for lengthy operations to report their progress.
At the same time Lucy provides a mechanism to notify listeners of this progress, which can be useful to show custom progress bars in a Lucy-based application.
ILcyLucyEnv
extends ILcdStatusListener
and, at the same time is a producer of status events, by offering the methods addStatusListener
and removeStatusListener
.
The idea is that ILcyLucyEnv
can be used as a listener to time-consuming tasks that produce TLcdStatusEvent
objects.
Add-ons that perform time-consuming tasks, such as decoding a large file, should register the ILcyLucyEnv
as a ILcdStatusListener
to the time-consuming object, the decoder for instance.
Currently, three types of status reporting are supported. You can call the statusChanged
method of the ILcyLucyEnv
interface with:
-
A
TLcdStatusEvent
with IDTLcdStatusEvent.MESSAGE
, to simply display a message in the status bar. The message is unrelated to progress. -
A
TLcdStatusEvent
with IDTLcdStatusEvent.START_BUSY
, followed by one or moreTLcdStatusEvent
instances with IDTLcdStatusEvent.PROGRESS
that contain the progress made, and finally aTLcdStatusEvent
with IDTLcdStatusEvent.END_BUSY
. This sequence reports when the task starts, what progress is made, and when the task is finished. -
A
TLcdStatusEvent
with IDTLcdStatusEvent.START_BUSY
, followed by one or moreTLcdStatusEvent
instances with IDTLcdStatusEvent.PROGRESS
, which have theisProgressIndeterminate
flag set to to true, and finally aTLcdStatusEvent
with IDTLcdStatusEvent.END_BUSY
. These report about tasks for which the progress cannot be predicted, such as waiting for an internet connection. -
The same as the two previous events in this list, except that these events have
isBlockingHint
set tofalse
. The result of this setting is a request for the user interface not to block until the task is finished. It is up to the front-end to decide whether this request is respected or not. The default front-end that comes with Lucy respects this request, but custom front-ends may choose to block the GUI in all cases.
GUI widgets that want to take care of status events, typically status bars or popup windows displaying a progress bar, can
then register themselves as status listeners to ILcyLucyEnv
. If they are registered, they are notified of all those status events. Note that it is possible that two sources emit status
events at the same time, when two files are being decoded at the same time for instance. You may want to consider this when
you implement your own status listener.
The default front-end that comes with Lucy serves as an example of a status listener. It adds a status listener to ILcyLucyEnv
to update the progress bar in its status bar. Note that this status bar is not designed to handle simultaneous progress reports
of multiple sources at once.