GwySelection: Gwyddion Library Reference Manual

## GwySelection GwySelection — Data selection base class |

## Functions

gboolean | (*GwySelectionFilterFunc) ()
guint | gwy_selection_get_object_size ()
const gchar * | gwy_selection_get_coord_symbol ()
void | gwy_selection_clear ()
gboolean | gwy_selection_get_object ()
gint | gwy_selection_set_object ()
void | gwy_selection_delete_object ()
gint | gwy_selection_get_data ()
gint | gwy_selection_get_n_objects ()
const gdouble * | gwy_selection_get_data_array ()
void | gwy_selection_set_data ()
guint | gwy_selection_get_max_objects ()
void | gwy_selection_set_max_objects ()
gboolean | gwy_selection_is_full ()
void | gwy_selection_crop ()
void | gwy_selection_move ()
void | gwy_selection_filter ()
void | gwy_selection_move_objects ()
void | gwy_selection_changed ()
gboolean | gwy_selection_get_changed_object ()
void | gwy_selection_finished ()
GwySelection * | gwy_selection_copy ()
void | gwy_selection_assign ()

## Properties

guint | max-objects | Read / Write

## Signals

void | changed | Run First
void | finished | Run First

## Types and Values

| GwySelectionClassPrivate
struct | GwySelection
struct | GwySelectionClass

## Object Hierarchy

        GObject
        ╰── GwySelection
            ├── GwySelectionAxis
            ├── GwySelectionEllipse
            ├── GwySelectionLattice
            ├── GwySelectionLine
            ├── GwySelectionPath
            ├── GwySelectionPoint
            ├── GwySelectionQuad
            ├── GwySelectionRange
            ╰── GwySelectionRectangle

## Implemented Interfaces

GwySelection implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## 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. Method `gwy_selection_get_n_objects()` reports the number of selected objects.

## Functions

### GwySelectionFilterFunc()

    gboolean
    (*GwySelectionFilterFunc) (GwySelection *selection,
                               gint i,
                               gpointer data);

Type of selection filtering function.

#### Parameters

selection | A selection. |
i | Index of object to consider. |
data | User data passed to `gwy_selection_filter()`. |

#### Returns

`TRUE` for objects that should be kept, `FALSE` for objects that should be removed.

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

#### Parameters

selection | A selection. |

#### Returns

The number of coordinates in one selection object.

### gwy_selection_get_coord_symbol()

    const gchar *
    gwy_selection_get_coord_symbol (GwySelection *selection,
                                    gint i);

Gets a symbol of a specific coodinate in a selection.

The returned string is static (or can be treated as such). However, it may not be constant for a given selection. If the selection is along a specific axis, like GwySelectionAxis or GwySelectionRange, the symbols change when the orientation changes.

#### Parameters

selection | A selection. |
i | Index of coordinate within a selection object. |

#### Returns

The symbol as a string with infinite lifetime.

### gwy_selection_clear()

    void
    gwy_selection_clear (GwySelection *selection);

Clears a selection.

#### Parameters

selection | A selection. |

### gwy_selection_get_object()

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

Gets one selection object.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### gwy_selection_get_data()

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

Copies all selection data to given array.

