![]() | ![]() | ![]() | Gwyddion Application Library Reference Manual | ![]() |
---|
unitool — Universal tool template.
#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); gboolean gwy_unitool_get_selection_or_all (GwyUnitoolState *state, gdouble *xmin, gdouble *ymin, gdouble *xmax, gdouble *ymax);
#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.
typedef enum { GWY_UNITOOL_UPDATED_SELECTION, GWY_UNITOOL_UPDATED_DATA, GWY_UNITOOL_UPDATED_CONTROLS } GwyUnitoolUpdateType;
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. |
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.
void (*GwyUnitoolFunc) (GwyUnitoolState *state);
General Unitool slot function signature.
state: | Tool state. |
GtkWidget* (*GwyUnitoolCreateFunc) (GwyUnitoolState *state);
Dialog constructor slot function signature.
state: | Tool state. |
Returns : | The newly created dialog. |
void (*GwyUnitoolResponseFunc) (GwyUnitoolState *state, gint response);
Extra dialog response handler slot function signature.
state: | Tool state. |
response: | The tool dialog response. |
void (*GwyUnitoolUpdateFunc) (GwyUnitoolState *state, GwyUnitoolUpdateType reason);
Tool update slot function signature.
state: | Tool state. |
reason: | Update reason. |
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. |
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. |
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. |
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. |
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. |
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.
state: | Tool state. |
Returns : | The name-displaying frame as a GtkWidget. |
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. |
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. |
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. |
<< menu | wait >> |