GwyVectorLayer: Gwyddion Widgets Library Reference Manual

## GwyVectorLayer GwyVectorLayer — Base class for GwyDataView vector (interactive) layers |

## Functions

gint | (*GwyVectorLayerSearchFunc) ()
#define | gwy_vector_layer_get_selection_type()
GType | gwy_vector_layer_class_get_selection_type ()
GwySelection * | gwy_vector_layer_ensure_selection ()
GwySelection * | gwy_vector_layer_get_selection ()
void | gwy_vector_layer_set_selection ()
gint | gwy_vector_layer_get_focus ()
gboolean | gwy_vector_layer_set_focus ()
gboolean | gwy_vector_layer_get_editable ()
void | gwy_vector_layer_set_editable ()
gboolean | gwy_vector_layer_queue_draw_parent ()
void | gwy_vector_layer_draw ()
PangoLayout * | gwy_vector_layer_ensure_layout ()
GdkModifierType | gwy_vector_layer_get_modifiers ()
gint | gwy_vector_layer_get_current_button ()
gint | gwy_vector_layer_get_current_object ()
void | gwy_vector_layer_set_current_object ()
gint | gwy_vector_layer_update_object ()
gint | gwy_vector_layer_find_nearest ()

## Properties

gboolean | editable | Read / Write
int | focus | Read / Write
GwySelection * | selection | Read / Write

## Signals

void | object-chosen | Run First

## Types and Values

| GwyVectorLayerClassPrivate
struct | GwyVectorLayer
struct | GwyVectorLayerClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GwyDataViewLayer
                ╰── GwyVectorLayer
                    ├── GwyLayerAxis
                    ├── GwyLayerCross
                    ├── GwyLayerEllipse
                    ├── GwyLayerLattice
                    ├── GwyLayerLine
                    ├── GwyLayerPath
                    ├── GwyLayerPoint
                    ├── GwyLayerQuad
                    ╰── GwyLayerRectangle

## Includes

    #include <libgwyui/gwyui.h>

## Description

GwyVectorLayer is a base class for GwyDataViewLayers displaying selections and handling user input. It is a GwyDataView component and it is not normally usable outside of it.

GwyVectorLayer provides two independent means to restrict user interaction with displayed selection: editability and focus. When a layer is set noneditable (see `gwy_vector_layer_set_editable()`), the user cannot modify displayed objects, however "object-chosen" is emitted normally. Focus (see `gwy_vector_layer_set_focus()`) on the other hand limits all possible interactions to a single selection object. It is possible although not very useful to combine both restrictions.

The other methods are rarely useful outside GwyDataView and/or layer implementation.

## Functions

### GwyVectorLayerSearchFunc()

    gint
    (*GwyVectorLayerSearchFunc) (gdouble x,
                                 gdouble y,
                                 gdouble *mindistance,
                                 const gdouble *coords,
                                 gint n,
                                 const gdouble *metric);

Type of coodinate searching function.

This is the type of function passed to `gwy_vector_layer_find_nearest()`.

The number of features is often the same as the number of object in the GwySelection. It does not have to be, however. For example, lines are defined by four coordinates representing the two endpoints. We can have a function looking for the closest line, but we can also have a function looking for the closest endpoint – and for such function the number of features doubles.

The returned value pintpoints a specific feature. Continuing with the lines example, when looking for the closest endpoint, the function must return the index of a specific endpoint (not just the index of the line). In some cases, there may not be a closest feature even if the selection is nonempty because coordinates are considered close only if they are in a specific position with respect to the geometrical shape.

#### Parameters

x | X-coodinate of the point to search. |
y | Y-coodinate of the point to search. |
mindistance | Location holding the current minimum distance, to be updated. |
coords | Coordinates defining the selection geometrical shapes, according to the selection type. |
n | The number of features in the `coords` array. |
metric | A 2×2 metric matrix, possibly `NULL` to use the standard Euclidean metric. |

#### Returns

The index of the closest feature, or -1 if none can be considered close.

### gwy_vector_layer_get_selection_type()

    #define             gwy_vector_layer_get_selection_type(layer)

