SelectionRegion

SelectionRegion is a component for selecting regions of various geometries.

It is not intended for direct use, but could be extended to create custom selection regions.

The region can be drawn by the user using the pointer device and can be of any shape, e.g. a rectangle, a polygon, or a range.

note

The geometry coordinate system is the same as the graph coordinate system.

It's a generic class with type variables G and O where:

• G represents the geometry of the region
• O represents the options of the region

class Region<G, O extends Region.Options<G>> { }

You can find more information about the use of the SelectionRegion class in the learn guide.

There are several built-in implementations of SelectionRegion:

• RectangularSelectionRegion
• PolygonalSelectionRegion
• RangeSelectionRegion

constructor

constructor(options?: SelectionRegion.Options);

paper

[required] The paper where the region will be drawn.

layer

[optional] The layer of the paper where the region will be drawn. Default is dia.Paper.Layers.FRONT.

onChange()

onChange?: (geometry: G, evt: dia.Event) => void;

[optional] A callback function that is called when the region geometry changes as the user interacts with the region.

Methods

addPoint()

protected abstract addPoint(x: number, y: number): void;

When the user draws the region, this method is called every time the user moves the pointer. The x and y parameters represent the current pointer position in the graph coordinate system.

draw()

draw(geometry: G | null): void;

A method to draw the region on the paper programmatically.

Example

Draws a rectangular region on the paper.

region.draw(new g.Rect(10, 10, 100, 100));

Removes the region from the paper.

region.draw(null);

getCurrentSelection()

getCurrentSelection(): G | null;

Returns the current region geometry if the user selection is in progress.

Example

Get the current selection and find all elements in that region.

const rectangle = region.getCurrentSelection();
const elements = graph.findModelsInArea(rectangle);

getUserSelectionAsync()

async getUserSelectionAsync(): Promise<G | null>;

A method that returns a promise that resolves to the region geometry drawn by the user. The promise is resolved when the user finishes drawing the region. It could be resolved with null if the user cancels the drawing.

Example

Let the user select a region and find all elements in the region.

const rectangle = await region.getUserSelectionAsync();
const elements = graph.findModelsInArea(rectangle);

validatePoint()

protected abstract validatePoint(x: number, y: number): boolean;

Check if the point is valid. If the method returns false, the region onChange event is not triggered. This is for performance optimization to avoid unnecessary updates.

resetPoints()

protected abstract resetPoints(): void;

Reset the region points before the user starts drawing a new region.

usePoints()

protected abstract usePoints(): G | null;

Gather the points of the region and return the geometry of the region.

update()

protected abstract update(internalGeometry: G): void;

This method is called when the region geometry changes and it is meant to update the region view on the paper.

Types

The SelectionRegion class is a base class for all region implementations.

class SelectionRegion<G, O extends SelectionRegion.Options<G>> extends mvc.View<undefined, SVGElement> {
    constructor(options?: O);
    async getUserSelectionAsync(): Promise<G | null>;
    getCurrentSelection(): G | null;
    draw(geometry: G): void;
}

Options

interface Options<G> extends mvc.ViewOptions<undefined, SVGElement> {
    paper: dia.Paper;
    layer?: dia.Paper.Layers;
    onChange?: (geometry: G, evt: dia.Event) => void;
}