## GwyPlainTool

GwyPlainTool — Base class for simple tools

## Synopsis

    #include <app/gwyapp.h>

    enum                GwyPlainToolChanged;
                        GwyPlainTool;
                        GwyPlainToolClass;
    GType               gwy_plain_tool_check_layer_type     (GwyPlainTool *plain_tool,
                                                             const gchar *name);
    void                gwy_plain_tool_connect_selection    (GwyPlainTool *plain_tool,
                                                             GType layer_type,
                                                             const gchar *bname);
    void                gwy_plain_tool_ensure_layer         (GwyPlainTool *plain_tool,
                                                             GType layer_type);
    const gchar*        gwy_plain_tool_set_selection_key    (GwyPlainTool *plain_tool,
                                                             const gchar *bname);
    GtkWidget*          gwy_plain_tool_add_clear_button     (GwyPlainTool *plain_tool);
    gdouble             gwy_plain_tool_get_z_average        (GwyDataField *data_field,
                                                             const gdouble *point,
                                                             gint radius);
    void                gwy_plain_tool_enable_object_deletion
                                                            (GwyPlainTool *plain_tool,
                                                             GtkTreeView *treeview);
                        GwyRectSelectionLabels;
    GwyRectSelectionLabels* gwy_rect_selection_labels_new   (gboolean none_is_full,
                                                             GCallback callback,
                                                             gpointer cbdata);
    GtkWidget*          gwy_rect_selection_labels_get_table (GwyRectSelectionLabels *rlabels);
    void                gwy_rect_selection_labels_select    (GwyRectSelectionLabels *rlabels,
                                                             GwySelection *selection,
                                                             GwyDataField *dfield);
    gboolean            gwy_rect_selection_labels_fill      (GwyRectSelectionLabels *rlabels,
                                                             GwySelection *selection,
                                                             GwyDataField *dfield,
                                                             gdouble *selreal,
                                                             gint *selpix);

## Object Hierarchy

      GObject
       +----GwyTool
             +----GwyPlainTool

## Description

## Details

### enum GwyPlainToolChanged

    typedef enum {
        GWY_PLAIN_TOOL_CHANGED_DATA       = 1 << 0,
        GWY_PLAIN_TOOL_CHANGED_MASK       = 1 << 1,
        GWY_PLAIN_TOOL_CHANGED_SHOW       = 1 << 2,
        GWY_PLAIN_TOOL_CHANGED_SELECTION  = 1 << 3,
        GWY_PLAIN_TOOL_FINISHED_SELECTION = 1 << 4,
    } GwyPlainToolChanged;

The type of pending changes that accumulated during tool inactivity.

`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").

### GwyPlainTool

    typedef struct _GwyPlainTool GwyPlainTool;

### GwyPlainToolClass

    typedef struct {
        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);
    } GwyPlainToolClass;

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

`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.

`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()`.

`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()`.

`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()`.

`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.

`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.

`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

### GwyRectSelectionLabels

    typedef struct _GwyRectSelectionLabels GwyRectSelectionLabels;

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

`none_is_full` : | `TRUE` to tread 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.

`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);

`rlabels` : |
`selection` : |
`dfield` : |

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

`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.