## GwyVectorLayer

GwyVectorLayer — Base class for GwyDataView vector (interactive) layers

## Synopsis

    #include <libgwydgets/gwydgets.h>

                        GwyVectorLayer;
                        GwyVectorLayerClass;
    GType               gwy_vector_layer_class_get_selection_type
                                                            (GwyVectorLayerClass *klass);
    #define             gwy_vector_layer_get_selection_type (layer)
    void                gwy_vector_layer_set_selection_key  (GwyVectorLayer *layer,
                                                             const gchar *key);
    const gchar*        gwy_vector_layer_get_selection_key  (GwyVectorLayer *layer);
    GwySelection*       gwy_vector_layer_ensure_selection   (GwyVectorLayer *layer);
    gint                gwy_vector_layer_get_focus          (GwyVectorLayer *layer);
    gboolean            gwy_vector_layer_set_focus          (GwyVectorLayer *layer,
                                                             gint focus);
    gboolean            gwy_vector_layer_get_editable       (GwyVectorLayer *layer);
    void                gwy_vector_layer_set_editable       (GwyVectorLayer *layer,
                                                             gboolean editable);
    void                gwy_vector_layer_draw               (GwyVectorLayer *layer,
                                                             GdkDrawable *drawable,
                                                             GwyRenderingTarget target);
    gboolean            gwy_vector_layer_button_press       (GwyVectorLayer *layer,
                                                             GdkEventButton *event);
    gboolean            gwy_vector_layer_button_release     (GwyVectorLayer *layer,
                                                             GdkEventButton *event);
    gboolean            gwy_vector_layer_motion_notify      (GwyVectorLayer *layer,
                                                             GdkEventMotion *event);
    gboolean            gwy_vector_layer_key_press          (GwyVectorLayer *layer,
                                                             GdkEventKey *event);
    gboolean            gwy_vector_layer_key_release        (GwyVectorLayer *layer,
                                                             GdkEventKey *event);
    void                gwy_vector_layer_object_chosen      (GwyVectorLayer *layer,
                                                             gint id);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GwyDataViewLayer
                         +----GwyVectorLayer

## Properties

      "editable"                 gboolean              : Read / Write
      "focus"                    gint                  : Read / Write
      "selection-key"            gchar*                : Read / Write

## Signals

      "object-chosen"                                  : Run First

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

The layer takes the selection to display from its parent GwyDataView's container. The key under which the selection is found is set with `gwy_vector_layer_set_selection_key()`. The selection either can be put there beforehand (the corresponding selection type can be obtained with `gwy_vector_layer_class_get_selection_type()`) or `gwy_vector_layer_ensure_selection()` can be used to create it if it doesn't exist.

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.

## Details

### GwyVectorLayer

    typedef struct _GwyVectorLayer GwyVectorLayer;

