Selection

Selection enables the ability to select shapes on the paper.

Learn more about the Selection plugin.

constructor

constructor(options?: Selection.Options);

The ui.Selection constructor accepts the following parameters:

paper

[required] The joint.dia.Paper or joint.ui.PaperScroller the Selection should operate on. If a PaperScroller object is provided, then its paper option is used as the basis for this Selection; in addition, the behavior specified by the PaperScroller's scrollWhileDragging option is automatically applied for relevant Selection activities (selecting, translating, resizing).

If the paper option is not provided, the Selection throws an exception:

ui.Selection: paper required

graph

[optional] The joint.dia.Graph the Selection should operate on. If no graph is passed paper.model is used.

collection

[optional] A mvc Collection object used to store selected cells. If no collection is passed new mvc.Collection is used.

frames

[optional] The SelectionFrameList which will be used to render the selection frames.

If no frames are passed, a legacy SelectionFrameList is created (to support the backward compatibility). If you want to customize the selection frames, you need to pass your own SelectionFrameList instance.

filter

[optional] Either an array in which case it can contain (even intermixed) cells or cell types that will be ignored by the selection. This is useful if you have certain elements in the diagram that are not supposed to get selected. It can also be function in which case it will be called with a cell as an argument and should return true if that cell should be filtered out of the selection. The function gives you more flexibility in deciding whether an element can or cannot be selected. Example:

filter: ['standard.Rectangle', 'mymodule.HiddenShape']

boxContent

[optional] A function that returns an HTML string with the content that will be used in the information box below the selection. By default, the box shows the number of selected elements.

boolean | mvc.$HTMLElement | ((boxElement: HTMLElement) => mvc.$HTMLElement);

useModelGeometry

[optional] If set to true, the cells position and dimensions will be used as a basis for the Selection wrapping rectangle position. By default, this is set to false which causes the Selection wrapping rectangle position be based on the bounding box of the selected element views. Sometimes though, your shapes can have certain SVG sub elements that stick out of the view and you don't want these sub elements to affect the Selection wrapping rectangle position. In this case, set the useModelGeometry to true.

selectLinks

[optional] If set to true, links under the selection rectangle will be selected as well. It defaults to false.

strictSelection

[optional] If set to true, only elements that are fully contained in the selection rectangle will be selected as opposed to the default behaviour that selects elements whose bounding box intersects the selection rectangle.

allowTranslate

[optional] If set to false, users are not allowed to move selected elements around by dragging selection boxes. It defaults to true.

preserveAspectRatio

[optional] Set to true if you want the resizing to preserve the aspect ratio of the elements. The default is false.

rotateAngleGrid

[optional] When selected elements are rotated the resulting angles are snapped to this value. It defaults to 15 degrees.

handles

[optional] A array of objects defining the tools around the selection. This array defaults to:

[
    {
        name: 'remove',
        position: 'nw',
        events: {
            pointerdown: 'removeElements'
        }
    },
    {
        name: 'rotate',
        position: 'sw',
        events: {
            pointerdown: 'startRotating',
            pointermove: 'doRotate',
            pointerup: 'stopBatch'
        }
    }
]

note

Normally, you do not need to set this array. It's better to use the addHandle(), removeHandle() and changeHandle() methods described below in the methods section.

translateConnectedLinks

[optional] When translating selected elements, should the connected links also be translated? Based on the selected value of the ui.Selection.ConnectedLinksTranslation enumerator, the behavior is as follows:

• NONE - none of the links are translated
• SUBGRAPH - only links whose both ends are connected to one of the selected elements are translated.
• ALL - all connected links are translated

The default is ui.Selection.ConnectedLinksTranslation.ALL.

allowCellInteraction

[optional] Allows interaction with underlying element's features, e. g. buttons or ports. In this case selection-box events will be triggered by browser event from the cell instead of the selection-box html element. It defaults to false.

wrapper

[optional] Should all the selection frames be wrapped in an rectangular HTML element? It defaults to true.

note

For backwards compatibility reasons, when the wrapper option is set to true, the selection wrapper is styled in CSS using built-in themes. And the class name of the selection wrapper is selection-wrapper.

It is joint-selection-wrapper when the wrapper option is set to false or an object (i.e theme is not applied).

The look of the selection wrapper can be customized by setting the wrapper option to an object with several properties.

The option object is passed to the selection wrapper mvc.View constructor, therefore properties such as className or style are also available.

new Selection({
    /* ... */
    wrapper: {
        style: {
            border: '2px dashed red',
        },
        margin: 10,
    }
})

Here're the selection wrapper properties:

margin

margin: number;

The gap between the selection wrapper and frames. It defaults to 7 and it does not account for thickness of the selection frames.

usePaperScale

usePaperScale: boolean;

If set to true, the selection wrapper and its handles scale with the paper scale. It defaults to false.

visibility

visibility: WrapperVisibility;

A callback function to determine the visibility of the selection wrapper. It defaults to () => true.

wrapper: {
    // Do not show the selection wrapper if there is only one element selected.
    visibility: (selection) => selection.collection.length > 1
}

Methods

addHandle()

selection.addHandle(handle?: Selection.Handle): void;

