unitool

unitool — Universal tool template.

Synopsis




#define     GWY_UNITOOL_RESPONSE_UNSELECT
enum        GwyUnitoolUpdateType;
struct      GwyUnitoolSlots;
typedef     GwyUnitoolState;
void        (*GwyUnitoolFunc)               (GwyUnitoolState *state);
GtkWidget*  (*GwyUnitoolCreateFunc)         (GwyUnitoolState *state);
void        (*GwyUnitoolResponseFunc)       (GwyUnitoolState *state,
                                             gint response);
void        (*GwyUnitoolUpdateFunc)         (GwyUnitoolState *state,
                                             GwyUnitoolUpdateType reason);
gboolean    gwy_unitool_use                 (GwyUnitoolState *state,
                                             GwyDataWindow *data_window,
                                             GwyToolSwitchEvent reason);
GtkWidget*  gwy_unitool_dialog_add_button_apply
                                            (GtkWidget *dialog);
GtkWidget*  gwy_unitool_dialog_add_button_clear
                                            (GtkWidget *dialog);
GtkWidget*  gwy_unitool_dialog_add_button_hide
                                            (GtkWidget *dialog);
void        gwy_unitool_apply_set_sensitive (GwyUnitoolState *state,
                                             gboolean sensitive);
GtkWidget*  gwy_unitool_windowname_frame_create
                                            (GwyUnitoolState *state);
gdouble     gwy_unitool_get_z_average       (GwyDataField *dfield,
                                             gdouble xreal,
                                             gdouble yreal,
                                             gint radius);
void        gwy_unitool_update_label        (GwySIValueFormat *units,
                                             GtkWidget *label,
                                             gdouble value);
void        gwy_unitool_update_label_no_units
                                            (GwySIValueFormat *units,
                                             GtkWidget *label,
                                             gdouble value);
gboolean    gwy_unitool_get_selection_or_all
                                            (GwyUnitoolState *state,
                                             gdouble *xmin,
                                             gdouble *ymin,
                                             gdouble *xmax,
                                             gdouble *ymax);

Description

Details

GWY_UNITOOL_RESPONSE_UNSELECT

#define GWY_UNITOOL_RESPONSE_UNSELECT 255

Response id you should use for "Clear selection" button, if the tool has any. Universal tool can than handle it itself.


enum GwyUnitoolUpdateType

typedef enum {
    GWY_UNITOOL_UPDATED_SELECTION,
    GWY_UNITOOL_UPDATED_DATA,
    GWY_UNITOOL_UPDATED_CONTROLS
} GwyUnitoolUpdateType;


struct GwyUnitoolSlots

struct GwyUnitoolSlots {

    GType                  layer_type;
    GwyUnitoolFunc         layer_setup;
    GwyUnitoolCreateFunc   dialog_create;
    GwyUnitoolUpdateFunc   dialog_update;
    GwyUnitoolFunc         dialog_abandon;
    GwyUnitoolFunc         apply;
    GwyUnitoolResponseFunc response;
};

The custom functions constituting a particular tool, called by universal tool on various occasions.

Most of the slots (FIXME: all?) can be NULL, except layer_type.

GType layer_type The type of the active layer this particular tool uses, like GWY_LAYER_SELECT.
GwyUnitoolFunc layer_setup Function called when the active layer is created or changed to tune its properties.
GwyUnitoolCreateFunc dialog_create Function creating the tool dialog.
GwyUnitoolUpdateFunc dialog_update Function called when "updated" signal is received from the layer and the tool dialog should be updated.
GwyUnitoolFunc dialog_abandon Function called when the tool is abadoned. It should namely take care of the user_data field of tool state.
GwyUnitoolFunc apply Function called when user presses the OK button on the dialog. It should do whatever the tool is supposed to do but don't touch the dialog itself.
GwyUnitoolResponseFunc response A function handling nonstandard dialog responses, i.e. others than GTK_RESPONSE_CLOSE, GTK_RESPONSE_APPLY, GTK_RESPONSE_DELETE_EVENT and GWY_UNITOOL_RESPONSE_UNSELECT, that are handled by universal tool itself. It gets the response id as its second argument.

GwyUnitoolState

typedef struct {
    /*< public >*/
    gpointer user_data;

    GwyUnitoolSlots *func_slots;
    GwyDataWindow *data_window;
    GwyVectorLayer *layer;
    gboolean is_visible;  /* GTK_WIDGET_VISIBLE() returns BS... */

    GtkWidget *windowname;
    GtkWidget *dialog;

    GwySIValueFormat *coord_format;
    GwySIValueFormat *value_format;

    gboolean apply_doesnt_close;

    /*< private >*/
    gulong layer_updated_id;
    gulong data_updated_id;
    gulong response_id;
    gulong windowname_id;
} GwyUnitoolState;

Universal tool state.

You should put pointer to particular tool state to the user_data member and pointer to function slots to func_slots when creating it and otherwise consider it read-only.

Always use g_new0() or zero-fill the memory by other means when creating an unitialized state.


