GwyDialog: Gwyddion Application Library Reference Manual

## GwyDialog GwyDialog — Data processing module dialog |

## Functions

void | (*GwyDialogPreviewFunc) ()
GtkWidget * | gwy_dialog_new ()
void | gwy_dialog_add_buttons ()
void | gwy_dialog_add_content ()
void | gwy_dialog_add_param_table ()
void | gwy_dialog_remove_param_table ()
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
enum | GwyResponseType
struct | GwyDialog
struct | GwyDialogClass

## Object Hierarchy

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

## Implemented Interfaces

GwyDialog implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <app/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_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()`. |

Since: 2.59

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

Since: 2.59

### gwy_dialog_add_buttons ()

    void
    gwy_dialog_add_buttons (GwyDialog *dialog,
                            gint response_id,
                            ...);

Adds stock buttons to data processing module dialog window.

Beside GwyResponseType, the following GTK+ responses are recognised and handled automatically.

`GTK_RESPONSE_OK` or `GTK_RESPONSE_ACCEPT` creates an OK button which finishes the dialog with result `GWY_DIALOG_PROCEED` (or `GWY_DIALOG_HAVE_RESULT` if result has been calculated).

`GTK_RESPONSE_CANCEL` or `GTK_RESPONSE_REJECT` creates a Cancel button which finishes the dialog with result `GWY_DIALOG_CANCEL`.

#### Parameters

dialog | A data processing module dialog window. |
response_id | Response identifier from either GtkResponseType or GwyResponseType enum. Not all GtkResponseType values may do something useful. |
... | List of more response identifiers, terminated by 0. |

Since: 2.59

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

Since: 2.59

### gwy_dialog_add_param_table ()

    void
    gwy_dialog_add_param_table (GwyDialog *dialog,
                                GwyParamTable *partable);

Registers a parameter table with a data processing module dialog window.

This function does not pack the table's widget anywhere; it just registers the table with `dialog` . Pack the table's widget obtained `gwy_param_table_widget()` to the dialog using `gwy_dialog_add_content()` or some other container widget.

All parameters in all parameter tables in a GwyDialog must have unique ids. This is because parameters are commonly refered to only by the id. When this condition is satisfied, different parameter tables can correspond to different GwyParamDef definition sets. Normally, however, multiple tables provide controls for different subsets of parameters defined by one GwyParamDef.

If multiple tables are added, parameters in any table can be changed inside a “param-changed” callback without triggering infinite recursion. This is because GwyDialog prevents recursion also during cross-updates.

Usually, you can just connect all “param-changed” signals to the same handler and ignore which table emitted the signal. All the useful information is in the parameter id.

The dialog consumes the floating reference of `partable` . Usually this has the desired effect that `dialog` becomes the only owner and the table is destroyed when `dialog` finishes. However, if you want to later use `gwy_dialog_remove_param_table()` without destroying the table you need to explicitly add your own reference.

#### Parameters

dialog | A data processing module dialog window. |
partable | Parameter table to add. |

Since: 2.59

### gwy_dialog_remove_param_table ()

    void
    gwy_dialog_remove_param_table (GwyDialog *dialog,
                                   GwyParamTable *partable);

Removes a parameter table from a data processing module dialog window.

Removal releases the reference `dialog` holds on `partable` . If you have not added your own reference `partable` will be destroyed when it is removed.

#### Parameters

dialog | A data processing module dialog window. |
partable | Parameter table to remove. |

Since: 2.59

### 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`). |
user_data | User data to pass to `preview` . |
destroy | Function to call to free `user_data` (or `NULL`). |

Since: 2.59

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

Since: 2.59

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

Since: 2.59

### gwy_dialog_invalidate ()

    void
    gwy_dialog_invalidate (GwyDialog *dialog);

Notifies a data processing module 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 require invalidation, for instance target graphs or mask colours.

The function can have multiple effects. In all cases it resets the result 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, `gwy_dialog_invalidate()` can be safely called multiple times in succession without triggering multiple recomputations.

#### Parameters

dialog | A data processing module dialog window. |

Since: 2.59

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

Since: 2.59

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

Since: 2.64

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

Since: 2.59

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

Since: 2.59

### enum GwyResponseType

Type of predefined dialog response types.

#### Members

GWY_RESPONSE_RESET | Reset of all parameters (that do not have the no-reset flag set). Adding it to a GwyDialog creates a Reset button which is normally handled fully by the dialog itself. |
GWY_RESPONSE_UPDATE | Update of the preview. Adding it to a GwyDialog creates an Update button which is normally handled fully by the dialog itself (including sensitivity tied to an instant updates parameter). |
GWY_RESPONSE_CLEAR | Clearing/resetting of selection. Adding it to a GwyDialog creates a Clear button. You need to connect to “response” and handle the response yourself. |

Since: 2.59

### struct GwyDialog

    struct GwyDialog;

Object representing a set of parameter definitions.

The GwyDialog struct contains no public fields.

Since: 2.59

### struct GwyDialogClass

    struct GwyDialogClass {
        GtkDialogClass parent;
    };

Class of parameter definition sets.

Since: 2.59