wait (HEAD)

wait — Informing the world we are busy

Functions

Includes

#include <app/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

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. It used to let the main loop to run always. Since version 2.46 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

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

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.

The prefix will take effect in the next gwy_app_wait_set_message() call.

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

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

Since: 2.3

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

Since: 2.3

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.

Since: 2.48

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

Since: 2.48

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.

Since: 2.49

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

Since: 2.54