Gets the selection type of a vector layer.

This is a convenience wrapper around `gwy_vector_layer_class_get_selection_type()`.

#### Parameters

layer | A vector layer. |

### gwy_vector_layer_class_get_selection_type()

    GType
    gwy_vector_layer_class_get_selection_type
                                   (GwyVectorLayerClass *klass);

Returns the selection type of a vector layer class.

Note this is a class method, to get the type from an instance one can use `gwy_vector_layer_get_selection_type()`. To get the type from layer's GType one has to use `g_type_class_peek()`.

#### Parameters

klass | A vector layer class. |

#### Returns

The type of selection used by layers of class `klass` .

### gwy_vector_layer_ensure_selection()

    GwySelection *
    gwy_vector_layer_ensure_selection (GwyVectorLayer *layer);

Ensures a vector layer's selection exists.

If the layer has a selection set the function is identical to `gwy_vector_layer_get_selection()`. Otherwise a selection of appropriate type is created with default properties and returned.

#### Parameters

layer | A vector layer. |

#### Returns

The layer's selection.

[transfer none]

### gwy_vector_layer_get_selection()

    GwySelection *
    gwy_vector_layer_get_selection (GwyVectorLayer *layer);

Returns vector layer's selection object.

#### Parameters

layer | A vector layer. |

#### Returns

The layer's selection (no reference is added), possibly `NULL` if none exists yet.

[nullable]

### gwy_vector_layer_set_selection()

    void
    gwy_vector_layer_set_selection (GwyVectorLayer *layer,
                                    GwySelection *selection);

Sets the vector layer's selection object.

Vector layer subclasses use specific selection types, It is an error to set the wrong selection. See `gwy_vector_layer_class_get_selection_type()` and `gwy_vector_layer_get_selection_type()` for obtaining the type generically. In most cases, however, you work with a concrete layer type and thus know the selection type.

#### Parameters

layer | A vector layer. |
selection | Selection to use, possibly `NULL`. | [nullable]

### gwy_vector_layer_get_focus()

    gint
    gwy_vector_layer_get_focus (GwyVectorLayer *layer);

Gets focused object index.

#### Parameters

layer | A vector image view layer. |

#### Returns

Focued object index, or -1 if no object is focused.

### gwy_vector_layer_set_focus()

    gboolean
    gwy_vector_layer_set_focus (GwyVectorLayer *layer,
                                gint focus);

Focues on one selection object.

When a selection object is focused, it becomes the only one user can interact with. More precisely, "object-chosen" signal is emitted only for this object, and if the layer is editable only this object can be modified by the user.

#### Parameters

layer | A vector image view layer. |
focus | Index of object to focus on, use -1 to unfocus (allow interaction with any object). |

#### Returns

`TRUE` if the object was focused, `FALSE` on failure. Failure can be caused by user currently moving another object, wrong object index, or the feature being unimplemented in `layer` .

### gwy_vector_layer_get_editable()

    gboolean
    gwy_vector_layer_get_editable (GwyVectorLayer *layer);

Gets editability of a vector layer.

#### Parameters

layer | A vector image view layer. |

#### Returns

`TRUE` if layer is edtiable, `FALSE` if it is not editable.

### gwy_vector_layer_set_editable()

    void
    gwy_vector_layer_set_editable (GwyVectorLayer *layer,
                                   gboolean editable);

Sets a vector layer editability.

It is an error to attempt to set a layer non-editabile while it is being edited.

When a layer is set noneditable, the user cannot change the selection. However, "object-chosen" signal is still emitted.

#### Parameters

layer | A vector image view layer. |
editable | `TRUE` to set layer editable, `FALSE` to set it noneditable. |

### gwy_vector_layer_queue_draw_parent()

    gboolean
    gwy_vector_layer_queue_draw_parent (GwyVectorLayer *layer);

Queue redrawing of vector layer's parent image view.

A conveninece function calling `gtk_widget_queue_draw()` on `layer` 's parent widget, provided it exists and is drawable. If there is nothing to redraw the function does nothing.

The return value can be used to decide whether to proceed with other actions which only make sense with a drawable parent widget.