### GwyVectorLayerClass

    typedef struct {
        GwyDataViewLayerClass parent_class;

        GType selection_type;

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

        /* Virtual table */
        void (*draw)(GwyVectorLayer *layer,
                     GdkDrawable *drawable,
                     GwyRenderingTarget target);
        gboolean (*button_press)(GwyVectorLayer *layer,
                                 GdkEventButton *event);
        gboolean (*button_release)(GwyVectorLayer *layer,
                                   GdkEventButton *event);
        gboolean (*motion_notify)(GwyVectorLayer *layer,
                                  GdkEventMotion *event);
        gboolean (*key_press)(GwyVectorLayer *layer,
                              GdkEventKey *event);
        gboolean (*key_release)(GwyVectorLayer *layer,
                                GdkEventKey *event);
        gboolean (*set_focus)(GwyVectorLayer *layer,
                              gint object);

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

### 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_class_selection_type()`. To get the type from layer's GType one has to use `g_type_class_peek()`.

`klass` : | A vector layer class.
Returns : | The type of selection used by layers of class `klass`.

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

`layer` : | A vector layer.

### gwy_vector_layer_set_selection_key ()

    void                gwy_vector_layer_set_selection_key  (GwyVectorLayer *layer,
                                                             const gchar *key);

Sets the selection object to use by a vector layer.

`layer` : | A vector layer.
`key` : | Container string key identifying the selection object.

### gwy_vector_layer_get_selection_key ()

    const gchar*        gwy_vector_layer_get_selection_key  (GwyVectorLayer *layer);

Gets the key identifying selection this vector layer displays.

`layer` : | A vector layer.
Returns : | The string key, or `NULL` if it isn't set.

### gwy_vector_layer_ensure_selection ()

    GwySelection*       gwy_vector_layer_ensure_selection   (GwyVectorLayer *layer);

Ensures a vector layer's selection exist in data container.

This method can be called only when layer is plugged into a data view and it has a selection key set. If the data container contains a selection under the specified key the selection is returned. If there is none, a selection of appropriate type is created and put to the container first.

Provided the above conditions are met this method is suitable for just obtaining the selection object a vector layer uses too.

`layer` : | A vector layer.
Returns : | The layer's selection (no reference is added).

### gwy_vector_layer_get_focus ()

    gint                gwy_vector_layer_get_focus          (GwyVectorLayer *layer);

Gets focused object index.

`layer` : | A vector data 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.

`layer` : | A vector data 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.

`layer` : | A vector data 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.

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

### gwy_vector_layer_draw ()

    void                gwy_vector_layer_draw               (GwyVectorLayer *layer,
                                                             GdkDrawable *drawable,
                                                             GwyRenderingTarget target);

Draws `layer` on given drawable (which should be a GwyDataView window).

`layer` : | A vector data view layer.
`drawable` : | A drawable to draw on.
`target` : | Rendering target.

### gwy_vector_layer_button_press ()

    gboolean            gwy_vector_layer_button_press       (GwyVectorLayer *layer,
                                                             GdkEventButton *event);

Sends a mouse button press event to a layer.

This method primarily exists for GwyDataView to forward events to layers. You should rarely need it.

`layer` : | A vector data view layer.
`event` : | A Gdk mouse button event.
Returns : | `TRUE` if the event was handled. In practice, it returns `FALSE`.

### gwy_vector_layer_button_release ()

    gboolean            gwy_vector_layer_button_release     (GwyVectorLayer *layer,
                                                             GdkEventButton *event);

Sends a mouse button release event to a layer.

This method primarily exists for GwyDataView to forward events to layers. You should rarely need it.

`layer` : | A vector data view layer.
`event` : | A Gdk mouse button event.
Returns : | `TRUE` if the event was handled. In practice, it returns `FALSE`.

### gwy_vector_layer_motion_notify ()

    gboolean            gwy_vector_layer_motion_notify      (GwyVectorLayer *layer,
                                                             GdkEventMotion *event);

Sends a mouse pointer motion notification event to a layer.

This method primarily exists for GwyDataView to forward events to layers. You should rarely need it.

`layer` : | A vector data view layer.
`event` : | A Gdk mouse pointer motion notification event. It can be a hint.
Returns : | `TRUE` if the event was handled. In practice, it returns `FALSE`.

### gwy_vector_layer_key_press ()

    gboolean            gwy_vector_layer_key_press          (GwyVectorLayer *layer,
                                                             GdkEventKey *event);

Sends a key press event to a layer.

This method primarily exists for GwyDataView to forward events to layers. You should rarely need it.

`layer` : | A vector data view layer.
`event` : | A Gdk key event.
Returns : | `TRUE` if the event was handled. In practice, it returns `FALSE`.

### gwy_vector_layer_key_release ()

    gboolean            gwy_vector_layer_key_release        (GwyVectorLayer *layer,
                                                             GdkEventKey *event);

Sends a key release event to a layer.

This method primarily exists for GwyDataView to forward events to layers. You should rarely need it.

`layer` : | A vector data view layer.
`event` : | A Gdk key event.
Returns : | `TRUE` if the event was handled. In practice, it returns `FALSE`.

### gwy_vector_layer_object_chosen ()

    void                gwy_vector_layer_object_chosen      (GwyVectorLayer *layer,
                                                             gint id);

Emits "object-chosen" signal on a vector layer.

This function is primarily intended for layer implementations.

`layer` : | A vector data view layer.
`id` : | Index of the chosen object.

## Property Details

### The `"editable"` property

      "editable"                 gboolean              : Read / Write

Whether selection objects are editable.

Default value: TRUE

### The `"focus"` property

      "focus"                    gint                  : Read / Write

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

Allowed values: >= -1

Default value: -1

### The `"selection-key"` property

      "selection-key"            gchar*                : Read / Write

The key identifying selection object in data container.

Default value: NULL

## Signal Details

### The `"object-chosen"` signal

    void                user_function                      (GwyVectorLayer *gwyvectorlayer,
                                                            gint            arg1,
                                                            gpointer        user_data)           : Run First

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.

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

## See Also

Standard vector layers