## GwySelection

GwySelection — Data selection base class

## Synopsis

    #include <libdraw/gwydraw.h>

                        GwySelection;
                        GwySelectionClass;
    #define             gwy_selection_duplicate             (selection)
    guint               gwy_selection_get_object_size       (GwySelection *selection);
    void                gwy_selection_clear                 (GwySelection *selection);
    gboolean            gwy_selection_get_object            (GwySelection *selection,
                                                             gint i,
                                                             gdouble *data);
    gint                gwy_selection_set_object            (GwySelection *selection,
                                                             gint i,
                                                             const gdouble *data);
    void                gwy_selection_delete_object         (GwySelection *selection,
                                                             gint i);
    gint                gwy_selection_get_data              (GwySelection *selection,
                                                             gdouble *data);
    void                gwy_selection_set_data              (GwySelection *selection,
                                                             gint nselected,
                                                             const gdouble *data);
    guint               gwy_selection_get_max_objects       (GwySelection *selection);
    void                gwy_selection_set_max_objects       (GwySelection *selection,
                                                             guint max_objects);
    gboolean            gwy_selection_is_full               (GwySelection *selection);
    void                gwy_selection_changed               (GwySelection *selection,
                                                             gint i);
    void                gwy_selection_finished              (GwySelection *selection);

## Object Hierarchy

      GObject
       +----GwySelection

## Implemented Interfaces

GwySelection implements GwySerializable.

## Properties

      "max-objects"              guint                 : Read / Write
      "object-size"              guint                 : Read

## Signals

      "changed"                                        : Run First
      "finished"                                       : Run First

## Description

GwySelection is an abstract class representing data selections. Particular selection types are defined by vector layer modules.

Selections behave as flat arrays of coordinates. They are however logically split into selection objects (points, lines, rectangles), characteristic for each selection type. For example, to describe a horizontal line one needs only one coordinate, for a point two coordinates are needed, rectangle or arbitrary line need four. `gwy_selection_get_object_size()` can be used to generically determine the number of coordinates used to describe a one selection object.

The number of selection objects in a selection can vary, `gwy_selection_set_max_objects()` sets the maximum possible number. Functions for getting and setting individual selection objects (`gwy_selection_get_object()`, `gwy_selection_set_object()`) or complete selection (`gwy_selection_get_data()`, `gwy_selection_set_data()`) are available. The method `gwy_selection_set_data()` with `NULL` second argument is also used to determine the number of selected object.

## Details

### GwySelection

    typedef struct _GwySelection GwySelection;

The GwySelection struct describes an abstract selection as a collection of coordinates. It should not be accessed directly except selection class implementation.

### GwySelectionClass

    typedef struct {
        guint object_size;

        /* Virtual table */
        void (*clear)(GwySelection *selection);
        gboolean(*get_object)(GwySelection *selection,
                              gint i,
                              gdouble *data);
        gint (*set_object)(GwySelection *selection,
                           gint i,
                           const gdouble *data);
        void (*delete_object)(GwySelection *selection,
                              gint i);
        gint (*get_data)(GwySelection *selection,
                         gdouble *data);
        void (*set_data)(GwySelection *selection,
                         gint nselected,
                         const gdouble *data);
        void (*set_max_objects)(GwySelection *selection,
                                guint max_objects);

        /* Signals */
        void (*changed)(GwySelection *selection,
                        gint i);
        void (*finished)(GwySelection *selection);
    } GwySelectionClass;

The virtual methods and data memebers of GwySelections.

Typically, the only field subclasses set in their class init method is `object_size`. The methods are implemented generically in GwySelection and need not be overriden.

guint `object_size`; | The number of coordinates that form one selection object.
`clear` () | The `gwy_selection_clear()` virtual method.
`get_object` () | The `gwy_selection_get_object()` virtual method.
`set_object` () | The `gwy_selection_set_object()` virtual method.
`delete_object` () | The `gwy_selection_delete_object()` virtual method.
`get_data` () | The `gwy_selection_get_data()` virtual method.
`set_data` () | The `gwy_selection_set_data()` virtual method.
`set_max_objects` () | The `gwy_selection_set_max_objects()` virtual method.
`changed` () | The "changed" signal virtual method.
`finished` () | The "finished" signal virtual method.

### gwy_selection_duplicate()

    #define             gwy_selection_duplicate(selection)

Convenience macro doing `gwy_serializable_duplicate()` with all the necessary typecasting.

`selection` : | An selection to duplicate.

### gwy_selection_get_object_size ()

    guint               gwy_selection_get_object_size       (GwySelection *selection);

Gets the number of coordinates that make up a one selection object.

`selection` : | A selection.
Returns : | The number of coordinates in one selection object.

### gwy_selection_clear ()

    void                gwy_selection_clear                 (GwySelection *selection);

