Skip to main content

Halo

Halo creates a control panel above an element with various tools.

Learn more about the Halo plugin.

constructor​

constructor(opt?: Halo.Options);

The Halo constructor accepts several parameters:

cellView​

[required] An element or link view. Previously, Halo accepted also paper and graph options, but this is now deprecated as those can always be inferred from cellView.paper and cellView.paper.model properties.

type​

[optional] The type of the halo control panel. The default value is 'surrounding'. Other possible values are 'pie' in which case the halo will be displayed as a pie menu, and 'toolbar' in which case the halo tools are displayed above the element in a small toolbar.

loopLinkPreferredSide​

[optional] The preferred side for a self-loop link created from Halo ("top"|"bottom"|"left"|"right"), the default is "top".

loopLinkWidth​

[optional] The self-loop link width in pixels, the default is 40.

rotateAngleGrid​

[optional] The angle increments the rotate action snaps to, the default is 15.

rotateEmbeds​

[optional] Should the elements embedded inside the cellView element be rotated as well? The default is false.

boxContent​

[optional] A string (text or HTML), or a function (of the form boxContent(cellView, boxDOMElement)) that returns a HTML string with the content that will be used in the information box below an element. By default, the box displays the x, y coordinates, and width and height dimensions of the element. If boxContent is set to false (or an empty string), the information box will be hidden

clearAll​

