Skip to main content

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

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.

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.

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.

[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​

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.

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.

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.

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​

interface Options extends mvc.ViewOptions<undefined> {
    paper: dia.Paper | 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;
}

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub