GwySelection (HEAD)

GwySelection — Data selection base class

Functions

gboolean	(*GwySelectionFilterFunc) ()
#define	gwy_selection_duplicate()
#define	gwy_selection_assign()
guint	gwy_selection_get_object_size ()
void	gwy_selection_clear ()
gboolean	gwy_selection_get_object ()
gint	gwy_selection_set_object ()
void	gwy_selection_delete_object ()
gint	gwy_selection_get_data ()
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_changed ()
void	gwy_selection_finished ()

Properties

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

Signals

void	changed	Run First
void	finished	Run First

Types and Values

struct	GwySelection
struct	GwySelectionClass

Object Hierarchy

    GObject
    ╰── GwySelection

Implemented Interfaces

GwySelection implements GwySerializable.

Includes

#include <libdraw/gwydraw.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. The method gwy_selection_set_data() with NULL second argument is also used to determine the number of selected object.

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.

Since: 2.16

gwy_selection_duplicate()

#define             gwy_selection_duplicate(selection)

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

Parameters

selection

An selection to duplicate.

gwy_selection_assign()

#define             gwy_selection_assign(dest, source)

Convenience macro making one selection identical to another.

This is just a gwy_serializable_clone() wrapper with all the necessary typecasting.

Note that it also copies properties like “max-objects”, which may or may not be wanted.

Parameters

dest	Target selection.
source	Source selection.

Since: 2.52

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

Gets selection data.

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.

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.

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.

Since: 2.16

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.

Since: 2.43

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.
data	User data passed to filter .

Since: 2.16

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

void
gwy_selection_finished (GwySelection *selection);

Emits "finished" signal on a selection.

Parameters

selection

A selection.

Types and Values

struct GwySelection

struct GwySelection;

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

Members

struct GwySelectionClass

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

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

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.

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

The “object-size” property

  “object-size”              guint

Number of coordinates in one selection object.

Owner: GwySelection

Flags: Read

Allowed values: <= 1024

Default value: 0

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