[optional] If set to true (the default value), clear all the existing halos from the page when a new halo is created. This is the most common behavior as it is assumed that there is only one halo visible on the page at a time. However, some applications might need to have more than one halo visible. In this case, set clearAll to false (and make sure to call remove() once you don't need a halo anymore)

clearOnBlankPointerdown​

[optional] If set to true (the default value), clear the halo when a user clicks the blank area of the paper.

useModelGeometry​

[optional] If set to true, the model position and dimensions will be used as a basis for the halo tools position. By default, this is set to false which causes the halo tools position be based on the bounding box of the element view. 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 halo tools position. In this case, set the useModelGeometry to true.

clone​

[optional] A function with signature function(cell, opt). This function will be called when cloning or forking actions take place, and it should return a clone of the original cell. This is useful e.g. if you want the clone to be moved by an offset after the user clicks the clone handle. The default function is: function(cell, opt) { return cell.clone().unset('z') }.

The callback may return an array of cells. This is useful if the element has nested cells that also need to be cloned. In this case, the user drags the first cell in the array.

new ui.Halo({
    /* ... */
    clone: (cell) => {
        return cell.clone({ deep: true });
        // const [cellClone, ...embedsClones] = cell.clone({ deep: true });
        // return [cellClone, ...embedsClones];
    }
});

pieSliceAngle​

[optional] (only valid for the 'pie' type of Halo) The angle of one slice in the pie menu. It defaults to 45.

pieStartAngleOffset​

[optional] (only valid for the 'pie' type of Halo) The angular offset of the first handle in the pie menu. It defaults to 0.

pieIconSize​

[optional] (only valid for the 'pie' type of Halo) The size in pixels of the icon in the pie menu. It defaults to 14.

pieToggles​

[optional] (only valid for the 'pie' type of Halo) An array of pie toggle buttons. Usually, there's only one (the default), but you can have as many as you want. The default value is [{ name: 'default', position: 'e' }]. Each item in the array is an object of the form { name: [name of you toggle], position: [one of e/w/s/n] }. The name is passed in the options object in the state:close and state:open events triggered by the Halo when the pie toggle is clicked.

bbox​

[optional] A bounding box within which the halo view will be rendered.

tinyThreshold​

[optional] If the set number value is higher than the halo bbox width and height, a 'tiny' CSS class is applied to the halo. This reduces the size of the halo. For elements, the default value is 40. For links, the default halo bbox width and height both equal 1. This means a value of 2 or higher is needed to apply the class.

smallThreshold​

[optional] If the set number value is higher than the halo bbox width and height, a 'small' CSS class is applied to the halo. This reduces the size of the halo. A 'small' class will not be applied, if a 'tiny' class is already present. For elements, the default value is 80. For links, the default halo bbox width and height both equal 1. This means a value of 2 or higher is needed to apply the class.

magnet​

[optional] A function accepting an elementView returning an SVGElement used as a magnet for links created via linking or forking handles.

new joint.dia.Halo({
    cellView: elementView,
    magnet: (elementView, end, evt) => {
    // where `end` is either "source" (linking and forking) or "target" (forking only)
    // and `evt` is a `mousedown` event
    // connect the link directly to a rectangle element as opposed to the element group
    return elementView.el.querySelector('rect') || elementView.el;
    }
})

Methods​

addHandle()​

halo.addHandle(handle: Halo.Handle): this;

Add a custom tool to the halo. handle.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 in your CSS stylesheet. handle.position is a string that specifies a position of the tool handle. Possible values are n, nw, w, sw, s, se, e and ne. handle.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.

addHandles(handles)​

halo.addHandles(handles: Halo.Handle[]): this;

Add multiple handles in one go. This calls addHandle() internally for each item of the handles array.

removeHandle()​

halo.removeHandle(name: string): this;

Remove a tool handle named name from the halo.

removeHandles()​

halo.removeHandles(): this;

Remove all handles from the halo.

changeHandle()​

halo.changeHandle(name: string, handle: Halo.Handle): this;

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

render()​

halo.render(): this;

Render the halo. This must be called after the halo object is instantiated.

on()​

halo.on(eventName: string, callback: EventHandler, context?: any): this;

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

toggleState()​

halo.toggleState(toggleName: string): void;

Toggle (open/close) the sate of the halo (applicable for the pie type of halo). toggleName is the name of the pie toggle as defined in the pieToggles option. If toggleName is not passed, all pie menus change state (the most common usage as there is usually only one pie toggle).

isOpen()​

halo.isOpen(toggleName: string): boolean;

Return true if the halo is open (applicable for the pie type of halo). toggleName is the name of the pie toggle as defined in the pieToggles option. If toggleName is not passed, return true if any of the pie menus are open.

remove()​

halo.remove(): this;

Remove/destroy the halo. Note that by default, the halo removes itself when the user clicks on a blank area in the paper. In some cases, however, it is useful to remove the halo programmatically.

Static Methods​

clear()​

ui.Halo.clear(paper: dia.Paper): void;

Remove all the halo panels (without having to have a reference to a particular halo object) from the paper. Note that this is a static function in the ui.Halo namespace rather than a method of a halo object.

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

action:​link:add​

Triggered after the user finishes creating a link with the default link tool. This is useful if you want to do something with the link after it has been created. For example, to prevent the user from creating loose links (links that do not have both source and target set), you can do:

halo.on('action:link:add', (link) => {
    if (!link.get('source').id || !link.get('target').id) {
        link.remove();
    }
});

state:open​

Triggered when the user opens the halo (applicable for the pie type of Halo). The handler is passed the pie toggle name as defined in the pieToggles option.

state:close​

Triggered when the user closes the halo (applicable for the pie type of halo). The handler is passed the pie toggle name as defined in pieToggles option.

close​

Triggered when the halo gets closed.

Types​

EventHandler​

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

Handle​

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

HandleEvents​

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

HandlePosition​

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

Options​

interface Options extends mvc.ViewOptions<undefined> {
    cellView: dia.CellView;
    loopLinkPreferredSide?: 'top' | 'bottom' | 'left' | 'right';
    loopLinkWidth?: number;
    rotateAngleGrid?: number;
    rotateEmbeds?: boolean;
    boxContent?: boolean | mvc.$HTMLElement | ((cellView: dia.CellView, boxElement: HTMLElement) => mvc.$HTMLElement);
    handles?: Array<Handle>;
    clearAll?: boolean;
    clearOnBlankPointerdown?: boolean;
    useModelGeometry?: boolean;
    clone?: (cell: dia.Cell, opt: { [key: string]: any }) => dia.Cell | Array<dia.Cell>;
    type?: string;
    pieSliceAngle?: number;
    pieStartAngleOffset?: number;
    pieIconSize?: number;
    pieToggles?: Array<{ name: string, position: HandlePosition }>;
    bbox?: dia.Point | dia.BBox | ((cellView: dia.CellView) => dia.Point | dia.BBox);
    tinyThreshold?: number;
    smallThreshold?: number;
    magnet?: (elementView: dia.ElementView, end: 'source' | 'target', evt: dia.Event) => SVGElement;
}

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub