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

GwyPlainTool (HEAD)

GwyPlainTool — Base class for simple tools

Functions

GType	gwy_plain_tool_check_layer_type ()
void	gwy_plain_tool_connect_selection ()
void	gwy_plain_tool_ensure_layer ()
const gchar *	gwy_plain_tool_set_selection_key ()
GtkWidget *	gwy_plain_tool_add_clear_button ()
gdouble	gwy_plain_tool_get_z_average ()
void	gwy_plain_tool_enable_object_deletion ()
void	gwy_plain_tool_hold_selection ()
void	gwy_plain_tool_enable_selection_holding ()
GwyRectSelectionLabels *	gwy_rect_selection_labels_new ()
GtkWidget *	gwy_rect_selection_labels_get_table ()
void	gwy_rect_selection_labels_select ()
gboolean	gwy_rect_selection_labels_fill ()
void	gwy_plain_tool_log_add ()
void	gwy_plain_tool_add_param_table ()

Types and Values

enum	GwyPlainToolChanged
enum	GwyHoldSelectionFlags
	GwyRectSelectionLabels
	GwyToolHeldSelection
struct	GwyPlainTool
struct	GwyPlainToolClass

Object Hierarchy

    GObject
    ╰── GwyTool
        ╰── GwyPlainTool

Includes

#include <app/gwyapp.h>

Description

Functions

gwy_plain_tool_check_layer_type ()

GType
gwy_plain_tool_check_layer_type (GwyPlainTool *plain_tool,
                                 const gchar *name);

Checks for a required layer type.

If the layer exists, its GType is returned. If it does not exist, zero is returned and a warning message is added to the tool dialog. In addition, it sets init_failed to TRUE.

Therefore, this function should be called early in tool instance initialization and it should not be called again once it fails.

Parameters

plain_tool	A plain tool.
name	Layer type name (e.g. `"GwyLayerPoint"`).

Returns

The type of the layer, or 0 on failure.

gwy_plain_tool_connect_selection ()

void
gwy_plain_tool_connect_selection (GwyPlainTool *plain_tool,
                                  GType layer_type,
                                  const gchar *bname);

Sets up a plain tool to automatically manage layer selection.

When layer_type is 0 and bname NULL, plain tool stops automatically managing selection (hopefully).

This method performs gwy_plain_tool_ensure_layer() and gwy_plain_tool_set_selection_key(), connecting to the selection and making sure the selection field always points to the correct selection object (or is NULL).

The selection_changed method of GwyPlainToolClass is only invoked for a tool instance once this method was called to set up the selection tracking.

Parameters

plain_tool	A plain tool.
layer_type	Layer type. Use `gwy_plain_tool_check_layer_type()` in tool instance initialization to check for layer types.
bname	Selection key base name, for example `"line"`.

gwy_plain_tool_ensure_layer ()

void
gwy_plain_tool_ensure_layer (GwyPlainTool *plain_tool,
                             GType layer_type);

Makes sure a plain tool's layer is of the correct type.

This is a low-level function, normally you would use gwy_plain_tool_connect_selection().

Parameters

plain_tool	A plain tool.
layer_type	Layer type. Use `gwy_plain_tool_check_layer_type()` in tool instance initialization to check for layer types.

gwy_plain_tool_set_selection_key ()

const gchar *
gwy_plain_tool_set_selection_key (GwyPlainTool *plain_tool,
                                  const gchar *bname);

Constructs selection key from data key and sets it on the vector layer.

This is a low-level function, normally you would use gwy_plain_tool_connect_selection().

Parameters

plain_tool	A plain tool.
bname	Selection key base name, for example `"line"`.

Returns

The full key (as a layer-owned string).

gwy_plain_tool_add_clear_button ()

GtkWidget *
gwy_plain_tool_add_clear_button (GwyPlainTool *plain_tool);

