## GwyPlainTool 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 ()
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 ()

## Types and Values

enum | GwyPlainToolChanged
| GwyRectSelectionLabels
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_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

## 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”). |

### GwyRectSelectionLabels

    typedef struct _GwyRectSelectionLabels GwyRectSelectionLabels;

### 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);
    };