Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwyDialog (HEAD)

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