GwyDialog: Gwyddion Application Library Reference Manual

## GwyDialog GwyDialog — Data processing module dialog |

## Functions

void | (*GwyDialogPreviewFunc) ()
GtkWidget * | gwy_dialog_new ()
void | gwy_dialog_add_stock_buttons ()
void | gwy_dialog_add_content ()
void | gwy_dialog_set_preview_func ()
void | gwy_dialog_set_instant_updates_param ()
GwyDialogOutcome | gwy_dialog_run ()
void | gwy_dialog_invalidate ()
void | gwy_dialog_have_result ()
gboolean | gwy_dialog_update_requested ()

## Types and Values

enum | GwyDialogOutcome
enum | GwyPreviewType
struct | GwyDialog
struct | GwyDialogClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkWindow
                            ╰── GtkDialog
                                ╰── GwyDialog

## Implemented Interfaces

GwyDialog implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

GwyDialog is a GtkDialog suitable for most data processing modules (including volume data, graph, etc.). It offers simplified construction functions `gwy_dialog_new()`, `gwy_dialog_add_stock_buttons()` and `gwy_dialog_add_content()`.

The main feature is integration with GwyParamTable. Parameter tables are registered using `gwy_dialog_add_param_table()`. The dialog can then perform some simple tasks itself. For instance with `gwy_dialog_set_instant_updates_param()` the sensitivity of an Update button is handled automatically together with a part of the preview redrawing logic if you set up a preview function with `gwy_dialog_set_preview_func()`.

GwyDialog also handles the state change logic typical for Gwyddion data processing modules. The function `gwy_dialog_run()` only exits when the dialog finishes with some kind of conclusion what to do next, see GwyDialogOutcome. Other response can either be handled completely automatically, for instance `GWY_RESPONSE_RESET` and `GWY_RESPONSE_UPDATE`, or in cooperation with the module which connects to the GtkDialog::response signal.

If you need to prepare the parameter tables before the automatic reset, connect to the signal normally and it will be run before the GwyDialog handler. If you need to touch up the tables afterwards connect your handler with `G_CONNECT_AFTER`.

## Functions

### GwyDialogPreviewFunc()

    void
    (*GwyDialogPreviewFunc) (gpointer user_data);

Protoype of GwyDialog preview functions.

#### Parameters

user_data | User data to passed to `gwy_dialog_set_preview_func()`. | [closure]

### gwy_dialog_new()

    GtkWidget *
    gwy_dialog_new (const gchar *title);

Creates a new data processing module dialog window.

The dialog is modal by default.

#### Parameters

title | Title of the dialog window or `NULL`. |

#### Returns

A new data processing module dialog window.

### 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).

`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.

`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.

#### Parameters

dialog | A data processing module dialog window. |
item | Predefined button type. |
... | List of more item identifiers, terminated by GWY_STOCK_NONE (or zero). |

### 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()`.

#### Parameters

dialog | A data processing module dialog window. |
child | Child widget to add. |
expand | `TRUE` if the `child` is to be given extra space allocated to the content area. |
fill | `TRUE` if space given by `expand` option is actually allocated to `child` , rather than just padding it |
padding | Extra space to put between `child` and its neighbours, including outer edges. |

### 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()`. Use `gwy_dialog_set_instant_updates_param()` if you have a parameter controlling instant updates.

#### Parameters

dialog | A data processing module dialog window. |
prevtype | Preview style to use. |
preview | Function which performs the preview (or `NULL` for `GWY_PREVIEW_NONE`). | [scope notified][closure user_data][destroy destroy]
user_data | User data to pass to `preview` . |
destroy | Function to call to free `user_data` (or `NULL`). |

### gwy_dialog_set_instant_updates_param()

    void
    gwy_dialog_set_instant_updates_param (GwyDialog *dialog,
                                          gint id);

Sets the id of instant updates parameter for a data processing module dialog window.

The parameter must be a boolean. When it is `TRUE` previews are immediate and the dialog button corresponding to `GWY_RESPONSE_UPDATE` is insensitive. When it is `FALSE` previews are manual, on pressing the dialog button which is now sensitive.

Setting the instant updates parameter makes the sensitivity of update dialog button automatic. If you need more control over it do not use this function.

#### Parameters

dialog | A data processing module dialog window. |
id | Parameter identifier. |

### 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()`.

#### Parameters

dialog | A data processing module dialog window. |

#### Returns

The final outcome of the dialog.

### 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.

#### Parameters

dialog | A data processing module dialog window. |

### 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()`.

#### Parameters

dialog | A data processing module dialog window. |

### 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`.

#### Parameters

dialog | A data processing module dialog window. |

#### Returns

`TRUE` if the Update button has been pressed since the last preview; `FALSE` if it has not been pressed.

## Types and Values

### enum GwyDialogOutcome

Type of conclusion from a data processing module dialog.

#### Members

GWY_DIALOG_CANCEL | The dialog was cancelled or destroyed. The module should save changed parameters but no data should be modified. This response is also returned for Close buttons used when there is no action to execute. |
GWY_DIALOG_PROCEED | The computation should proceed. Normally this means the user pressed the OK button. If the results are already available `GWY_DIALOG_HAVE_RESULT` is used instead. |
GWY_DIALOG_HAVE_RESULT | The computation has already been done. This response is used when `gwy_dialog_have_result()` has been called since the last `gwy_dialog_invalidate()`. |

### enum GwyPreviewType

Style of preview in a data processing dialog.

#### Members

GWY_PREVIEW_NONE | There is no preview. This is the default if you do not set any preview function. It does not make much sense to use it when setting up a preview function. |
GWY_PREVIEW_IMMEDIATE | Preview occurs immediately, either unconditionally or controlled by an instant updates checkbox. Dialog invalidation queues a preview if instant updates are not disabled. |
GWY_PREVIEW_UPON_REQUEST | Preview is only upon request, usually by pressing a button with response `GWY_RESPONSE_UPDATE`. Dialog invalidation does not queue a preview. |

### 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 of parameter definition sets.