GwyUnitoolFunc ()

void        (*GwyUnitoolFunc)               (GwyUnitoolState *state);

General Unitool slot function signature.

state: Tool state.

GwyUnitoolCreateFunc ()

GtkWidget*  (*GwyUnitoolCreateFunc)         (GwyUnitoolState *state);

Dialog constructor slot function signature.

state: Tool state.
Returns : The newly created dialog.

GwyUnitoolResponseFunc ()

void        (*GwyUnitoolResponseFunc)       (GwyUnitoolState *state,
                                             gint response);

Extra dialog response handler slot function signature.

state: Tool state.
response: The tool dialog response.

GwyUnitoolUpdateFunc ()

void        (*GwyUnitoolUpdateFunc)         (GwyUnitoolState *state,
                                             GwyUnitoolUpdateType reason);

Tool update slot function signature.

state: Tool state.
reason: Update reason.

gwy_unitool_use ()

gboolean    gwy_unitool_use                 (GwyUnitoolState *state,
                                             GwyDataWindow *data_window,
                                             GwyToolSwitchEvent reason);

Switches a tool.

This function is to be called from a tool module use method. It does all the hard work of changing the layer, connecting or disconnecting callbacks, and showing or hiding the dialog; making all tools using it to behave more-or-less consistently.

state: Tool state.
data_window: A data window, as obtained in tool switch module method.
reason: Tool switch reason, as obtained in tool switch module method.
Returns : Whether the tool switch succeeded. Currently always TRUE.

gwy_unitool_dialog_add_button_apply ()

GtkWidget*  gwy_unitool_dialog_add_button_apply
                                            (GtkWidget *dialog);

Adds a Unitool-partially-managed "Apply" button to the tool dialog.

See also gwy_unitool_apply_set_sensitive().

dialog: The tool dialog.
Returns : The just added button as a GtkWidget.

gwy_unitool_dialog_add_button_clear ()

GtkWidget*  gwy_unitool_dialog_add_button_clear
                                            (GtkWidget *dialog);

Adds a Unitool-managed "Clear" button to the tool dialog.

dialog: The tool dialog.
Returns : The just added button as a GtkWidget.

gwy_unitool_dialog_add_button_hide ()

GtkWidget*  gwy_unitool_dialog_add_button_hide
                                            (GtkWidget *dialog);

Adds a Unitool-managed "Hide" button to the tool dialog.

dialog: The tool dialog.
Returns : The just added button as a GtkWidget.

gwy_unitool_apply_set_sensitive ()

void        gwy_unitool_apply_set_sensitive (GwyUnitoolState *state,
                                             gboolean sensitive);

Makes the "Apply" button sensitive or insensitive.

state: Tool state.
sensitive: TRUE to make the "Apply" button sensitive.

gwy_unitool_windowname_frame_create ()

GtkWidget*  gwy_unitool_windowname_frame_create
                                            (GwyUnitoolState *state);

Creates a frame displaying the name of currently active data window.

The displayed name automatically changes on tool switch or when the file name changes.

You should not make assumptions about the exact type and structure of the returned widget, its changes are not considered API changes.

state: Tool state.
Returns : The name-displaying frame as a GtkWidget.

gwy_unitool_get_z_average ()

gdouble     gwy_unitool_get_z_average       (GwyDataField *dfield,
                                             gdouble xreal,
                                             gdouble yreal,
                                             gint radius);

Computes average value over a part of data field dfield.

The area is (currently) square with side of 2radius+1. It's not an error if part of it lies outside the data field borders, it's simply not counted in.

dfield: A data field.
xreal: X-coordinate of area center in physical units.
yreal: Y-coordinate of area center in physical units.
radius: Area radius in pixels.
Returns : The average value.

gwy_unitool_update_label ()

void        gwy_unitool_update_label        (GwySIValueFormat *units,
                                             GtkWidget *label,
                                             gdouble value);

Sets the text of a label to display value according to units.

units: Units specification.
label: A label to update (a GtkLabel).
value: A value to show.

gwy_unitool_update_label_no_units ()

void        gwy_unitool_update_label_no_units
                                            (GwySIValueFormat *units,
                                             GtkWidget *label,
                                             gdouble value);

Sets the text of a label to display value according to units, but excludes units showing the number only.

units: Units specification.
label: A label to update (a GtkLabel).
value: A value to show.

Since 1.2.


gwy_unitool_get_selection_or_all ()

gboolean    gwy_unitool_get_selection_or_all
                                            (GwyUnitoolState *state,
                                             gdouble *xmin,
                                             gdouble *ymin,
                                             gdouble *xmax,
                                             gdouble *ymax);

Stores either current selection or complete field in xmin, ymin, xmax, ymax.

Must not be called when the selection layer is not GwyLayerSelect.

state: Tool state.
xmin: Where upper-left corner x coordinate should be stored.
ymin: Where upper-left corner y coordinate should be stored.
xmax: Where lower-right corner x coordinate should be stored.
ymax: Where lower-right corner y coordinate should be stored.
Returns : Whether there is a selection.