Clears a selection.

`selection` : | A selection.

### gwy_selection_get_object ()

    gboolean            gwy_selection_get_object            (GwySelection *selection,
                                                             gint i,
                                                             gdouble *data);

Gets one selection object.

`selection` : | A selection.
`i` : | Index of object to get.
`data` : | Array to store selection object data to. Object data is an array of coordinates whose precise meaning is defined by particular selection types.
Returns : | `TRUE` if there was such an object and `data` was filled.

### gwy_selection_set_object ()

    gint                gwy_selection_set_object            (GwySelection *selection,
                                                             gint i,
                                                             const gdouble *data);

Sets one selection object.

This method can be also used to append objects (if the maximum number is not exceeded). Since there cannot be holes in the object list, `i` must be then equal to either the number of selected objects or special value -1 meaning append to end.

`selection` : | A selection.
`i` : | Index of object to set.
`data` : | Object selection data. It's an array of coordinates whose precise meaning is defined by particular selection types.
Returns : | The index of actually set object (useful namely when `i` is -1).

### gwy_selection_delete_object ()

    void                gwy_selection_delete_object         (GwySelection *selection,
                                                             gint i);

Deletes a one selection object.

Since there cannot be holes in the object list, the rest of selection objects is moved to close the gap.

`selection` : | A selection.
`i` : | Index of object to delete.

### gwy_selection_get_data ()

    gint                gwy_selection_get_data              (GwySelection *selection,
                                                             gdouble *data);

Gets selection data.

`selection` : | A selection.
`data` : | Array to store selection data to. Selection data is an array of coordinates whose precise meaning is defined by particular selection types. It may be `NULL`.
Returns : | The number of selected objects. This is *not* the required size of `data`, which must be at least `gwy_selection_get_object_size()` times larger.

### gwy_selection_set_data ()

    void                gwy_selection_set_data              (GwySelection *selection,
                                                             gint nselected,
                                                             const gdouble *data);

Sets selection data.

`selection` : | A selection.
`nselected` : | The number of selected objects.
`data` : | Selection data, that is an array `nselected` * `gwy_selection_get_object_size()` long with selected object coordinates.

### gwy_selection_get_max_objects ()

    guint               gwy_selection_get_max_objects       (GwySelection *selection);

Gets the maximum number of selected objects.

`selection` : | A selection.
Returns : | The maximum number of selected objects;

### gwy_selection_set_max_objects ()

    void                gwy_selection_set_max_objects       (GwySelection *selection,
                                                             guint max_objects);

Sets the maximum number of objects allowed to select.

When selection reaches this number of selected objects, it emits "finished" signal.

`selection` : | A selection.
`max_objects` : | The maximum number of objects allowed to select. Note particular selection types may allow only specific values.

### gwy_selection_is_full ()

    gboolean            gwy_selection_is_full               (GwySelection *selection);

Checks whether the maximum number of objects is selected.

`selection` : | A selection.
Returns : | `TRUE` when the maximum possible number of objects is selected, `FALSE` otherwise.

### gwy_selection_changed ()

    void                gwy_selection_changed               (GwySelection *selection,
                                                             gint i);

Emits "changed" signal on a selection.

`selection` : | A selection.
`i` : | Index of object that changed. Use -1 when not applicable, e.g., when complete selection was changed, cleared, or truncated.

### gwy_selection_finished ()

    void                gwy_selection_finished              (GwySelection *selection);

Emits "finished" signal on a selection.

`selection` : | A selection.

## Property Details

### The `"max-objects"` property

      "max-objects"              guint                 : Read / Write

Maximum number of objects that can be selected.

Allowed values: <= 1024

Default value: 1

### The `"object-size"` property

      "object-size"              guint                 : Read

Number of coordinates in one selection object.

Allowed values: <= 1024

Default value: 0

## Signal Details

### The `"changed"` signal

    void                user_function                      (GwySelection *gwyselection,
                                                            gint          arg1,
                                                            gpointer      user_data)         : Run First

The ::changed signal is emitted whenever selection changes.

`gwyselection` : | The GwySelection which received the signal.
`arg1` : | Changed object position hint. If the value is nonnegative, only this object has changed. If it's negative, the selection has to be treated as completely changed.
`user_data` : | user data set when the signal handler was connected.

### The `"finished"` signal

    void                user_function                      (GwySelection *gwyselection,
                                                            gpointer      user_data)         : Run First

The ::finished signal is emitted when selection is finished.

What exactly finished means is defined by corresponding GwyVectorLayer, but normally it involves user stopped changing a selection object. Selections never emit this signal themselves.

`gwyselection` : | The GwySelection which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

GwyVectorLayer -- uses GwySelection for selections, GwyGraphArea -- uses GwySelection for selections