#### Parameters

layer | A vector image view layer. |

#### Returns

Whether redrawing was queued.

### gwy_vector_layer_draw()

    void
    gwy_vector_layer_draw (GwyVectorLayer *layer,
                           cairo_t *cr);

Draws `layer` to a given Cairo context.

#### Parameters

layer | A vector image view layer. |
cr | Cairo context for drawing. |

### gwy_vector_layer_ensure_layout()

    PangoLayout *
    gwy_vector_layer_ensure_layout (GwyVectorLayer *layer);

Obtains a suitable Pango context for drawing text by a vector layer.

This is a helper function for layer implementation. The layout is generally kept around, but in any case it is created if it does not exist yet and the layer has a parent widget. It may be destroyed upon screen change, so layers should not keep it around long-term themselves.

#### Parameters

layer | A vector image view layer. |

#### Returns

A Pango context, or `NULL` if the layer has no parent widget.

[transfer none]

### gwy_vector_layer_get_modifiers()

    GdkModifierType
    gwy_vector_layer_get_modifiers (GwyVectorLayer *layer);

Gets the current modifier state of a vector layer.

This is a helper function for implementations of simple layers which then do not need to query the state themselves.

#### Parameters

layer | A vector image view layer. |

#### Returns

The current modifier state.

### gwy_vector_layer_get_current_button()

    gint
    gwy_vector_layer_get_current_button (GwyVectorLayer *layer);

Gets the current pointer button interacting with a vector layer.

This is a helper function for implementations of layers.

#### Parameters

layer | A vector image view layer. |

#### Returns

The current button (or 0 for none).

### gwy_vector_layer_get_current_object()

    gint
    gwy_vector_layer_get_current_object (GwyVectorLayer *layer);

Gets the index of the currently edited selection object.

#### Parameters

layer | A vector image view layer. |

#### Returns

Index of the selection object, if any. Otherwise -1.

### gwy_vector_layer_set_current_object()

    void
    gwy_vector_layer_set_current_object (GwyVectorLayer *layer,
                                         gint i);

Sets the index of the currently selected selection object.

It also emits the "object-chosen" signal. Usually, the selected object is the one being edited. However, objects can also be selected then the selection is not editable.

#### Parameters

layer | A vector image view layer. |
i | Index of the new current object (or -1 for none). |

### gwy_vector_layer_update_object()

    gint
    gwy_vector_layer_update_object (GwyVectorLayer *layer,
                                    gint i,
                                    const gdouble *xy);

Updates or adds one selection object of a vector layer.

This is mainly a helper function for layer implementation. Index `i` may be negative for appending, as usual. Appending can also be done by passing index equal to the current number of objects. If the maximum number of objects is 1, passing negative `i` is the same as passing 0 (replacing the single object, if it exists). Do not pass negative `i` if such behaviour is not wanted.

#### Parameters

layer | A vector image view layer. |
i | Index of the object to update (or -1). |
xy | New coordinates, according to the layer's selection. |

#### Returns

Index of modified object, usually equal to `i` . Negative value is returned if no object was modified.

### gwy_vector_layer_find_nearest()

    gint
    gwy_vector_layer_find_nearest (GwyVectorLayer *layer,
                                   GwyVectorLayerSearchFunc search,
                                   gint subdivision,
                                   gdouble x,
                                   gdouble y,
                                   gdouble *mindistance);

Finds the closest vector layer feature using a search function.

What type of feature is sought depends on the function `calc_distance` and there can be multiple features on each selection object. The function is usually something like `gwy_math_find_nearest_line()` and works with squared distances. However, it can compute any type of distance as needed.

The search function must accept the coordinate array exactly in the same form as they are in stored the selection data. But, for instance, the selection data of GwySelectionLine are compatible with both `gwy_math_find_nearest_line()` and `gwy_math_find_nearest_point()`.

Focus is taken into account. Meaning, if focus is set only the single focused selection object is considered. Otherwise all objects are considered.

#### Parameters

layer | A vector image view layer. |
search | Function to which calculates the distance to the closest feature. |
subdivision | How many features each selection object is considered to consist of. |
x | X-coodinate of the point to search. |
y | Y-coodinate of the point to search. |
mindistance | Location where to store the minimum distance, or `NULL`. |

#### Returns

Index of the closest feature, or -1 if not found.

## Types and Values

### GwyVectorLayerClassPrivate

    typedef struct _GwyVectorLayerClassPrivate GwyVectorLayerClassPrivate;

### struct GwyVectorLayer

    struct GwyVectorLayer;

### struct GwyVectorLayerClass

    struct GwyVectorLayerClass {
        GwyDataViewLayerClass parent_class;
        GwyVectorLayerClassPrivate *priv;

        GType selection_type;

        /* Signals */
        gboolean (*object_chosen)(GwyVectorLayer *layer,
                                  gint id);

        /* Virtual table */
        void (*draw)(GwyVectorLayer *layer,
                     cairo_t *cr);
        void (*invalidate_object)(GwyVectorLayer *layer,
                                  cairo_region_t *cr,
                                  const gdouble *xy);
        void (*selection_notify)(GwyVectorLayer *layer,
                                 const GParamSpec *spec);
        void (*cancel_editing)(GwyVectorLayer *layer);
        void (*key_press)(GwyVectorLayer *layer,
                          guint keyval);
        void (*key_release)(GwyVectorLayer *layer,
                            guint keyval);
        void (*enter)(GwyVectorLayer *layer,
                      gdouble x,
                      gdouble y);
        void (*motion)(GwyVectorLayer *layer,
                       gdouble x,
                       gdouble y);
        void (*leave)(GwyVectorLayer *layer);
        void (*button_press)(GwyVectorLayer *layer,
                             gdouble x,
                             gdouble y);
        void (*button_release)(GwyVectorLayer *layer,
                               gdouble x,
                               gdouble y);
        gboolean (*set_focus)(GwyVectorLayer *layer,
                              gint i);
    };

Class of vector layers drawn on image views.

Specific vector layers need to implement the methods to provide useful functionality.

#### Members

GwyVectorLayerClassPrivate *`priv`; |  |
GType `selection_type`; |  |
`object_chosen`() |  |
`draw`() | Draw the selection on the parent widget, invoked if selection and parent exist. FIXME: But in future drawing on other Cairo surfaces may be added. |
`invalidate_object`() |  |
`selection_notify`() |  |
`cancel_editing`() | Invoked after a subtantial change such as replacing the selection object entirely. The selection may be `NULL`. The current object is unset by the base class itself. |
`key_press`() | Invoked on pressing a key if a selection exists. |
`key_release`() | Invoked on releasing a key if a selection exists. |
`enter`() | Invoked on pointer entering the layer if a selection exists. |
`motion`() | Invoked on pointer motion if a selection exists. |
`leave`() | Invoked on pointer leaving the layer if a selection exists. |
`button_press`() | Invoked on pressing the first mouse button if a selection exists. |
`button_release`() | Invoked on releasing the first mouse button if a selection exists. |
`set_focus`() |  |

## Property Details

### The `“editable”` property

      “editable”                 gboolean

Whether selection objects are editable.

Owner: GwyVectorLayer

Flags: Read / Write

Default value: TRUE

### The `“focus”` property

      “focus”                    int

The id of focused object, or -1 if all objects are active.

Owner: GwyVectorLayer

Flags: Read / Write

Allowed values: >= -1

Default value: -1

### The `“selection”` property

      “selection”                GwySelection *

Selection object representing the coordinates.

Owner: GwyVectorLayer

Flags: Read / Write

## Signal Details

### The `“object-chosen”` signal

    void
    user_function (GwyVectorLayer *gwyvectorlayer,
                   int             arg1,
                   gpointer        user_data)

The ::object-chosen signal is emitted when user starts interacting with a selection object, even before modifying it. It is emitted even if the layer is not editable, but it is not emitted when focus is set and the user attempts to choose a different object.

#### Parameters

gwyvectorlayer | The GwyVectorLayer which received the signal. |
arg1 | The number (index) of the chosen selection object. |
user_data | user data set when the signal handler was connected. |

Flags: Run First