Add a custom tool to the Selection. opt.name is the name of the custom tool. This name will be also set as a CSS class to the handle DOM element making it easy to select it your CSS stylesheet. opt.position is a string that specifies a position of the tool handle. Possible values are n, nw, w, sw, s, se, e and ne. opt.icon is a URL of the icon used to render the tool. This icons is set as a background image on the tool handle DOM element.

removeHandle()

selection.removeHandle(name: string): void;

Remove a tool handle named name from the Selection.

changeHandle()

selection.changeHandle(name: string, opt?: Selection.HandleOptions): void;

Change a tool handle named name in the Selection. The opt object can contain the same parameters as with the addHandle() method except of the name property. opt parameters will be merged with those defined previously.

on()

selection.on(eventName: string, callback: EventHandler, context?: any): this;
// or
selection.on(eventMap: EventMap, context?: any): this;

Register a handler (callback) for an event See the Selection Events section for the list of events the Selection object triggers.

setWrapperVisibility()

selection.setWrapperVisibility(visible: WrapperVisibility): void;

Change the visibility of the selection wrapper dynamically. The visible parameter can be a boolean or a function that returns a boolean.

startSelecting()

selection.startSelecting(evt: dia.Event): void;

Initiate bulk selection. See the Common Setup section how that can be used.

createSelectionBox()

selection.createSelectionBox(cell: dia.Cell): void;

Create a single selection box above an element.

destroySelectionBox()

selection.destroySelectionBox(cell: dia.Cell): void;

Destroy a single selection box, which is rendered above an element.

Static Methods

getDefaultHandle()

Selection.getDefaultHandle(name: string): Selection.Handle;

Get the default handle configuration by its name. The default handles are remove, rotate, resize and clone. The method throws an exception if the handle with the given name does not exist:

ui.Selection: default handle not found: ${name}

Events

action:[name]:pointerdown

Triggered when the user clicks (touches) on a tool handle named name. The handler is called with the mousedown event object, and x and y of the pointer in local coordinates.

action:[name]:pointermove

Triggered when the user moves with mouse cursor after a tool handle named name was mousedowned (touched). The handler is called with the mousemove event object, and x and y of the pointer in local coordinates.

action:[name]:pointerup

Triggered when the user releases his mouse cursor after a tool handle named name was mousedowned (touched). The handler is called with the mouseup event object, and x and y of the pointer in local coordinates.

action:[name]:contextmenu

Triggered when the user invokes contextmenu on a tool handle named name. The handler is called with the mousedown event object, and x and y of the pointer in local coordinates.

selection-box:pointerdown

Triggered when the user starts interacting with a selected element, an element that has a selection box above it. The handler gets passed the element view, the DOM event object, x and y paper local coordinates. Use elementView.model if you wish to access the actual element model. In the case of allowCellInteraction: true the DOM event will be triggered by the element instead of selection-box. See below in the Common Setup section how that can be used.

selection-box:pointermove

Triggered when the user is moving with a selected element, an element that has a selection box above it. The handler gets passed the element view, the DOM event object, x and y paper local coordinates.

selection-box:pointerup

Triggered when the user stops interacting with a selected element, an element that has a selection box above it. The handler gets passed the element view, the DOM event object, x and y paper local coordinates.

Types

HandlePosition

enum HandlePosition {
    N = 'n', NW = 'nw',
    W = 'w', SW = 'sw',
    S = 's', SE = 'se',
    E = 'e', NE = 'ne'
}

ConnectedLinksTranslation

enum ConnectedLinksTranslation {
    NONE = 'none',
    SUBGRAPH = 'subgraph',
    ALL = 'all'
}

EventHandler

type EventHandler = (evt: dia.Event, x: number, y: number) => void;

EventMap

interface EventMap {
    [event: string]: EventHandler;
}

HandleEvents

interface HandleEvents {
    pointerdown?: string | EventHandler;
    pointermove?: string | EventHandler;
    pointerup?: string | EventHandler;
    contextmenu?: string | EventHandler;
}

HandleOptions

interface HandleOptions {
    position?: HandlePosition;
    events?: HandleEvents;
    attrs?: any;
    icon?: string;
    content?: mvc.$HTMLElement
}

Handle

interface Handle extends HandleOptions {
    name: string;
}

Options

The options for the ui.Selection class.

interface Options extends mvc.ViewOptions<undefined> {
    paper: dia.Paper | ui.PaperScroller;
    graph?: dia.Graph;
    boxContent?: boolean | mvc.$HTMLElement | ((boxElement: HTMLElement) => mvc.$HTMLElement);
    handles?: Array<Handle>;
    useModelGeometry?: boolean;
    strictSelection?: boolean;
    rotateAngleGrid?: number;
    allowTranslate?: boolean;
    preserveAspectRatio?: boolean;
    collection?: any;
    filter?: ((cell: dia.Cell) => boolean) | Array<string | dia.Cell>;
    translateConnectedLinks?: ConnectedLinksTranslation;
    allowCellInteraction?: boolean;
    frames?: ui.SelectionFrameList;
    wrapper?: boolean | ui.HTMLSelectionWrapper.Options | ui.SelectionWrapper;
}

WrapperVisibility

The type of the wrapper visibility callback.

type WrapperVisibility = boolean | ((selection: Selection) => boolean);