wait: Gwyddion Application Library Reference Manual

## wait wait — Informing the world we are busy |

## Functions

void | gwy_app_wait_start ()
void | gwy_app_wait_finish ()
gboolean | gwy_app_wait_set_fraction ()
gboolean | gwy_app_wait_set_message ()
gboolean | gwy_app_wait_set_message_prefix ()
void | gwy_app_wait_cursor_start ()
void | gwy_app_wait_cursor_finish ()
gboolean | gwy_app_wait_get_enabled ()
void | gwy_app_wait_set_enabled ()
gboolean | gwy_app_wait_was_canceled ()
void | gwy_app_wait_set_preview_widget ()

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

The waiting functions implement a simple single-thread approach to performing a long computation while keeping the GUI responsive.

The typical basic usage is as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    gboolean cancelled = FALSE;

    gwy_app_wait_start(window, _("Evaluating..."));
    for (i = 0; i < n_iters; i++) {
        do_one_calculation_iteration();
        if (!gwy_app_wait_set_fraction((i + 1.0)/n_iters)) {
            cancelled = TRUE;
            break;
        }
    }
    gwy_app_wait_finish();

    if (cancelled)
        handle_cancelled_computation();
    else
        do_something_with_result();

## Functions

### gwy_app_wait_start()

    void
    gwy_app_wait_start (GtkWindow *window,
                        const gchar *message);

Starts waiting for a window `window` , creating a dialog with a progress bar.

Waiting is global, there can be only one at a time.

Do not forget to call `gwy_app_wait_finish()` when the computation is finished (or cancelled). You should also call `gwy_app_wait_set_fraction()` or `gwy_app_wait_set_message()` regularly to leave the GUI responsive.

#### Parameters

window | A window. |
message | A message to show in the wait dialog. |

### gwy_app_wait_finish()

    void
    gwy_app_wait_finish (void);

Finishes waiting, closing the dialog.

No function like `gwy_app_wait_set_message()` should be call after that.

This function must be called even if user cancelled the operation.

### gwy_app_wait_set_fraction()

    gboolean
    gwy_app_wait_set_fraction (gdouble fraction);

Sets the amount of progress the progress bar on the dialog displays.

This function may let the Gtk+ main loop to run, but it performs automated rate-limiting and only does so if sufficient time has passed since the last main loop invocation. Therefore, you can call it 10000 times per second without fearing that the program will spend all time updating the GUI and no time in the calculation.

It must not be called again once the operation is cancelled, i.e. after any of the progress reporting functions return `FALSE`.

#### Parameters

fraction | The progress of the operation, as a number from 0 to 1. |

#### Returns

`TRUE` if the operation can continue, `FALSE` if user cancelled it meanwhile. You must always check the return value and cancel the operation if it is `FALSE`.

### gwy_app_wait_set_message()

    gboolean
    gwy_app_wait_set_message (const gchar *message);

Sets the message shown on the progress dialog.

See also `gwy_app_wait_set_message_prefix()` which makes this function more usable directly as a callback.

This function lets the Gtk+ main loop to run.

It must not be called again once the operation is cancelled, i.e. after any of the progress reporting functions return `FALSE`.

#### Parameters

message | A mesage to show in the progress dialog. |

#### Returns

`TRUE` if the operation can continue, `FALSE` if user cancelled it meanwhile. You must always check the return value and cancel the operation if it is `FALSE`.

### gwy_app_wait_set_message_prefix()

    gboolean
    gwy_app_wait_set_message_prefix (const gchar *prefix);

Sets prefix for the messages shown in the progress dialog.

This function lets the Gtk+ main loop to run.

It must not be called again once the operation is cancelled, i.e. after any of the progress reporting functions return `FALSE`.

#### Parameters

prefix | The prefix for new messages. |

#### Returns

`TRUE` if the operation can continue, `FALSE` if user cancelled it meanwhile. You must always check the return value and cancel the operation if it is `FALSE`.

### gwy_app_wait_cursor_start()

    void
    gwy_app_wait_cursor_start (GtkWindow *window);

Changes the cursor for a window to indicate work.

This function lets the Gtk+ main loop to run.

#### Parameters

window | A window. |

### gwy_app_wait_cursor_finish()

    void
    gwy_app_wait_cursor_finish (GtkWindow *window);

Resets the cursor for a window.

This function lets the Gtk+ main loop to run.

If the window cursor was non-default before `gwy_app_wait_cursor_start()`, it is not restored and has to be set manually. This limitation is due to the nonexistence of a method to obtain the current cursor.

#### Parameters

window | A window. |

### gwy_app_wait_get_enabled()

    gboolean
    gwy_app_wait_get_enabled (void);

Reports whether progress reporting is globally enabled.

#### Returns

`TRUE` if progress reporting is enabled, `FALSE` if it is disabled.

### gwy_app_wait_set_enabled()

    void
    gwy_app_wait_set_enabled (gboolean setting);

Globally enables or disables progress reporting.

This function may not be used when a waiting dialog is currently being shown.

By default, progress reporting is enabled. Non-GUI applications that run module functions may wish to disable it to avoid GTK+ calls or just showing the progress dialogs.

If progress reporting is disabled then functions such as `gwy_app_wait_set_message()` and `gwy_app_wait_set_fraction()` become no-op and always return `TRUE` as nothing can be cancelled by the user. Functions `gwy_app_wait_cursor_start()` and `gwy_app_wait_cursor_finish()` still work but may be called with `NULL` arguments.

#### Parameters

setting | `TRUE` to enable progress reporting, `FALSE` to disable it. |

### gwy_app_wait_was_canceled()

    gboolean
    gwy_app_wait_was_canceled (void);

Checks if a progress dialog was cancelled.

Calling this function is only meaningful between `gwy_app_wait_start()` and `gwy_app_wait_finish()`. It returns `TRUE` if the computation was cancelled by the user. This may be occasionaly useful in complex multi-level calculations. Usually, the return values of `gwy_app_wait_set_fraction()` and `gwy_app_wait_set_message()` are sufficient.

#### Returns

`TRUE` if the currently running calculation was cancelled.

### gwy_app_wait_set_preview_widget()

    void
    gwy_app_wait_set_preview_widget (GtkWidget *widget);

Sets the preview widget of a wait dialogue.

This function needs to be used before `gwy_app_wait_start()` to have any effect.

#### Parameters

widget | Preview widget, usually something like GwyDataView. |