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 ID TLcdStatusEvent.MESSAGE, to simply display a message in the status bar. The message is unrelated to progress.

  • A TLcdStatusEvent with ID TLcdStatusEvent.START_BUSY, followed by one or more TLcdStatusEvent instances with ID TLcdStatusEvent.PROGRESS that contain the progress made, and finally a TLcdStatusEvent with ID TLcdStatusEvent.END_BUSY. This sequence reports when the task starts, what progress is made, and when the task is finished.

  • A TLcdStatusEvent with ID TLcdStatusEvent.START_BUSY, followed by one or more TLcdStatusEvent instances with ID TLcdStatusEvent.PROGRESS, which have the isProgressIndeterminate flag set to to true, and finally a TLcdStatusEvent with ID TLcdStatusEvent.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 to false. 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.