![]() | ![]() | Gwyddion Application Library Reference Manual | ![]() |
---|
unitoolunitool — Universal tool template. |
#define GWY_UNITOOL_RESPONSE_UNSELECT enum GwyUnitoolUpdateType; GwyUnitoolSlots; GwyUnitoolRectLabels; 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); gint gwy_unitool_rect_info_table_setup (GwyUnitoolRectLabels *rinfo, GtkTable *table, gint col, gint row); gboolean gwy_unitool_rect_info_table_fill (GwyUnitoolState *state, GwyUnitoolRectLabels *rinfo, gdouble *selreal, gint *selpix);
#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;
Reason why dialog_update() tool function was called.
GWY_UNITOOL_UPDATED_SELECTION | Selection have changed. |
GWY_UNITOOL_UPDATED_DATA | Data have changed. |
GWY_UNITOOL_UPDATED_CONTROLS | Unused. |
typedef struct { GType layer_type; GwyUnitoolFunc layer_setup; GwyUnitoolCreateFunc dialog_create; GwyUnitoolUpdateFunc dialog_update; GwyUnitoolFunc dialog_abandon; GwyUnitoolFunc apply; GwyUnitoolResponseFunc response; } GwyUnitoolSlots;
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 { GtkWidget *xreal; GtkWidget *yreal; GtkWidget *wreal; GtkWidget *hreal; GtkWidget *xpix; GtkWidget *ypix; GtkWidget *wpix; GtkWidget *hpix; GtkWidget *rwidget1; GtkWidget *rwidget2; GtkWidget *rwidget3; GtkWidget *rwidget4; gboolean unselected_is_full; gboolean reserved1; gboolean reserved2; } GwyUnitoolRectLabels;
Widgets and flags for rectangular selection display.
You will probably ever need to access the flag fields only.
GtkWidget *xreal; | Selection x-origin in physical units widget. |
GtkWidget *yreal; | Selection y-origin in physical units widget. |
GtkWidget *wreal; | Selection width in physical units widget. |
GtkWidget *hreal; | Selection height in physical units widget. |
GtkWidget *xpix; | Selection x-origin in pixels widget. |
GtkWidget *ypix; | Selection y-origin in pixels widget. |
GtkWidget *wpix; | Selection width in pixels widget. |
GtkWidget *hpix; | Selection height in pixels widget. |
GtkWidget *rwidget1; | Reserved. |
GtkWidget *rwidget2; | Reserved. |
GtkWidget *rwidget3; | Reserved. |
GtkWidget *rwidget4; | Reserved. |
gboolean unselected_is_full; | If TRUE, no selection is displayed as full data range, if FALSE, labels are cleared when nothing is selected. |
gboolean reserved1; | Reserved. |
gboolean reserved2; | Reserved. |
Since 1.6
typedef struct { 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; } 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.
gpointer user_data; | Where you should pointer to particular tool state data. |
GwyUnitoolSlots *func_slots; | Pointer to function slots for the particular tool. |
GwyDataWindow *data_window; | The data window the tool is active for. |
GwyVectorLayer *layer; | The layer the tool is using. |
gboolean is_visible; | TRUE if the dialog is visible, FALSE if it's hidden. |
GtkWidget *windowname; | The name of data_window. |
GtkWidget *dialog; | The tool dialog. |
GwySIValueFormat *coord_format; | Format good for coordinate representation (to be used in gwy_unitool_update_label() for coordinates). |
GwySIValueFormat *value_format; | Format good for value representation (to be used in gwy_unitool_update_label() for values). |
gboolean apply_doesnt_close; | When set to TRUE "Apply" button doesn't close (hide) the tool dialog. |
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.
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. |
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. |
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.
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. |
gint gwy_unitool_rect_info_table_setup (GwyUnitoolRectLabels *rinfo, GtkTable *table, gint col, gint row);
Places widgets displaying rectangular selection information to a table.
This function initializes the GwyUnitoolRectLabels widgets fields and thus must be used before gwy_unitool_rect_info_table_fill().
rinfo : | A rectangular selection display data. |
table : | Table to place the widgets to. |
col : | Starting column in table. |
row : | Starting row in table. |
Returns : | The number of rows taken. |
Since 1.6
gboolean gwy_unitool_rect_info_table_fill (GwyUnitoolState *state, GwyUnitoolRectLabels *rinfo, gdouble *selreal, gint *selpix);
Updates rectangular selection info display.
state : | Tool state. |
rinfo : | A rectangular selection display data. |
selreal : | If not NULL, must be an array of size at least 4 and will be filled with selection data xmin, ymin, xmax, ymax in physical units. |
selpix : | If not NULL, must be an array of size at least 4 and will be filled with selection data xmin, ymin, xmax, ymax in pixels. |
Returns : | TRUE if a selection is present, FALSE otherwise. |
Since 1.6
<< undo | wait >> |