GwyDialogPreviewFunc()

void
(*GwyDialogPreviewFunc) (gpointer user_data);

Protoype of GwyDialog preview functions.

gwy_dialog_new()

GtkWidget *
gwy_dialog_new (const gchar *title);

Creates a new data processing module dialog window.

The dialog is modal by default.

gwy_dialog_add_stock_buttons()

void
gwy_dialog_add_stock_buttons (GwyDialog *dialog,
                              GwyStockItem item,
                              ...);

Adds stock buttons to data processing module dialog window.

Several items are handled by the dialog itself, although you can still respond to them in your own handler (which is most useful custom resetting actions). The following two determine the outcome of gwy_dialog_run().

GWY_STOCK_OK creates an OK button which finishes the dialog with result GWY_DIALOG_PROCEED or GWY_DIALOG_HAVE_RESULT, depending on whether the result has been calculated. If an OK button is present, it becomes the default dialog response.

GWY_STOCK_CANCEL creates a Cancel button and GWY_STOCK_CLOSE a Close button. Either finishes the dialog with result GWY_DIALOG_CANCEL. The Close button should be used when no further action exist that could be executed and there would be no meaningful difference between OK and Cancel. In such case, it should be the only final-response button. If a Close button is present (and no OK), it becomes the default dialog response.

Other buttons with standard response are update and parameter reset.

GWY_STOCK_UPDATE creates an Update button. It runs the preview function if updates are manual or instant updates are disabled.

GWY_STOCK_RESET creates a Reset button. It resets all the parameter tables in the dialog.

Other stock button can be recognised and handled automatically by something else that helps to manage the dialog. For example, GwyTool handles additional buttons.

gwy_dialog_add_content()

void
gwy_dialog_add_content (GwyDialog *dialog,
                        GtkWidget *child,
                        gboolean expand,
                        gboolean fill,
                        gint padding);

Adds a widget to the data processing module dialog window content area.

By tradition, the dialog content is in a vertical GtkBox. Parameters expand , fill and padding have the same meaning as in gtk_box_pack_start().

gwy_dialog_set_preview_func()

void
gwy_dialog_set_preview_func (GwyDialog *dialog,
                             GwyPreviewType prevtype,
                             GwyDialogPreviewFunc preview,
                             gpointer user_data,
                             GDestroyNotify destroy);

Sets the preview function for a data processing module dialog.

The preview function is called automatically when the dialog receives GWY_RESPONSE_UPDATE response and/or after gwy_dialog_invalidate(). Define a boolean parameter with gwy_param_def_add_instant_updates() and add it to a param table to set up optional (user-controlled) instant updates.

gwy_dialog_run()

GwyDialogOutcome
gwy_dialog_run (GwyDialog *dialog);

Runs a data processing module dialog window.

This function does not return until the dialog finishes with a final outcome. The final outcome is usually either cancellation or an OK response, as indicated by the return value. Other response types – preview, parameter reset or help – are generally handled inside and do not cause this function to return. Furthermore, the dialog is always destroyed when the function returns. These are the main differences from gtk_dialog_run().

Modal data processing functions normally run their GUI by setting up the GwyDialog and a single call

1

GwyDialogOutcome outcome = gwy_dialog_run(dialog);

Non-modal tools should show the dialog with gtk_window_show() or a similar function and letting the main loop run. In such case the only responses handled by GwyDialog itself are GWY_RESPONSE_UPDATE and GWY_RESPONSE_RESET. They are both run between the user “response” handler and the user handler connected with G_CONNECT_AFTER. So you can respond before and/or after the built-in response, as needed.

The first time the GwyDialog is run using this function (which is usually also the only time), it emits GwyParamTable::param-changed with id =-1 on the parameter table(s). If there are multiple, the signal is emitted only on the first added, as the updates are assumed being consolidated.

gwy_dialog_invalidate()

void
gwy_dialog_invalidate (GwyDialog *dialog);

Notifies a data processing module that dialog preview is no longer valid.

This function should be called from “param-changed” when a parameter influencing the result has changed. This means most parameter changes. Some parameter do not require invalidation, for instance target graphs or mask colours.

The function can have multiple effects. In all cases it resets the outcome state back to having no results (nullifying any previous gwy_dialog_have_result()). Furthermore, if the preview style is GWY_PREVIEW_IMMEDIATE and instant updates are enabled it queues up a preview recomputation. The preview is added as an idle source to the GTK+ main loop. Therefore, the computation is rerun after a short delay and gwy_dialog_invalidate() can be safely called multiple times in succession without triggering multiple recomputations.

gwy_dialog_cancel_preview()

void
gwy_dialog_cancel_preview (GwyDialog *dialog);

Cancels queued preview update in a data processing dialog.

If no preview is currently queued, this function is a no-op.

Cancellation may be needed in a tool dialog when the current data are switched to no-data while a preview update is still queued. A tool dialog would handle such change immediately by making controls insensitive and changing data display widets to display nothing. Any preview function call in such state is unnecessary and even awkward.

The function only deals with update queuing; it does not stop any long-running computation in the module. That is the responsibility of the module function. The dialog outcome does not change. If a preview was queued, gwy_dialog_have_result() will continue returning FALSE.

Modal dialogs of data processing functions should not need this function at all.

gwy_dialog_have_result()

void
gwy_dialog_have_result (GwyDialog *dialog);

Notifies a data processing module dialog preview that results are available.

Modules may not have any other means of preview than the full computation of the final result. It is then useful to keep track whether it has been already computed to prevent unnecessary work.

Calling this function makes gwy_dialog_run() return GWY_DIALOG_HAVE_RESULT instead of the usual OK response GWY_DIALOG_PROCEED. This indicates the result do not need to be recalculated (presumably you stored them in a safe place). The state is reset back to no results by gwy_dialog_invalidate().

gwy_dialog_update_requested()

gboolean
gwy_dialog_update_requested (GwyDialog *dialog);

Reports whether preview was explicitly requested by the user.

If the dialog has both immediate (partial) previews and an Update button to run a slower computation, the preview function usually needs to distinguish between invocations from invalidation and pressing Update button. It can be done using this function. If the preview is invoked by user pressing button with GWY_RESPONSE_UPDATE response id then it returns TRUE, otherwise FALSE.

enum GwyDialogOutcome

Type of conclusion from a data processing module dialog.

enum GwyPreviewType

Style of preview in a data processing dialog.

struct GwyDialog

struct GwyDialog;

Object representing a set of parameter definitions.

The GwyDialog struct contains no public fields.

struct GwyDialogClass

struct GwyDialogClass {
    GtkDialogClass parent_class;
};

Class of parameter definition sets.