progress_dialogue_i

Display a progress dialogue box to show status for long-running operations and allow the user to cancel them.

Modelled after the Automation 4 Lua progress reporting interface.

The progress dialogue requires the long-running operation to be run in a thread, this is achieved by having the plugin pass a pointer to a work function.

TODO: Dialogues need to be parented somehow.

typedef void * progress_dialogue_t;
typedef void * (*progress_dialogue_work_function_t)(int *cancel_status, progress_dialogue_t dialogue, void *userdata);

struct progress_dialogue_i {
    void * (*Create)(progress_dialogue_work_function_t work_function, void *userdata);

    void (*SetTitle)(progress_dialogue_t dialogue, const char *title);
    void (*SetStatus)(progress_dialogue_t dialogue, const char *status);
    void (*SetProgress)(progress_dialogue_t dialogue, int n, int max);
    void (*SetEta)(progress_dialogue_t dialogue, int seconds);
    void (*LogMessage)(progress_dialogue_t dialogue, const char *message);
};

progress_dialogue_work_function_t

void *progress_dialogue_work_function_t(int *cancel_status, progress_dialogue_t dialogue, void *userdata);

Plugin-defined work function that gets run in a separate thread to do the long operation. Because this function is run in a separate thread from the main UI thread, it cannot access the UI directly, it can only access the progress dialogue through the interface defined here. It should not attempt to create another progress dialogue either. Be aware of thread-local storage.

cancel_status points to an integer that is initially zero, it will be changed to non-zero if the user clicks the Cancel button in the dialogue box. Note that you can not disable the cancel-button, you must always allow the user to cancel the operation.

dialogue is a handle to the dialogue box. This is used to control its appearance and more. This handle is only valid as long as the operation is running, and should only be accessed within the work function.

userdata is a pointer to plugin-defined data. This can be used to transfer data into the function.

When this function returns, the operation is considered completed (or failed/cancelled) and the progress dialogue will disappear. If any messages were logged, the dialogue will stay open to let the user read through the messages, and the user will be provided with a Close button. The progress_dialogue_i::Create function will only return when the progress dialogue box has been closed.

The return value of progress_dialogue_work_function_t is passed unchanged and uninterpreted back as the result of progress_dialogue_i::Create.

Create

void *Create(progress_dialogue_work_function_t work_function, void *userdata);

Create and display a progress dialogue box.

work_function is the function that will be called once the dialogue box is displayed. See above for details.

userdata is a pointer passed unchanged to the work function, to allow the plugin to pass data into the work function.

The return value is the return value of the work function. Create only returns when the work function has returned, and the progress dialogue has been closed.

SetTitle

Set the title of the dialogue box, what the name of the operation is.

SetStatus

Set a message telling what part of the operation is being performed right now.

SetProgress

Set the progress bar, n steps of max steps have been completed.

SetEta

Display an estimate for remaining time. Set estimate to negative to not display one.

LogMessage

Log a message, display in a message log in the progress dialogue. The message log is only shown if it is used. If any messages are logged, the dialogue will stay on screen and block execution until the user dismisses it.