classafReflux::ProgressDialogue

sys::Obj
  afReflux::ProgressDialogue

(Widget) - A dialogue window that displays an updatable progress bar.

Progress Dialogue

Sample usage:

dialogue := ProgressDialogue()

dialogue.with {
    it.title = "Look at me!"
    it.image = Image(`fan://icons/x48/flux.png`)
    it.closeWhenFinished = false
}

result := dialogue.open(reflux.window) |ProgressWorker worker->Obj?| {
    worker.update(1, 4, "Processing...")
    Actor.sleep(2sec)

    worker.update(2, 4, "A Very Long...")
    Actor.sleep(2sec)

    worker.update(3, 4, "Process...")
    Actor.sleep(2sec)

    worker.update(4, 4, "Done.")
    return "result!"
}

Processing

As seen in the example, the work should be performed in the callback func passed to open(). The work func should then make repeated calls to ProgressWorker.update() to update the dialogue and progress bar.

The callback func is processed in its own thread. This keeps the UI thread free to update the progress dialogue as needed.

Note that this means the worker function should be immutatble.

To update other UI components from within the callback func, use Desktop:

registry := this.registry
Desktop.callAsync |->| {
    reflux := (Reflux) registry.serviceById(Reflux#.qname)
    reflux.refresh
    ...
}  

Cancelling

A user may cancel any progress dialogue at any time. Callback funcs should check the status of the ProgressWorker.cancelled flag and return early if set. An alternative is to call ProgressWorker.update() often, which throws a sys::CancelledErr if the cancelled flag has been set.

Should a progress dialogue be cancelled, ProgressDialogue.onCancel() is called. This hook may be overridden to perform custom cancel handling. By default the dialogue shows a Cancelled by User message.

To mimic a user pressing Cancel the callback func may simply throw a sys::CancelledErr.

Error Handling

Should an error occur, ProgressDialogue.onError(Err) is called. This hook may be overridden to perform custom cancel handling. By default the dialogue shows an error message and displays the stack trace in the details panel.

If the ProgressDialogue is autobuilt then the error is added to the Errors service.

dialogue := (ProgressDialogue) registry.autobuild(ProgressDialogue#)

or the dialogue may be set as an IoC field:

@Autobuild ProgressDialogue dialogue
_padToFiveLines

Source

const static Str _padToFiveLines(Str text)

closeWhenFinished

Source

Bool closeWhenFinished := true

If true then the dialogue automatically closes when the work is done. Set to false to keep the dialogue open and have the user manually close it. Handy to show a final status and / or let the user inspect the details.

Defaults to true.

detailText

Source

Str detailText := ""

The text displayed in the details panel.

image

Source

Image? image

The image displayed to the left of the message.

onCancel

Source

virtual Void onCancel()

Hook for handling cancelled events from the user.

By default this sets the dialogue text to Cancelled by User.

onError

Source

virtual Void onError(Err err)

Hook for handling errors from the ProgressWorker callback function.

By default this adds a stack trace to the details panel and sets the text to the error msg. closeWhenFinished is also set to false.

If this progress dialogue was autobuilt by IoC then the Err is also added to the Errors service.

open

Source

Obj? open(Window parent, |ProgressWorker->Obj? callback)

Creates and displays a progress dialogue. All work is done inside the given callback in a separate thread.

This call blocks until the work is finished and returns what the function returns.

text

Source

Str text := ""

The message text to display.

title

Source

Str title := "Progress Dialogue"

Title string.