#### Parameters

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`. | [nullable]

#### Returns

The number of objects in the selection. This is *not* the required size of `data` , which must be at least `gwy_selection_get_object_size()` times larger.

### gwy_selection_get_n_objects()

    gint
    gwy_selection_get_n_objects (GwySelection *selection);

Gets the number of objects in a selection.

#### Parameters

selection | A selection. |

#### Returns

The number of objects in the selection. The number of individual coordinates of is `gwy_selection_get_object_size()` times larger.

### gwy_selection_get_data_array()

    const gdouble *
    gwy_selection_get_data_array (GwySelection *selection);

Gets the entire data array of a selection for reading.

The returned array is owned by `selection` and remains valid only until the selection changes.

Use `gwy_selection_get_n_objects()` to obtain the number of objects in the array.

#### Parameters

selection | A selection. |

#### Returns

Data of the entire selection.

### gwy_selection_set_data()

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

Sets selection data.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

selection | A selection. |

#### Returns

`TRUE` when the maximum possible number of objects is selected, `FALSE` otherwise.

### gwy_selection_crop()

    void
    gwy_selection_crop (GwySelection *selection,
                        gdouble xmin,
                        gdouble ymin,
                        gdouble xmax,
                        gdouble ymax);

Limits objects in a selection to a rectangle.

Objects that are fully outside specified rectangle are removed. Objects partially outside may be removed or cut, depending on what makes sense for the specific selection type. If the selection class does not implement this method then all objects are removed.

#### Parameters

selection | A selection. |
xmin | Minimum x-coordinate. |
ymin | Minimum y-coordinate. |
xmax | Maximum x-coordinate. |
ymax | Maximum y-coordinate. |

### gwy_selection_move()

    void
    gwy_selection_move (GwySelection *selection,
                        gdouble vx,
                        gdouble vy);

Moves entire selection in plane by given vector.

If a selection class does not implement this operation the selection remains unchanged. Bult-in selection classes generally implement this operation if it is meaningful. For some, such as GwySelectionLattice, it is not meaningful and moving GwySelectionLattice thus does not do anything.

#### Parameters

selection | A selection. |
vx | Value to add to all x-coordinates. |
vy | Value to add to all y-coordinates. |

### gwy_selection_filter()

    void
    gwy_selection_filter (GwySelection *selection,
                          GwySelectionFilterFunc filter,
                          gpointer data);

Removes selection objects matching certain criteria.

#### Parameters

selection | A selection. |
filter | Function returning `TRUE` for objects that should be kept, `FALSE` for objects that should be removed. | [scope call]
data | User data passed to `filter` . |

### gwy_selection_move_objects()

    void
    gwy_selection_move_objects (GwySelection *selection,
                                const gdouble *v);

Translates cooordinates in a selection according to a repeating pattern.

This function is mainly useful as a helper for GwySelection subclasses. The array `v` must have `gwy_selection_get_object_size()` values. Each coordinate in every object is translated by the corresponding values in `v` .

In order to implement `move()`, a subclass can fill `v` with the corresponding x and y shift pattern and call `gwy_selection_move_objects()` to apply them to all objects.

#### Parameters

selection | A selection. |
v | Array of shifts for individual coodinates |

### gwy_selection_changed()

    void
    gwy_selection_changed (GwySelection *selection,
                           gint i);

Emits "changed" signal on a selection.

#### Parameters

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_get_changed_object()

    gboolean
    gwy_selection_get_changed_object (GwySelection *selection,
                                      gdouble *data);

Gets the previous data of the last changed selection object.

This function can only be meaningfully used in a GwySelection::changed signal handler. Outside it always returns `FALSE`.

If the `hint` parameter of the signal handler is ≥ 0 and the function returns `TRUE`, only a single object has been changed. In such case `data` will be filled with the object coordinates before the change.

If the hint is negative and the function returns `TRUE`, a single object has been deleted. In such case `data` will be filled with the deleted object coordinates.

Otherwise the function returns `FALSE`. In particular, it is possible that `hint` ≥ 0 and the function returns `FALSE`. For instance when an object is added, there are no prior coordinates.

#### Parameters

selection | A selection. |
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 `data` was filled with object coordinates.

### gwy_selection_finished()

    void
    gwy_selection_finished (GwySelection *selection);

Emits "finished" signal on a selection.

#### Parameters

selection | A selection. |

### gwy_selection_copy()

    GwySelection *
    gwy_selection_copy (GwySelection *selection);

Create a new data selection as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

selection | A data selection to duplicate. |

#### Returns

A copy of the data selection.

[transfer full]

### gwy_selection_assign()

    void
    gwy_selection_assign (GwySelection *destination,
                          GwySelection *source);

Makes one data selection equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

#### Parameters

destination | Target data selection. |
source | Source data selection. |

## Types and Values

### GwySelectionClassPrivate

    typedef struct _GwySelectionClassPrivate GwySelectionClassPrivate;

### struct GwySelection

    struct GwySelection;

### struct GwySelectionClass

    struct GwySelectionClass {
        GObjectClass parent_class;
        GwySelectionClassPrivate *priv;

        guint object_size;

        /* TODO: maybe geometrical methods: clamp (the same as crop?), scale */
        void (*crop)(GwySelection *selection,
                     gdouble xmin,
                     gdouble ymin,
                     gdouble xmax,
                     gdouble ymax);
        void (*move)(GwySelection *selection,
                     gdouble xv,
                     gdouble vy);
        const gchar* (*coord_symbol)(GwySelection *selection,
                                     gint i);

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

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.

#### Members

GwySelectionClassPrivate *`priv`; |  |
guint `object_size`; | The number of coordinates that form one selection object. |
`crop`() | Virtual method cropping selection to given rectangle in the plane. |
`move`() | Virtual method moving selection in the plane. |
`coord_symbol`() |  |
`changed`() | The "changed" signal virtual method. |
`finished`() | The "finished" signal virtual method. |

## Property Details

### The `“max-objects”` property

      “max-objects”              guint

Maximum number of objects that can be selected.

Owner: GwySelection

Flags: Read / Write

Allowed values: <= 65536

Default value: 1

## Signal Details

### The `“changed”` signal

    void
    user_function (GwySelection *gwyselection,
                   int           arg1,
                   gpointer      user_data)

The ::changed signal is emitted whenever selection changes.

#### Parameters

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

Flags: Run First

### The `“finished”` signal

    void
    user_function (GwySelection *gwyselection,
                   gpointer      user_data)

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.

#### Parameters

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

Flags: Run First

## See Also

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