Adds a `Clear' button to a plain tool.

This button works with automatically managed selection (see gwy_plain_tool_connect_selection()). If you want to manage selection yourself add the button with gtk_dialog_add_button().

Parameters

plain_tool

A plain tool.

Returns

The button widget.

gwy_plain_tool_get_z_average ()

gdouble
gwy_plain_tool_get_z_average (GwyDataField *data_field,
                              const gdouble *point,
                              gint radius);

Computes average value over a part of data field dfield .

It is not an error if part of it lies outside the data field borders (it is simply not counted in), however the intersection have to be nonempty.

Parameters

data_field	A data field.
point	Real X and Y-coordinate of area center in physical units.
radius	Area radius in pixels, 1 means a signle pixel. The actual radius passed to `gwy_data_field_circular_area_extract()` is `radius` -0.5.

Returns

The average value.

gwy_plain_tool_enable_object_deletion ()

void
gwy_plain_tool_enable_object_deletion (GwyPlainTool *plain_tool,
                                       GtkTreeView *treeview);

Enables deletion of selection objects by presssing Delete in a tree view diplaying them.

Parameters

plain_tool	A plain tool.
treeview	A tree view that displays selection objects in order, each row corresponding to one selection object.

Since: 2.7

gwy_plain_tool_hold_selection ()

void
gwy_plain_tool_hold_selection (GwyPlainTool *plain_tool,
                               GwyHoldSelectionFlags hold_flags);

Possibly transfers the selection to a new image upon plain tool data switch.

This function should be called from data_switched() class method in a tool after setting up the layer and selection. If the selection should be transferred to the new image according to hold_flags the previous (held) selection will replace whatever selection might be there currently. Otherwise the new image's selection is preserved (and in fact held itself).

Selection holding must be enabled in tool instance init function using gwy_plain_tool_enable_selection_holding().

Parameters

plain_tool	A plain tool.
hold_flags	Flags controlling when the selection is held (transferred to another image).

Since: 2.63

gwy_plain_tool_enable_selection_holding ()

void
gwy_plain_tool_enable_selection_holding
                               (GwyPlainTool *plain_tool);

Enables selection holding for a plain tool.

Selection holding means that, if certain conditions are satisfied, upon data switch the tool transfers the current selection to the new image, replacing whatever selection might be there.

This function should be called from the instance init function.

Holding is currently unsupported for tools which use multiple selection types.

Parameters

plain_tool

A plain tool.

Since: 2.63

gwy_rect_selection_labels_new ()

GwyRectSelectionLabels *
gwy_rect_selection_labels_new (gboolean none_is_full,
                               GCallback callback,
                               gpointer cbdata);

Creates a table displaying rectangular selection information.

The returned object will destroy itself when the table is destroyed.

Parameters

none_is_full	`TRUE` to treat unselected state as full data selected.
callback	Callback to call when the selection is edited.
cbdata	Data to pass to `callback` (as the first argument).

Returns

The newly created rectangular selection information, as an opaque pointer. The table widget can be obtained with gwy_rect_selection_labels_get_table().

gwy_rect_selection_labels_get_table ()

GtkWidget *
gwy_rect_selection_labels_get_table (GwyRectSelectionLabels *rlabels);

Gets the table widget of a rectangular selection information.

Parameters

rlabels

Rectangular selection information table.

Returns

The table as a GtkWidget.

gwy_rect_selection_labels_select ()

void
gwy_rect_selection_labels_select (GwyRectSelectionLabels *rlabels,
                                  GwySelection *selection,
                                  GwyDataField *dfield);

Updates selection data using rectangular selection information table.

Parameters

rlabels	Rectangular selection information table.
selection	A rectangular selection to fill information into.
dfield	A data field to use for real/pixel coordinate transforms.

gwy_rect_selection_labels_fill ()

gboolean
gwy_rect_selection_labels_fill (GwyRectSelectionLabels *rlabels,
                                GwySelection *selection,
                                GwyDataField *dfield,
                                gdouble *selreal,
                                gint *selpix);

Updates rectangular selection info display.

It is possible to pass NULL dfield but non-NULL selection . This can lead to TRUE return value (if the selection is non-empty), but the labels will be still cleared as there is no way to convert between real and pixel coordinates.

Parameters

rlabels	Rectangular selection info table.
selection	A rectangular selection to fill information from. It can be `NULL` to clear the labels.
dfield	A data field to use for real/pixel coordinate transforms. It can be `NULL` to clear the labels.
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.

gwy_plain_tool_log_add ()

void
gwy_plain_tool_log_add (GwyPlainTool *plain_tool);

Logs a data modification operation of a plain tool.

This is a convenience wrapper for gwy_app_channel_log_add(), setting automatically the container, data id and function name from the tool. It can only be used for simple data modification operations in which the source and target ids are the same. In more complex cases you have to use gwy_app_channel_log_add() directly.

Parameters

plain_tool

A plain tool.

Since: 2.35

gwy_plain_tool_add_param_table ()

void
gwy_plain_tool_add_param_table (GwyPlainTool *plain_tool,
                                GwyParamTable *partable);

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

See gwy_dialog_add_param_table() for details.

Parameters

plain_tool	A plain tool.
partable	Parameter table to add.

Since: 2.62

Types and Values

enum GwyPlainToolChanged

The type of pending changes that accumulated during tool inactivity.

Members

GWY_PLAIN_TOOL_CHANGED_DATA	Channel data field was changed.
GWY_PLAIN_TOOL_CHANGED_MASK	Mask data field was changed.
GWY_PLAIN_TOOL_CHANGED_SHOW	Presentation data field was changed.
GWY_PLAIN_TOOL_CHANGED_SELECTION	Selection was changed.
GWY_PLAIN_TOOL_FINISHED_SELECTION	Selection was finished (that is emitted “finished”).

enum GwyHoldSelectionFlags

Flags controlling the selection holding behaviour of tools.

Although any combination of flags is valid, this is mainly so that user's choice is not reset. For any holding to be done at all the GWY_HOLD_SELECTION_HOLD flag must be set. If it is unset then GWY_HOLD_SELECTION_OVERWRITE and GWY_HOLD_SELECTION_CLEAR do not matter. Similarly, for GWY_HOLD_SELECTION_CLEAR has any effect only if overwriting is enabled by setting GWY_HOLD_SELECTION_OVERWRITE.

Members

GWY_HOLD_SELECTION_HOLD	Selections are held (transferred to the new image).
GWY_HOLD_SELECTION_OVERWRITE	Existing selections on the new image is replaced.
GWY_HOLD_SELECTION_CLEAR	If the current image has no selection the selection on the new image is cleared.

Since: 2.63

GwyRectSelectionLabels

typedef struct _GwyRectSelectionLabels GwyRectSelectionLabels;

GwyToolHeldSelection

typedef struct _GwyToolHeldSelection GwyToolHeldSelection;

struct GwyPlainTool

struct GwyPlainTool;

struct GwyPlainToolClass

struct GwyPlainToolClass {
    GwyToolClass parent_class;

    void (*data_changed)(GwyPlainTool *plain_tool);
    void (*mask_changed)(GwyPlainTool *plain_tool);
    void (*show_changed)(GwyPlainTool *plain_tool);
    void (*selection_changed)(GwyPlainTool *plain_tool,
                              gint hint);
    void (*selection_finished)(GwyPlainTool *plain_tool);

    void (*reserved1)(void);
    void (*reserved2)(void);
    void (*reserved3)(void);
};