SV class (Surface) | Exontrol Docs

new SV(oSurface)

The SV type defines the surface view of the Surface control. The surface displays elements that can be connected by links. Users can create new elements, move and resize them by drag and drop, and create links between elements to represent relationships or connections. This interactive behavior allows users to visually arrange and organize elements directly on the surface.

The oSV member of the Surface control holds a reference to the SV object and defines the base view of the control. Most of the properties and methods of the SV object are exported by the Surface control, so you can access them directly on the control. For example, you can call oSurface.GetZoom() instead of oSurface.oSV.GetZoom(), because the Surface control exposes all properties and methods of its SV object.

Parameters:

Name	Type	Description
`oSurface`	any	Indicates a reference to the exontrol.Surface object the view belongs to.

Methods

Arrange(id, oDefArrangeopt)

The Arrange() method arranges the elements, starting from giving element, based on the links. The Arrange() method is useful to automatically arrange the elements of the surface based on their links. For instance, you can use it to arrange the elements in a hierarchical structure, such as a tree or an organizational chart, by defining the links between parent and child elements and then calling the Arrange() method. The Arrange() method takes an optional id parameter that specifies the element from which to start the arrangement. If the id parameter is not provided or is null, the arrangement starts from all linked-elements of the control.

Parameters:

Name	Type	Attributes	Description
`id`	any		The id parameter could be any of the following: null {null}, specifies that all linked-elements of the control get arranged id {number}, indicates a numeric value that defines the index of the element to start arrangement from id {string}, specifies a string expression that defines the identifier/key/plain-caption of the element to start arrangement from id {Element}, specifies the object reference to the element to start arrangement from
`oDefArrange`	DefArrange	<optional>	Indicates an object of {dir, dx, dy, align, compact} type to customize the arrangement of the elements. The dir property defines the direction of arrangement as a value of 0 (down), 1 (up), 2 (right) or 3 (left). The dx and dy properties specify the horizontal and vertical distance between the elements, respectively. The align property indicates the alignment of elements in each level of arrangement as a value of 0 (near), 1 (center) or 2 (far). The compact property specifies whether to arrange the elements in a compact style, which reduces the distance between elements if they have enough space to be arranged without overlapping. For instance, {dir: 0, dx: 20, dy: 20, align: 0, compact: true} arranges the elements in a downward direction with 20 pixels of horizontal and vertical distance, aligned to the left (near) and in a compact style.

Example

oSurface.Arrange(), arranges all linked-elements of the control based on the links

Arrange

Clear()

The Clear() method clears the elements and the links. The Clear() method removes all elements and links from the control, effectively resetting the control to an empty state. After calling the Clear() method, the control will no longer contain any elements or links, and you can start adding new elements and links as needed. In the context of the control, this method is useful for quickly removing all existing content and starting fresh without having to individually delete each element or link. In addition, the Clear() method can be used to free up resources and improve performance when you want to completely reset the control's content.

Since:

Example

oSurface.Clear(), clears all elements and links from the control

Clear

Copy()

The Copy() method copies the current selection to the clipboard. The Cut, Copy, and Paste methods work only when the control is visible. The Copy() method generates the data to export to the clipboard from the selected elements and the links between them by calling the onCopy() method, and then sets this data in the clipboard. The onCopy() method can be overridden to customize the default data format for derived objects. By default, onCopy() returns an object of {e(lements), l(inks)} type, where e(lements) is a collection of [{ElementOptions}] objects representing the selected elements, and l(inks) is either undefined or a collection of [{LinkOptions}] objects representing the links between the selected elements. The clipboard data is stored as a JSON representation of the object returned by onCopy(), which can later be retrieved by the Paste() method through the Clipboard API.

Since:

Example

The following samples demonstrate how to implement the Copy, Cut, and Paste methods for the control using the Clipboard API when the user presses the CTRL + C, CTRL + X (the "See text and images copied to the clipboard /Allow/Block" message may occur due security permissions):

 oSurface.on("{CTRL + C}", oSurface.Copy)
 oSurface.on("{CTRL + X}", oSurface.Cut)
 oSurface.on("{CTRL + V}", oSurface.Paste)

Please note that the control requires focus, so CTRL + C, CTRL + X or CTRL + V to make it works. In the same manner, the tabIndex attribute must be present into the defintion of the canvas HTML element.

Copy

Cut()

The Cut() method moves the selection to the Clipboard. Shortly, the Cut method copies the current selection to the clipboard by calling the Copy() method, and then removes the selected elements from the surface by calling the RemoveSelection() method. The Cut/Copy/Paste methods work only when the control is visible. The Cut method is used to cut the selected elements and links to the clipboard, and the Paste method is used to paste them back to the surface.

Since:

Example

The following samples demonstrate how to implement the Copy, Cut, and Paste methods for the control using the Clipboard API when the user presses the CTRL + C, CTRL + X (the "See text and images copied to the clipboard /Allow/Block" message may occur due security permissions):

 oSurface.on("{CTRL + C}", oSurface.Copy)
 oSurface.on("{CTRL + X}", oSurface.Cut)
 oSurface.on("{CTRL + V}", oSurface.Paste)

Please note that the control requires focus, so CTRL + C, CTRL + X or CTRL + V to make it works. In the same manner, the tabIndex attribute must be present into the defintion of the canvas HTML element.

Cut

EnsureVisibleClient(clientA, ensureOptsopt)

The EnsureVisibleClient() method ensures that the specified client fits within the control's client area. The EnsureVisibleSelection() method is an alias of EnsureVisibleClient and ensures that the specified selection fits within the control's client area. The EnsureVisibleClient() method can adjust the control's scale or zoom factor to fully fit the client if the allowScale option is set to true. Additionally, if the nearestFit option is set to true, it ensures that the corner of the object nearest to the window's client area is visible; this option only applies when the object's size is larger than the window's client area.

Parameters:

Name	Type	Attributes	Description
`clientA`	object		The client parameter could be any of the following: clientA {array}, specifies an array of [x,y,width,height] type that indicates the absolute-coordinates of the layout-rectangle to fit into the control's client area clientA {object}, indicates an object of {Element} type or any other type the control's layout contains, that indicates the object to fit into the control's client area
`ensureOpts`	object	<optional>	Specifies different options to run the current method as explained: allowScale {boolean}, updates the control's scale/zoom-factor to ensure full-fit the client (@since 5.2) nearestFit {boolean}, ensures that corner of the object nearest the window's client area fits it (it has effect only if the size of the object is greater than size of the window's client area) (@since 5.2)

Example

oSurface.EnsureVisibleClient([100, 100, 50, 50]), ensures that the rectangle of [x:100,y:100,width:50,height:50] absolute-coordinates fits within the control's client area
 oSurface.EnsureVisibleClient(oSurface.Element(0)), ensures that the first element of the control's layout fits within the control's client area

EnsureVisibleClient

EnsureVisibleSelection()

The EnsureVisibleSelection() method scrolls the control's content to ensure that the control's selection fits the control's client area. The Selection property can be used to set or retrieve the selected elements. The EnsureVisibleClient() method can be used to ensure that a specific client (element or rectangle) fits the control's client area. The EnsureVisibleSelection() method retrieves the current selection and calculates the union of all selected elements in absolute coordinates. It then calls the EnsureVisibleClient() method with the calculated rectangle to scroll the control's content accordingly. This ensures that all selected elements are visible within the control's client area, providing a better user experience when working with selections in the control.

Example

oSurface.EnsureVisibleSelection(), scrolls the control's content to ensure that the control's selection fits the control's client area

EnsureVisibleSelection

FitToClient(rtLayout)

The FitToClient() method ensures that the entire (null/undefined) or giving layout fits the control's client area. The FitToClient() method is typically used to fit the entire layout or a specific layout-rectangle into the control's client area, while the EnsureVisibleClient() method is used to ensure that a specific client (layout-rectangle or element) is visible within the control's client area. The EnsureVisibleSelection() method is an alias of EnsureVisibleClient and ensures that the specified selection fits within the control's client area. The Home() method zooms to 100% and scrolls the control to origin (0,0).

Parameters:

Name	Type	Description
`rtLayout`	Array.<number>	Indicates null for entire layout or an array of [x,y,width,height] type that defines the absolute-coordinate to fit to client.

Example

oSurface.FitToClient(), fits the entire layout into the control's client area

FitToClient

GetAlignObjectsToGridLines() → {number}

The GetAlignObjectsToGridLines() method specifies whether the object(s) are aligned to the minor or major grid lines when they are moved or resized. The MajorGridLines property defines the appearance of the surface's major grid lines as an object of {step, width, color, style, cap} type. The MinorGridLines property defines the appearance of the surface's minor grid lines in the same format. The ShowGridLines property specifies whether the control displays the minor and major grid lines.

Since:

Returns:

Returns one of the following values:

0 {number}, no alignment is performed
-1 {number}, the objects are aligned to minor grid lines
1 {number}, the objects are aligned to major grid lines

Type: number

Example

The following statements are equivalents:

 oSurface.GetAlignObjectsToGridLines() {number}, specifies whether the object(s) are aligned to the minor or major grid lines
 oSurface.AlignObjectsToGridLines {number}, specifies whether the object(s) are aligned to the minor or major grid lines

where oSurface is an instance of Surface control

GetAlignObjectsToGridLines

GetAllowActions() → {string}

The GetAllowActions() method gets the actions the user can perform once the control is clicked or touched. The order of the actions is very important, as the control checks each action from left to right until it finds a matching action for the performed mouse/touch event. The first matched action is performed, and the rest of the actions are ignored. So if you want to perform a specific action once the user clicks an item, and perform another action if the user clicks an area that does not contain any item, you should place the first action before the second one in the AllowActions property.

Returns:

Returns the actions the user can perform once the control is clicked or touched

The format of the property is:

"action(shortcut,shortcut,...),action(shortcut,shortcut,...)..."

where

"action", defines the action to perform (as defined below)

Action	Description	Flags
"create"	Creates an element by drag (not available if the control is read-only)
"drag-drop"	Performs drag and drop of the element (the element can be dropped inside or outside of the control). The ExDrop(event, data) method of the target HTML element is invoked once the user drops the element. The event parameter contains information about the mouse/touch event. The data parameter contains information about the source-object that initiated the drag/drop operation as {object, source, client, shape}
"fit"	Fits the drag-area into the control's client area
"link"	Links elements by drag (not available if the control is read-only)	[toggle], the link is removed if the linked-elements has already a link between
"link-cp"	Allows customization of the link's path by drag (not available if the control is read-only). This action is effective only if allowLinkControlPoint field is not zero
"move"	Moves or resizes elements by drag (not available if the control is read-only). The allowChangeParent field specifies whether the element's position or parent can be changed at runtime by drag and drop
"scroll"	Scrolls the control's content by drag
"select"	Selects elements by drag
"zoom"	Zooms the control's content at dragging-point

The exswimlane/js control supports additional actions as listed in the table below:

Action	Description	Flags
"create"	Creates an element or a pool by drag (For instance "create[pool](Ctrl+Alt)" creates a pool if Ctrl + Alt is pressed, while "create[element](Alt)" creates an element while the Alt key is pressed, not available if the control is read-only)	[pool], specifies that a pool is created [element], specifies that an element is created
"move"	Moves or resizes elements by drag (For instance, "move[element]" indicates that only elements are allowed to be moved or resized, not available if the control is read-only). If flag is missing, the user can move or resize elements or pools	[pool], specifies that just pools are movable/resizable [element], specifies that just elements are movable/resizable
"resize-header"	Resizes the pool's header (For instance, "resize-header[left,top]" specifies that just the left and top-header of the pool are resizable, not available if the control is read-only). If no flag is present, all pool's headers are resizable	[left], indicates that the left-header of the pool is resizable [right], indicates that the right-header of the pool is resizable [top], indicates that the top-header of the pool is resizable [bottom], indicates that the bottom-header of the pool is resizable
"resize-lane"	Resizes the pool's lane (the lanes are vertically arranged)
"resize-phase"	Resizes the pool's phase (the phases are horizontally arranged)

"shortcut", defines the event's button or/and the modifier-keys that are required to perform the action. The "shortcut" can include one or more of the following: "Shift", "Ctrl", "Alt", "Meta", "LButton", "RButton", "MButton" and "+"

For instance "create(Alt+LButton),move,scroll" indicates that creating-elements is possible only if the user presses the mouse's left-button while ALT key is pressed, and "move" or "scroll" is possible no matter of the event's button or modifier-keys in this order. Also, if no "create"-operation is possible, do "move"-operation, if no "move"-operation is possible, do "scroll"-operation

Type: string

GetAllowChangeParent() → {boolean}

The GetAllowChangeParent() method specifies whether an element's position or parent can be changed at runtime using drag and drop. When set to true, users can rearrange elements by dragging them to different positions or parents. When set to false, drag and drop cannot change the element's position or parent. This property is useful for maintaining a fixed structure or hierarchy within the control. AllowChangeParent is effective only if the "move" action is included in the AllowActions property and the control is not read-only. The Element.Parent property indicates the parent of an element, while Element.Position indicates the element's position within its parent's children collection.

Returns:

Returns true if the element's position or parent can be changed at runtime by drag and drop.

Type: boolean

Example

The following statements are equivalent:

 oSurface.GetAllowChangeParent() {boolean}, gets whether the element's position or parent can be changed at runtime by drag and drop
 oSurface.AllowChangeParent {boolean}, gets whether the element's position or parent can be changed at runtime by drag and drop

where oSurface is an instance of Surface type

GetAllowChangeParent

GetAllowLinkControlPoint() → {Surface.LinkControlPointEnum}

The GetAllowLinkControlPoint() method specifies the control points of links that users can use to customize the link's path. This property applies to all links unless a different value is specified by the Link.AllowControlPoint property. Users can drag and drop control points to change the link's path or remove them by dragging one control point onto another. The ShowLinks property must be different from 0 to display the link's control points. AllowLinkControlPoint is effective only if the "link-cp" action is included in the AllowActions property and the control is not read-only.

Returns:

Returns the control points of the link, the user can use to customize the link's path. The property is applied to all links (unless the Link.AllowControlPoint property indicates a different value).

The Surface.LinkControlPointEnum type defines the following flags:

exNoControlPoint(0), the link displays no control points
exStartControlPoint(1), the link shows control point that changes the link's startPos field (the exStartControlPoint point is marked with black squares)
exEndControlPoint(2), the link shows control point that changes the link's endPos field (the exEndControlPoint point is marked with black squares)
exControlPoint(4), defines the corners of the link's path. You can remove a exControlPoint points by dragging to another, so intermediate exControlPoint points are removed. You can move all control points of the link at once, if SHIFT key is pressed (the exControlPoint points are marked black circles)
exMiddleControlPoint(8), defines the link's middle control points that are displayed between two exControlPoint points, to let the use add new exControlPoint points, to redefine the link's path (The exMiddleControlPoint points are marked with gray circles)
exOrthoArrange(0x10), specifies that the lines of the link are orthogonal arranged when the user drags and drops the middle or control-points of the path (excludes the start/end control-points)
exAllowChangeFrom(0x20), allows the user to adjust the link's from element by dragging and dropping the start control point (requires the exStartControlPoint flag)
exAllowChangeTo(0x40), indicates that the user can adjust the link's to element by dragging and dropping the end control point (requires the exEndControlPoint flag)

Type: Surface.LinkControlPointEnum

Example

The following statements are equivalents:

 oSurface.GetAllowLinkControlPoint() {number}, gets the current control points of the link
 oSurface.AllowLinkControlPoint {number}, gets the current control points of the link

where oSurface is an instance of Surface control.

GetAllowLinkControlPoint

GetAxes() → {object}

The GetAxes() method specifies the appearance used to draw the surface axes, as an object of {width, color, style, cap} type. The axes are typically represented by two perpendicular lines that intersect at the origin (0,0) of the surface. The ShowAxes property determines whether the control displays the horizontal and vertical axes. The Axes property allows you to customize their appearance, including width, color, line style, and other visual attributes.

Since:

Returns:

Returns an object of {width, color, style, cap} type as explained:

width, {number} specifies the line's width or size (1 by default) (if 0 no axes are shown). For instance:
null {null}, indicates line of 1-pixel wide (default value)
0 {number}, indicates that no axes are shown
2 {number}, indicates line of 2-pixels wide
color, {string} indicates the line's color ("#E8E8E8" by default). For instance:
null {null}, indicates a light gray line (default value)
"transparent" {string}, specifies a transparent line
"red" {string}, specifies a red line
"#00FF00" {string}, specifies a green line
"rgba(255,0,0,0.5)" {string}, indicates 50% red line
style, {array} defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance:
null {null} or [] {array}, defines solid grid-lines (default style)
2 {number}, becomes [2, 2, ...]
[5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
cap {string}, determines the shape used to draw the end points of lines ("but" by default).
Determines the shape used to draw the end points of lines, as one of the following:
- "butt" {string}, the ends of lines are squared off at the endpoints.
- "round" {string}, the ends of lines are rounded
- "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness
For instance:

null {null}, "butt" ends (default value)
"round" {string}, the ends of lines are rounded

Type: object

GetCanvas() → {HTMLCanvasElement}

The GetCanvas() method returns the HTMLCanvasElement object where the control is currently running on. The control is always running on a canvas, which is the canvas of the control's canvas-window (exontrol.CW). The GetCanvas() method is useful when you need to access the canvas directly. You can also use the GetCanvas() method to retrieve the canvas's context and perform custom drawing operations using the Canvas API. It is recommended to call the exontrol.CC.Resize(<canvas>, [width], [height]) method to resize and refresh the control; otherwise, the control's content is lost.

Returns:

Returns the HTMLCanvasElement object the control is running on.

Type: HTMLCanvasElement

Example

The following statement draws a filled rectangle on the control's canvas, at position (10,10) with width and height of 100px:

 oSurface.GetCanvas().getContext("2d").fillRect(10, 10, 100, 100)
 oSurface.oSV.GetCanvas().getContext("2d").fillRect(10, 10, 100, 100)

where oSurface is a reference to the Surface object

GetCanvas

GetCollapsedLink() → {DisplayLinkType}

The GetCollapsedLink() method specifies the appearance of links between collapsed elements. It allows customization of line style, color, thickness, and other visual attributes to differentiate these links from those between expanded elements. The ShowLinksOnCollapse property controls whether links between collapsed elements are visible. The Element.Expand property indicates whether an element is expanded or collapsed, and the CollapsedLink settings apply to links connecting elements that are collapsed.

Returns:

Returns the appearance of the link between collapsed elements. The link object includes any of the following:

type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round)
dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides
width {number}, specifies the link's width or size (1 by default)
color {string}, indicates the link's color (partial-black by default)
arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default)
arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2)
arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2)
style {array}, specifies the link's dash pattern to show the lines (solid by default)
startPos {any}, indicates the in-element's corners, the link can start from
endPos {any}, indicates the out-element's corners , the link ends into

Type: DisplayLinkType

Example

The following statements are equivalent:

  oSurface.GetCollapsedLink() {DisplayLinkType}, gets the appearance of the link between collapsed elements
  oSurface.CollapsedLink {DisplayLinkType}, gets the appearance of the link between collapsed elements
  
where oSurface is an instance of Surface object

GetCollapsedLink

GetCoord() → {Surface.CoordEnum}

The GetCoord() method gets the coordinate system used to display the elements of the surface. It can be set to different values to control how element coordinates are interpreted and displayed. This allows you to choose between coordinate systems such as Cartesian or default coordinates, and to specify whether only positive coordinates should be used.

Returns:

Returns the type of coordinates the elements of the surface display in.

The Surface.CoordEnum type defines the following flags:

exDefCoord(0), the positive coordinates are shown right-down to origin of the surface.
exCartesian(1), the elements show in Cartesian coordinates. The positive coordinates are shown right-up to origin of the surface.
exAllowPositiveOnly(0x10), only the positive panel of the surface is shown. The exAllowPositiveOnly flag can be combined with exDefCoord or exCartesian value. For instance, the exCartesian + exAllowPositiveOnly indicates that surface displays only the positive coordinates in Cartesian system.

Type: Surface.CoordEnum

Example

The following statements are equivalents:

 oSurface.GetCoord() {number}, gets the current coordinate system used to display the elements of the surface
 oSurface.Coord {number}, gets the current coordinate system used to display the elements of the surface

where oSurface is an instance of Surface control

GetCoord

GetCursors() → {string}

The GetCursors() method specifies the mouse cursor to be displayed when pointing over a part of the control. Parts that can be customized include element, expand, and others, each corresponding to a different UI component - for example, element affects the cursor when hovering over any element, while expand defines the cursor when hovering over expand/collapse glyphs. The Cursors property allows you to assign different mouse cursors to control parts, enhancing the user experience by providing visual feedback on interactive areas. For instance, the string "pointer(element),crosshair(expand)" applies a pointer cursor to the element part and a crosshair cursor to the expand part of the control.

Returns:

A string expression that defines the mouse cursor to display when pointing over different parts of the control.

The format of the property is:

"cursor(part),cursor(part),..."

where:

"cursor", defines the CSS mouse cursor to display while cursor hovers the part
"part", defines the name of the part the cursor is applied on (as defined bellow)

The "cursor" can be any of the following:

Cursor Description

"alias" indicates a shortcut or alias will be created

"all-scroll" indicates scrolling in any direction

"auto" lets the browser decide the cursor based on context

"cell" indicates a table cell

"col-resize" indicates a column can be resized horizontally

"context-menu" indicates a context menu is available

"copy" indicates something will be copied

"crosshair" a precise crosshair cursor

"default" the default arrow cursor

"e-resize" resize east (right edge)

"ew-resize" resize horizontally

"grab" indicates an item can be grabbed

"grabbing" indicates an item is being grabbed

"help" indicates help information is available

"move" indicates something can be moved

"n-resize" resize north (top edge)

"ne-resize" resize northeast (top-right corner)

"nesw-resize" resize along the northeast–southwest axis

"no-drop" indicates dropping is not permitted

"not-allowed" indicates the action is not allowed

"ns-resize" resize vertically

"nw-resize" resize northwest (top-left corner)

"nwse-resize" resize along the northwest–southeast axis

"pointer" the pointer cursor (a hand with a pointing finger)

"progress" indicates background processing

"row-resize" indicates a row can be resized vertically

"s-resize" resize south (bottom edge)

"se-resize" resize southeast (bottom-right corner)

"sw-resize" resize southwest (bottom-left corner)

"text" the text selection cursor (I-beam)

"url(...)" uses a custom cursor image (with optional fallback)

"vertical-text" the vertical text selection cursor

"w-resize" resize west (left edge)

"wait" indicates the program is busy

"zoom-in" indicates zooming in

"zoom-out" indicates zooming out

Cursor	Description
"alias"	indicates a shortcut or alias will be created
"all-scroll"	indicates scrolling in any direction
"auto"	lets the browser decide the cursor based on context
"cell"	indicates a table cell
"col-resize"	indicates a column can be resized horizontally
"context-menu"	indicates a context menu is available
"copy"	indicates something will be copied
"crosshair"	a precise crosshair cursor
"default"	the default arrow cursor
"e-resize"	resize east (right edge)
"ew-resize"	resize horizontally
"grab"	indicates an item can be grabbed
"grabbing"	indicates an item is being grabbed
"help"	indicates help information is available
"move"	indicates something can be moved
"n-resize"	resize north (top edge)
"ne-resize"	resize northeast (top-right corner)
"nesw-resize"	resize along the northeast–southwest axis
"no-drop"	indicates dropping is not permitted
"not-allowed"	indicates the action is not allowed
"ns-resize"	resize vertically
"nw-resize"	resize northwest (top-left corner)
"nwse-resize"	resize along the northwest–southeast axis
"pointer"	the pointer cursor (a hand with a pointing finger)
"progress"	indicates background processing
"row-resize"	indicates a row can be resized vertically
"s-resize"	resize south (bottom edge)
"se-resize"	resize southeast (bottom-right corner)
"sw-resize"	resize southwest (bottom-left corner)
"text"	the text selection cursor (I-beam)
"url(...)"	uses a custom cursor image (with optional fallback)
"vertical-text"	the vertical text selection cursor
"w-resize"	resize west (left edge)
"wait"	indicates the program is busy
"zoom-in"	indicates zooming in
"zoom-out"	indicates zooming out

The "part" can be any of the following:

Cursor Description

"anchor" (hyperlink) defines the mouse-cursor when the mouse pointer hovers the anchor (the <a> ex-HTML part marks an anchor or hyperlink element) (@since 2.2)

"drag-drop" defines the cursor while the node is being dragged using the "drag-drop" action

"element" defines the mouse-cursor when the mouse pointer hovers any element. The cursor field defines the element's indiviual cursor.

"expand" (expand/collapse) defines the mouse-cursor when the mouse pointer hovers the element's expand/collapse glyphs

"link-cp" (link-control-point) defines the mouse-cursor when the mouse pointer hovers any link's control point

"link-cp-all" (link-control-point-all) defines the mouse-cursor when the mouse pointer hovers any link's control point (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

"link-cp-h" (link-control-point-horizontal) defines the mouse-cursor when the mouse pointer hovers a horizontal line (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

"link-cp-v" (link-control-point-vertical) defines the mouse-cursor when the mouse pointer hovers a vertical line (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

Cursor	Description
"anchor" (hyperlink)	defines the mouse-cursor when the mouse pointer hovers the anchor (the <a> ex-HTML part marks an anchor or hyperlink element) (@since 2.2)
"drag-drop"	defines the cursor while the node is being dragged using the "drag-drop" action
"element"	defines the mouse-cursor when the mouse pointer hovers any element. The cursor field defines the element's indiviual cursor.
"expand" (expand/collapse)	defines the mouse-cursor when the mouse pointer hovers the element's expand/collapse glyphs
"link-cp" (link-control-point)	defines the mouse-cursor when the mouse pointer hovers any link's control point
"link-cp-all" (link-control-point-all)	defines the mouse-cursor when the mouse pointer hovers any link's control point (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)
"link-cp-h" (link-control-point-horizontal)	defines the mouse-cursor when the mouse pointer hovers a horizontal line (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)
"link-cp-v" (link-control-point-vertical)	defines the mouse-cursor when the mouse pointer hovers a vertical line (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

The exswimlane/js control supports additional parts as listed in the table below:

Cursor Description

"pool" (pool) defines the mouse-cursor when the mouse pointer hovers any pool

Cursor	Description
"pool" (pool)	defines the mouse-cursor when the mouse pointer hovers any pool

Type: string

Example

The following statements are equivalent:

 oSurface.GetCursors() {string}, gets the current mouse cursor settings for all parts of the control
 oSurface.Cursors {string}, gets the current mouse cursor settings for all parts of the control

where oSurface is an instance of Surface object

GetCursors

GetElements() → {Elements}

The GetElements() method gets the control's elements. The elements are the building blocks of the control, as they represent the objects that are displayed and manipulated within the control. The control's elements can be accessed and managed using the Elements property, which returns an object of Elements type that provides methods and properties to work with the control's elements. You can use the Elements property to add, remove, or modify elements within the control, as well as to retrieve information about the existing elements.

Returns:

Returns an object of Elements type, that represents the control's elements.

Type: Elements

Example

The following statements are equivalents:

 oSurface.GetElements() {Elements}, gets the control's Elements collection
 oSurface.Elements {Elements}, gets the control's Elements collection
 
where oSurface is an object of Surface type.

GetElements

GetExpandGlyphSize() → {number}

The GetExpandGlyphSize() method specifies the size of the element's expand/collapse glyphs. These glyphs indicate whether an element can be expanded to show its children or collapsed to hide them. ExpandGlyphSize controls the dimensions of these glyphs, allowing you to adjust their visibility based on your design preferences. Setting this property to 0 hides the expand/collapse glyphs, while a positive value (for example 24) displays them at the specified size (such as 24x24 pixels). The Element.Expand property indicates whether an element is expanded or collapsed, and the "expand" part of the Shapes property defines the appearance of the expand/collapse glyphs.

Returns:

Returns the size to show the element's expand/collapse glyphs.

Type: number

Example

The following statements are equivalent:

 oSurface.GetExpandGlyphSize() {number}, gets the size to show the element's expand/collapse glyphs
 oSurface.ExpandGlyphSize {number}, gets the size to show the element's expand/collapse glyphs

where oSurface is an instance of Surface type

GetExpandGlyphSize

GetFocusLink() → {Link}

The GetFocusLink() method gets the focused link, whose path the user can modify by dragging its control points when the AllowLinkControlPoint property enables them. The FocusLink property can be set to specify the focused link on the surface or read to retrieve the currently focused link. The "link-bs", "link-be", "link-m", and "link-p" parts of the Shapes property define the appearance of the link's control points (beginning, end, middle, and path control points, respectively). The onfocuslink event notifies your application when the user focuses on a new link.

Since:

Returns:

Returns null (no link has been focused) or the link being focused as an object of Link type

Type: Link

Example

The following statements are equivalents:

 oSurface.GetFocusLink() {Link}, gets the current focused link as an object of Link type
 oSurface.FocusLink {Link}, gets the current focused link as an object of Link type

where oSurface is an instance of Surface control.

GetFocusLink

GetFormatText() → {exontrol.DrawTextFormatEnum}

The GetFormatText() method specifies the format used to display labels or captions on the control. It is a bitwise combination of flags that control text alignment, word-breaking, tab expansion, and other rendering options. For example, you can align text to the center, enable word-breaking for long captions, or display text on a single line. The available flags are defined in the exontrol.DrawTextFormatEnum type and can be combined to achieve the desired text formatting.

Returns:

Returns a value of exontrol.DrawTextFormatEnum type, that defines the format to display the element's caption.

The exontrol.DrawTextFormatEnum type support the following flags:

exTextAlignTop (0x00), justifies the text to the top of the rectangle
exTextAlignLeft (0x00), aligns text to the left
exTextAlignCenter (0x01), centers text horizontally in the rectangle
exTextAlignRight (0x02), aligns text to the right
exTextAlignVCenter (0x04), centers text vertically
exTextAlignBottom (0x08), justifies the text to the bottom of the rectangle.
exTextAlignMask (0x0F), specifies the mask for text's alignment.
exTextWordBreak (0x10), breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line. If this is not specified, output is on one line.
exTextSingleLine (0x20), displays text on a single line only. Carriage returns and line feeds do not break the line.
exTextExpandTabs (0x40), expands tab characters. The default number of characters per tab is eight.
exPlainText (0x80), treats the text as plain text.
exTextNoClip (0x0100), draws without clipping.
exHTMLTextNoColors (0x0200), ignores the and tags.
exTextCalcRect (0x0400), determines the width and height of the text.
exHTMLTextNoTags (0x0800), ignores all HTML tags.
exTextPathEllipsis (0x4000), for displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, exTextPathEllipsis preserves as much as possible of the text after the last backslash.
exTextEndEllipsis (0x8000), for displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses.
exTextWordEllipsis (0x040000), truncates any word that does not fit in the rectangle and adds ellipses.

Type: exontrol.DrawTextFormatEnum

Example

The following statements are equivalents:

 oSurface.GetFormatText() {exontrol.DrawTextFormatEnum}, gets the format to display the element's caption
 oSurface.FormatText {exontrol.DrawTextFormatEnum}, gets the format to display the element's caption

where oSurface is an object of Surface type.

GetFormatText

GetImageAlign() → {number}

The GetImageAlign() method gets the alignment of the image within the element, while the ImageSize property defines its dimensions. Together, they control how the image is displayed within the element, with ImageSize specifying the image's size and ImageAlign determining its position relative to the caption.

Returns:

Returns the alignment of the element's image as one of the following:

0, the image is on the left of the element's caption
1, the image is on the right of the element's caption
2, the image is on the top of the element's caption
3, the image is on the bottom of the element's caption

Type: number

Example

The following statements are equivalents:

 oSurface.GetImageAlign() {number}, gets the alignment of the element's image
 oSurface.ImageAlign {number}, gets the alignment of the element's image

where oSurface is an object of Surface type.

GetImageAlign

GetImageSize() → {any}

The GetImageSize() method gets the size of the element's image, and the ImageAlign property defines its alignment within the element. Together, they control how the image is displayed relative to the caption. ImageSize sets the image dimensions, while ImageAlign determines its position in relation to the caption. For captions or labels that support ex-HTML formatting, images can be included using the ex-HTML tag; however, ImageSize does not affect these images. The tag supports a size attribute to specify the image's dimensions, for example: apple:182002 sets the image named "apple" to size 18.

Returns:

Returns the size, range of limits the element's image is displayed as expalined:

{null}, indicates that the element's image is displayed as it is (full-sized).
{number}, specifies that the element's image is displayed into a square of giving size (same width and height). If 0 the element displays no image, if negative the element's image is stretched to giving square, else the element's picture is scaled to fit the giving rectangle.
{array}, specifies an array of [aspect-width,aspect-height] type that defines the limits for width or/and height. The aspect-width and aspect-height define the width/height of the element's picture to scale or stretch to.

Type: any

Example

The following statements are equivalents:

 oSurface.GetImageSize() {any}, gets the size of the element's image
 oSurface.ImageSize {any}, gets the size of the element's image

where oSurface is an object of Surface type.

GetImageSize

GetLink() → {DisplayLinkType}

The GetLink() method gets the default appearance of links between elements, including settings such as line style, color, thickness, and other visual attributes. The ShowLinks property determines whether links are displayed in the control. You can further customize link appearance based on their relationship to selected elements:

LinkStartFrom property, defines the appearance of links starting from a selected element (outgoing links)
LinkEndTo property, defines the appearance of links ending at a selected element (incoming links)
LinkUnselected property, defines the appearance of links not related to any selected element (unselected links)

Returns:

Returns the appearance of the link between elements. The link object includes any of the following:

type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round)
dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides
width {number}, specifies the link's width or size (1 by default)
color {string}, indicates the link's color (partial-black by default)
arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default)
arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2)
arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2)
style {array}, specifies the link's dash pattern to show the lines (solid by default)
startPos {any}, indicates the in-element's corners, the link can start from
endPos {any}, indicates the out-element's corners , the link ends into

Type: DisplayLinkType

Example

oSurface.GetLink() {object}, gets the default appearance of links between elements

GetLink

GetLinkEndTo() → {DisplayLinkType}

The GetLinkEndTo() method gets the appearance of links that end at selected elements (incoming links). It allows customization of line style, color, thickness, and other visual attributes to distinguish incoming links from other connections. The SV.SetLink method defines the default appearance of links between elements, and the ShowLinks property controls whether links are displayed in the control.

Returns:

Returns the appearance of the link that ends to any selected-element (incoming links). It can include any of the following:

type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round)
dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides
width {number}, specifies the link's width or size (1 by default)
color {string}, indicates the link's color (partial-black by default)
arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default)
arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2)
arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2)
style {array}, specifies the link's dash pattern to show the lines (solid by default)
startPos {any}, indicates the in-element's corners, the link can start from
endPos {any}, indicates the out-element's corners , the link ends into

Type: DisplayLinkType

Example

The following statements are equivalent:

 oSurface.GetLinkEndTo() {DisplayLinkType}, gets the appearance of the link that ends to any selected-element (incoming links)
 oSurface.LinkEndTo {DisplayLinkType}, gets the appearance of the link that ends to any selected-element (incoming links)

where oSurface is an instance of Surface object

GetLinkEndTo

GetLinkStartFrom() → {DisplayLinkType}

The GetLinkStartFrom() method gets the appearance of links that start from selected elements (outgoing links). It allows customization of line style, color, thickness, and other visual attributes to distinguish outgoing links from other connections. The SV.SetLink method defines the default appearance of links between elements, and the ShowLinks property determines whether links are displayed in the control.

Returns:

Returns the appearance of the link that starts from any selected-element (outgoing links). It can include any of the following:

type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round)
dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides
width {number}, specifies the link's width or size (1 by default)
color {string}, indicates the link's color (partial-black by default)
arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default)
arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2)
arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2)
style {array}, specifies the link's dash pattern to show the lines (solid by default)
startPos {any}, indicates the in-element's corners, the link can start from
endPos {any}, indicates the out-element's corners , the link ends into

Type: DisplayLinkType

Example

The following statements are equivalent:

 oSurface.GetLinkStartFrom() {DisplayLinkType}, gets the appearance of the link that starts from any selected-element (outgoing links)
 oSurface.LinkStartFrom {DisplayLinkType}, gets the appearance of the link that starts from any selected-element (outgoing links)

where oSurface is an instance of Surface object

GetLinkStartFrom

GetLinkUnselected() → {DisplayLinkType}

The GetLinkUnselected() method gets the appearance of links that are not connected to any selected elements (unselected links). It allows customization of line style, color, thickness, and other visual attributes to visually distinguish unselected links from those related to selected elements. The SV.SetLink method defines the default appearance of links between elements, and the ShowLinks property controls whether links are displayed in the control.

Returns:

Returns the appearance of the link not related to any selected-element (unselected links). It can include any of the following:

type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round)
dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides
width {number}, specifies the link's width or size (1 by default)
color {string}, indicates the link's color (partial-black by default)
arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default)
arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2)
arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2)
style {array}, specifies the link's dash pattern to show the lines (solid by default)
startPos {any}, indicates the in-element's corners, the link can start from
endPos {any}, indicates the out-element's corners , the link ends into

Type: DisplayLinkType

Example

The following statements are equivalent:

 oSurface.GetLinkUnselected() {DisplayLinkType}, gets the appearance of the link not related to any selected-element (unselected links)
 oSurface.LinkUnselected {DisplayLinkType}, gets the appearance of the link not related to any selected-element (unselected links)

where oSurface is an instance of Surface object

GetLinkUnselected

GetLinks() → {Links}

The GetLinks() method returns the control's links. The links represent the connections or relationships between the elements within the control. The control's links can be accessed and managed using the Links property, which returns an object of Links type that provides methods and properties to work with the control's links. You can use the Links property to add, remove, or modify links between elements within the control, as well as to retrieve information about the existing links.

Returns:

Returns an object of Links type

Type: Links

Example

The following statements are equivalents:

 oSurface.GetLinks() {Links}, gets the control's Links collection
 oSurface.Links {Links}, gets the control's Links collection

where oSurface is an object of Surface type.

GetLinks

GetLocked() → {boolean}

The GetLocked() method specifies whether the control is locked (protected) or unlocked.

When Locked is set to true, the control is fully locked and users cannot scroll, select, or interact with any element within the control.
When Locked is false, the control behaves normally, allowing users to scroll, select, and interact with its elements.

In contrast, when the control is read-only, users cannot create, resize, or move elements, but they can still scroll, select, and interact with existing elements. Therefore, Locked mode completely prevents user interaction with the control, while read-only mode only prevents modifications to the elements.

Returns:

Returns true, if the control is locked(protected) or unlocked

Type: boolean

Example

The following statements are equivalent:

 oSurface.GetLocked() {boolean}, returns true, if the control is locked(protected) or unlocked
 oSurface.Locked {boolean}, returns true, if the control is locked(protected) or unlocked

where oSurface is an instance of Surface control

GetLocked

GetMajorGridLines() → {object}

The GetMajorGridLines() method gets the appearance of major grid-lines, as an object of {step, width, color, style, cap} type. The MinorGridLines property defines the appearance of the surface's minor grid lines in the same format. The ShowGridLines property specifies whether the control displays both minor and major grid lines. When ShowGridLines is true, the grid lines are displayed according to the specifications in MinorGridLines and MajorGridLines. When false, the grid lines are hidden regardless of their specified appearance. The AlignObjectsToGridLines property specifies whether objects are aligned to minor or major grid lines when they are moved or resized.

Since:

Returns:

Returns an object of {step, width, color, style, cap} type as explained:

step, {number} specifies the distance between two consecutive major grid-lines (100 by default) (if 0 the major grid-lines are ignored). For instance:
null {null}, the distance between two consecutive major grid-lines is 10 (default value)
0 {number}, the major grid-lines are ignored
5 {number}, show the major grid-lines from 5 to 5
width, {number} specifies the line's width or size (1 by default) (if 0 no major grid-lines are shown). For instance:
null {null}, indicates line of 1-pixel wide (default value)
0 {number}, indicates that no major grid-lines are shown
2 {number}, indicates line of 2-pixels wide
color, {string} indicates the line's color ("#E8E8E8" by default). For instance:
null {null}, indicates a light gray line (default value)
"transparent" {string}, specifies a transparent line
"red" {string}, specifies a red line
"#00FF00" {string}, specifies a green line
"rgba(255,0,0,0.5)" {string}, indicates 50% red line
style, {array} defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance:
null {null} or [] {array}, defines solid grid-lines (default style)
2 {number}, becomes [2, 2, ...]
[5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
cap {string}, determines the shape used to draw the end points of lines ("but" by default).
Determines the shape used to draw the end points of lines, as one of the following:
- "butt" {string}, the ends of lines are squared off at the endpoints.
- "round" {string}, the ends of lines are rounded
- "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness
For instance:

null {null}, "butt" ends (default value)
"round" {string}, the ends of lines are rounded

Type: object

Example

The following statements are equivalents:

 oSurface.GetMajorGridLines() {object}, gets the appearance of the surface's major grid lines
 oSurface.MajorGridLines {object}, gets the appearance of the surface's major grid lines

where oSurface is an instance of Surface control

GetMajorGridLines

GetMargins() → {object}

The GetMargins() method indicates the control's margins and spacing. It is an object of the form {x, y, indent, border}, where x is the horizontal distance between elements, y is the vertical distance, indent is the indentation for nested elements, and border is the distance from the control's edges. You can use the Margins property to adjust spacing around and between elements, improving the visual layout and organization. By default, Margins is {border: 16, x: 2, y: 2, indent: 16}, meaning the control has a 16-pixel border, 2-pixel horizontal and vertical spacing, and a 16-pixel indent.

Returns:

Returns an object of {x,y,indent,border} type that specifies the horizontal and vertical distance between elements.

Type: object

Example

The following statements are equivalent:

 oSurface.GetMargins() {object}, returns an object of {x,y,indent,border} type that specifies the horizontal and vertical distance between elements
 oSurface.Margins {object}, returns an object of {x,y,indent,border} type that specifies the horizontal and vertical distance between elements

where oSurface is an instance of Surface control

GetMargins

GetMinorGridLines() → {object}

The GetMinorGridLines() method gets the appearance of the surface's minor grid lines as an object of {step, width, color, style, cap} type. The MajorGridLines property defines the appearance of the surface's major grid lines in the same format. The ShowGridLines property specifies whether the control displays both minor and major grid lines. When ShowGridLines is true, the grid lines are displayed according to the specifications in MinorGridLines and MajorGridLines. When false, the grid lines are hidden regardless of their specified appearance. The AlignObjectsToGridLines property specifies whether objects are aligned to minor or major grid lines when they are moved or resized.

Since:

Returns:

Returns an object of {step, width, color, style, cap} type as explained:

step, {number} specifies the distance between two consecutive minor grid-lines (10 by default) (if 0 the minor grid-lines are ignored). For instance:
null {null}, the distance between two consecutive minor grid-lines is 10 (default value)
0 {number}, the minor grid-lines are ignored
5 {number}, show the minor grid-lines from 5 to 5
width, {number} specifies the line's width or size (1 by default) (if 0 no minor grid-lines are shown). For instance:
null {null}, indicates line of 1-pixel wide (default value)
0 {number}, indicates that no minor grid-lines are shown
2 {number}, indicates line of 2-pixels wide
color, {string} indicates the line's color ("#F8F8F8" by default). For instance:
null {null}, indicates a light gray line (default value)
"transparent" {string}, specifies a transparent line
"red" {string}, specifies a red line
"#00FF00" {string}, specifies a green line
"rgba(255,0,0,0.5)" {string}, indicates 50% red line
style, {array} defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance:
null {null} or [] {array}, defines solid grid-lines (default style)
2 {number}, becomes [2, 2, ...]
[5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
cap {string}, determines the shape used to draw the end points of lines ("but" by default).
Determines the shape used to draw the end points of lines, as one of the following:
- "butt" {string}, the ends of lines are squared off at the endpoints.
- "round" {string}, the ends of lines are rounded
- "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness
For instance:

null {null}, "butt" ends (default value)
"round" {string}, the ends of lines are rounded

Type: object

Example

The following statements are equivalents:

 oSurface.GetMinorGridLines() {object}, gets the appearance of the surface's minor grid lines
 oSurface.MinorGridLines {object}, gets the appearance of the surface's minor grid lines

where oSurface is an instance of Surface control

GetMinorGridLines

GetOptions() → {Surface.Options}

The GetOptions() method gets the current options of the control. The options include different fields to specify the control's appearance such as showLinks, shapes, cursors, and so on. The options are stored in an object of Surface.Options type.

Every option of the Surface.Options type has associated a property of the link. For instance, the option:

showLinks, defines whether to show the links between elements

is associated with the property:

ShowLinks {string}, defines whether to show the links between elements

which means that the following statements are equivalent:

oSurface.Options = {showLinks: "show"}
oSurface.SetOptions({showLinks: "show"})
oSurface.ShowLinks = "show"
oSurface.SetShowLinks("show")

where oSurface is a reference to the Surface control.

It is important to note that changing a field of the Options object does not automatically update the control. For example, oSurface.Options.showLinks = "show" does not apply the change. Instead, you must assign the Options property again, such as oSurface.Options = {showLinks: "show"}, so the control updates and applies the new value.

Returns:

An object of Surface.Options type that indicates the options to display the control.

Type: Surface.Options

Example

The following statements are equivalent:

 oSurface.GetOptions() {object}, gets the current options of the control as an object of Surface.Options type
 oSurface.Options {object}, gets or sets the current options of the control as an object of Surface.Options type

where oSurface is a reference to the Surface control.

GetOptions

GetOrigin() → {object}

The GetOrigin() method specifies the appearance of the surface origin as an object of {size, width, color, style, cap} type. The origin represents the point (0,0) on the surface and is typically displayed as a cross. The ShowOrigin property determines whether the origin is visible. The Origin property allows you to customize the origin's appearance, including its size, color, line style, and other visual attributes.

Since:

Returns:

Returns an object of {size, width, color, style, cap} type as explained:

size, {number} indicates the size of the origin (the size of the cross) (8 by default). For instance:
null {null}, defines an 8-pixels wide cross (default size)
16 {number}, defines a 16-pixels wide cross
width, {number} specifies the line's width or size (1 by default) (if 0 no surface's origin is shown). For instance:
null {null}, indicates line of 1-pixel wide (default width)
0 {number}, indicates that no surface's origin is shown
2 {number}, indicates line of 2-pixels wide
color, {string} indicates the line's color (black by default). For instance:
null {null}, indicates a black line (default color)
"transparent" {string}, specifies a transparent line
"red" {string}, specifies a red line
"#00FF00" {string}, specifies a green line
"rgba(255,0,0,0.5)" {string}, indicates 50% red line
style, {array} defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance:
null {null} or [] {array}, defines solid grid-lines (default style)
2 {number}, becomes [2, 2, ...]
[5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
cap {string}, determines the shape used to draw the end points of lines ("but" by default).
Determines the shape used to draw the end points of lines, as one of the following:
- "butt" {string}, the ends of lines are squared off at the endpoints.
- "round" {string}, the ends of lines are rounded
- "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness
For instance:

null {null}, "butt" ends (default value)
"round" {string}, the ends of lines are rounded

Type: object

Example

The following statements are equivalents:

 oSurface.GetOrigin() {object}, gets the current appearance of the surface origin
 oSurface.Origin {object}, gets the current appearance of the surface origin

where oSurface is an instance of Surface control

GetOrigin

GetPad() → {number|Array.<number>|string}

The GetPad() method gets the space between an element's content and its border. It can be a single number for equal horizontal and vertical padding, or a pair of values ("x,y" or [x, y]) for different horizontal and vertical padding. For example, 8 adds 8 pixels on all sides, while "8,4" adds 8 pixels horizontally and 4 pixels vertically. The Surface.Pad property defines a default padding for all elements, which can be overridden for individual elements using Element.Pad property.

Returns:

Returns a value that could be:

{number} a numeric value, to pad horizontal and vertical size with the same value
{(number[]|string)} a "x,y" or [x,y] type to specify the padding on h/v size

Type: number | Array.<number> | string

Example

The following statements are equivalents:

 oSurface.GetPad() {(number|number[]|string)}, gets the space between an element's content and its border
 oSurface.Pad {(number|number[]|string)}, gets the space between an element's content and its border

where oSurface is an object of Surface type.

GetPad

GetReadOnly() → {string}

The GetReadOnly() method defines whether the control is in read-only mode. When the control is set to read-only, users can still scroll, select, and interact with existing elements, but they cannot create, resize, or move any element within the control. This allows users to view and interact with the content without making any modifications to it. The Locked property, on the other hand, completely prevents user interaction with the control, while read-only mode only prevents modifications to the elements.

Returns:

Returns true, if the control is read-only

Type: string

Example

The following statements are equivalent:

 oSurface.GetReadOnly() {boolean}, returns true, if the control is read-only
 oSurface.ReadOnly {boolean}, returns true, if the control is read-only

where oSurface is an instance of Surface control

GetReadOnly

GetScrollBarsHome() → {string}

The GetScrollBarsHome() method specifies the color used to highlight the position of the origin (0,0) on the control's scroll bars. It accepts a CSS color to display the origin marker, or null to hide it. The ScrollBarsLayout property specifies the color used to highlight the position of the current layout within the control's scroll bars. It accepts a CSS color to display the layout marker, or null to hide it. To display these markers, the ScrollBars property must be set to a value other than exNoScroll so the control shows scroll bars. Additionally, ScrollBarsHome must be set to a CSS color to display the origin marker. By default, ScrollBarsHome is set to "black", which highlights the position of the origin (0,0) on the scroll bars. This feature is useful when the control's content extends in multiple directions from the origin, as it helps users quickly identify their position relative to (0,0) and navigate the content more easily. The onscroll event is fired whenever the user scrolls the control's content. This event can be used to implement custom behavior when the user scrolls, such as updating the position of other elements on the page or loading additional content dynamically. The user can right-click on the scroll bars over the origin marker to automatically scroll the control's content to the origin position (0,0).

Returns:

Indicates null, to prevent showing the position of origin (0,0) on the control's scroll bars, or a CSS color

Type: string

Example

The following statements are equivalent:

 oSurface.GetScrollBarsHome() {string}, gets the color used to highlight the position of the origin (0,0) on the control's scroll bars
 oSurface.ScrollBarsHome {string}, gets the color used to highlight the position of the origin (0,0) on the control's scroll bars

where oSurface is an instance of the Surface control

GetScrollBarsHome

GetScrollBarsLayout() → {string}

The GetScrollBarsLayout() method gets the color used to highlight the position of the current layout within the control's scroll bars. It can be set to a CSS color to display the layout marker, or null to hide it. To display this marker, the ScrollBars property must be set to a value other than exNoScroll so the control shows scroll bars. The onscroll event is fired whenever the user scrolls the control's content. By default, ScrollBarsLayout is null, so the position of the current layout is not shown on the scroll bars. This feature is useful when the control's content extends in multiple directions from the origin, as highlighting the current layout on the scroll bars helps users easily identify their position relative to the layout and navigate the content more effectively. The user can right-click on the scroll bars over the layout marker to automatically scroll the control's content to the current layout position.

Returns:

Indicates null, to prevent showing the position of current layout within the control's scrollbars, or a CSS color

Type: string

Example

The following statements are equivalent:

 oSurface.GetScrollBarsLayout() {string}, gets the color used to highlight the position of current layout within the control's scroll bars
 oSurface.ScrollBarsLayout {string}, gets the color used to highlight the position of current layout within the control's scroll bars

where oSurface is an instance of the Surface control

GetScrollBarsLayout

GetSelection() → {array}

The GetSelection() method gets the elements currently selected in the control. Selected elements are highlighted with a specific color to indicate their selection state. The "select" part of the shapes field defines the appearance of the selected elements, including their color, border, and other visual attributes. The Selection property can be used to set or retrieve the selected elements. It accepts or returns values that identify the elements selected within the control. This property is automatically updated when the Selection property changes or when the user selects or unselects elements in the control. The SingleSel property determines the selection mode of the control. When SingleSel is true, only one element can be selected at a time. When false, multiple elements can be selected simultaneously. The onselchange event is fired whenever the control's selection changes, either by user interaction or programmatically through the Selection property. This event can be used to implement custom behavior when the selection changes, such as updating other parts of the user interface or performing actions based on the selected elements.

Returns:

The GetSelection can return one of the following:

{null}, indicates that the control has no selected-elements {Element}, indicates a single-selected element (while the control support single-selection only) {Element[]}, defines a collection of selected-elements within the control.

Type: array

Example

The following statements are equivalents:

 oSurface.GetSelection() {any}, gets the control's selection, which can be null, a single element or an array of elements
 oSurface.Selection {any}, gets the control's selection, which can be null, a single element or an array of elements

where oSurface is an instance of Surface type.

GetSelection

GetSelements()

The GetSelements() method defines the elements of the control from a string representation. The Selements property is optional, because you can always use the Elements.Add method to add elements individually. However, it is very useful when you want to quickly define the control's elements using a string. The Selements property provides a getter and a setter to handle the control's elements as a string: the setter calls Elements.Load(), which reads the assigned string and creates the corresponding elements in the control, while the getter calls Elements.Save(), returning a string that represents all current elements in the control. This makes it easy to define, store, or transfer the elements using a string representation.

The format of the string representation is (everything between () refers to children, and everything between [] refers to flags):

"element1[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value]),...,elementn[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value])"

where the element1, sub-element1 ... elementn defines the caption for each element (can include ex-HTML tags).

The string representation supports the following flags:

[key] {string}, specifies the element's key (Key/GetKey()/SetKey(value) methods of Surface.Element). For instance, [key=root], specifies that the element's key is "root"
[vis]/[hid] {number}, shows or hides the element (Visible/GetVisible()/SetVisible(value) methods of Surface.Element). For instance, [hid] or [vis=0], hides the element, while [vis=1] shows the element
[dis] {number}, enables or disables the element (Enabled/GetEnabled()/SetEnabled(value) methods of Surface.Element). For instance, [dis] or [dis=0], disables the element, while [dis=1] enables the element
[nsel] {number}, indicates whether the user can select, resize or move the element (Selectable/GetSelectable()/SetSelectable(value) methods of exontrol.Surface.Element). For instance, [nsel] or [nsel=0], forces the element to be unselectable, while [nsel=1] makes the element selectable
[pos] {number}, changes the element's position (0-based) (Position/GetPosition()/SetPosition(value) methods of Surface.Element). For instance, [pos=0] indicates that the element should be displayed first
[img] {string}, assigns a image/picture to the element (Image/GetImage()/SetImage(value) methods of Surface.Element). For instance, [img=logo] assigns the "logo" picture to the element. The image can be added using the exontrol.HTMLPicture.Add method. You can use the [simg] flag to define the element's image to be displayed on the "sub-items" portion of the control.
[imgs] {string}, defines the size of the element's image as a string of "aspect-width,aspect-height" type (without quotes) (ImageSize/GetImageSize()/SetImageSize(value) methods of Surface.Element). For instance, [imgs=-32] stretches the element's image into a square of 32x32 size, while [imgs=32,32] fits the element's image into a square of 32x32 size.
[imga] {number}, specifies the alignment of the image within the element relative to its caption. The value of "imga" flag can be 0(left), 1(right), 2(top) or 3(bottom). (ImageAlign/GetImageAlign()/SetImageAlign(value) methods of Surface.Element). For instance, [imga=3] aligns the element's image at the bottom of its box
[client] {string}, specifies the element's client-rectangle as a string of "x,y,width,height" type (without quotes) (Client/GetClient()/SetClient(value) methods of Surface.Element). For instance, [client=0,0,128,128] specifies the element's client are to [0,0,128,128]
[coll] {string}, indicates a collapsed-element (Expand/GetExpand()/SetExpand(value) methods of Surface.Element). For instance, [coll] or [coll=0], collapses the element, while [c=1] expands the element
[ft] {number}, specifies the format to display the element's caption. The value of "ft" flag can be a combination of one or more values of exontrol.DrawTextFormatEnum type (FormatText/GetFormatText()/SetFormatText(value) methods of Surface.Element). For instance, [ft=32] displays the element's caption on a single line only. Carriage returns and line feeds do not break the line (32 indicates the value of exontrol.DrawTextFormatEnum.exTextSingleLine)
[pad] {string}, defines the element's padding (space between the element's content and its border) (Pad/GetPad()/SetPad(value) methods of Surface.Element). For instance, [pad=4] defines a 4-pixels padding for all edges
[shape] {string}, defines the shape for individual element (Shape/GetShape()/SetShape(value) methods of Surface.Element). For instance, [shape=Button] specifies that the element is shown as a "button".
[cursor] {string}, defines the mouse-cursor for individual element (Cursor/GetCursor()/SetCursor(value) methods of Surface.Element). For instance, [cursor=wait] indicates that the "wait" mouse-cursor is displayed while the cursor hovers the element
[auto] {number}, resizes the element to fit its content (AutoSize/GetAutoSize()/SetAutoSize(value) methods of Surface.Element). For instance, [auto] resizes the element to fit its content
[nres] {number}, defines a non-resizable element (Resizable/GetResizable()/SetResizable(value) methods of Surface.Element). For instance, [nres] indicates that the user can not resize the element by drag and drop
[nmov] {number}, defines a non-movable element (Movable/GetMovable()/SetMovable(value) methods of Surface.Element). For instance, [nmov] indicates that the user can not move the element by drag and drop

Example

"" {string}, indicates that the control has no elements
"Root[key=root](Child 1[key=child1],Child 2[key=child2])" {string}, defines two root-elements with captions of "Root" and keys of "root", each of them has two children with captions of "Child 1" and "Child 2", and keys of "child1" and "child2" respectively. The elements are created in the default order, which is the same order as they are defined in the string (in this example, the "Root" element is created first, then its child "Child 1", and then its child "Child 2").

GetSelements

GetShapes() → {string}

The GetShapes() method gets the shapes that each part of the control can display, allowing you to customize its visual appearance. A shape can be specified as a JSON representation of a shape object, the name of a predefined shape within exontrol.Shapes.Surface or exontrol.Shapes, or a CSS color value. Parts that can be customized include element, expand, and others, each corresponding to a different UI component - for example, element affects all elements in the control, while expand defines the look of expand/collapse glyphs. The Shapes property enables you to apply different shapes and colors to control parts, enhancing its overall appearance. For instance, the string "red(element),blue(expand)" applies a red shape to the element part and a blue shape to the expand part of the control.

Returns:

A string expression that defines the shapes each part of the control can display.

The format of the property is:

"shape(part),shape(part),..."

where:

"shape", defines the shape to apply on the UI part as one of the following:
◦ any of 140 color names any browser supports (such as red, blue, green, ...)
◦ hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF (such as #0000ff which defines a blue background)
◦ hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF (such as #0000ff80 which defines a semi-transparent blue background)
◦ RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255( such as rgb(0,0,255) that defines a blue background)
◦ RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) ( such as rgba(0,0,255,0.5) which defines a semi-transparent blue background)
◦ HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors (such as hsl(240, 100%, 50%) that defines a blue background)
◦ HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) (such as hsla(240, 100%, 50%,0.5) that defines a semi-transparent blue background)
◦ a JSON representation of the shape object to apply (while it starts with { character, such as '{"normal": {"primitive": "RoundRect","fillColor":"black","tfi": {"fgColor": "white"}}}')
◦ specifies the name of the field within the exontrol.Shapes.Surface object (while it starts with a lowercase letter, such as element which refers to exontrol.Shapes.Surface.element shape)
◦ specifies the name of the field within the exontrol.Shapes object (while it starts with an uppercase letter, such as Button which refers to exontrol.Shapes.Button shape)
"part", defines the name of the part the shape is applied on (as defined bellow)

The shapes property supports any of the following parts:

Part Description

"element" defines the visual-appearance of all elements within the control. The shape field defines the shape for individual element.

"expand" specifies the visual appearance for expand/collapse glyphs. The expandGlyphSize field specifies the size to show the element's expand/collapse glyphs.

"frameDrag" specifies the visual appearance to display the frame while dragging the objects

"frameFit" defines the visual-appearance to display the frame while fitting objects into the control's client area by drag

"frameSel" defines the visual appearance to display a frame while selecting objects by drag

"link-be" defines the visual-appearance of the link's end control-point (it changes the end-position of the link)

"link-bs" defines the visual-appearance of the link's start control-point (it changes the start-position of the link)

"link-m" defines the visual-appearance of the link's middle control-point

"link-p" defines the visual-appearance of the link's intermediate control-point

"multiSel" specifies the visual appearance to show the count of multiple-selected items

"select" defines the visual-appearance of selected-element

Part	Description
"element"	defines the visual-appearance of all elements within the control. The shape field defines the shape for individual element.
"expand"	specifies the visual appearance for expand/collapse glyphs. The expandGlyphSize field specifies the size to show the element's expand/collapse glyphs.
"frameDrag"	specifies the visual appearance to display the frame while dragging the objects
"frameFit"	defines the visual-appearance to display the frame while fitting objects into the control's client area by drag
"frameSel"	defines the visual appearance to display a frame while selecting objects by drag
"link-be"	defines the visual-appearance of the link's end control-point (it changes the end-position of the link)
"link-bs"	defines the visual-appearance of the link's start control-point (it changes the start-position of the link)
"link-m"	defines the visual-appearance of the link's middle control-point
"link-p"	defines the visual-appearance of the link's intermediate control-point
"multiSel"	specifies the visual appearance to show the count of multiple-selected items
"select"	defines the visual-appearance of selected-element

The exswimlane/js control supports additional parts as listed in the table below:

Part Description

"header" defines the visual-appearance of all headers within the control

"lane" defines the visual-appearance of all lanes for all pools

"laneAlt" defines the visual-appearance of alternate lanes for all pools

"phase" defines the visual-appearance of all phases for all pools

"phaseAlt" defines the visual-appearance of alternate phases for all pools

"pool" defines the visual-appearance of all pools within the control

Part	Description
"header"	defines the visual-appearance of all headers within the control
"lane"	defines the visual-appearance of all lanes for all pools
"laneAlt"	defines the visual-appearance of alternate lanes for all pools
"phase"	defines the visual-appearance of all phases for all pools
"phaseAlt"	defines the visual-appearance of alternate phases for all pools
"pool"	defines the visual-appearance of all pools within the control

Type: string

Example

The following statements are equivalent:

 oSurface.GetShapes() {string}, returns a string expression that defines the shapes each part of the control can display
 oSurface.Shapes {string}, returns a string expression that defines the shapes each part of the control can display

where oSurface is an instance of the Surface control.

GetShapes

GetShowAxes() → {boolean}

The GetShowAxes() method specifies whether the control displays the axes (horizontal and vertical). The axes are typically represented by two perpendicular lines that intersect at the origin (0,0) of the surface. The Axes property defines the appearance of the axes as an object of {width, color, style, cap} type. ShowAxes allows you to control the visibility of the axes, which can be useful when working with diagrams or layouts that use a coordinate system. By default, ShowAxes is false, meaning the axes are hidden unless explicitly enabled.

Since:

Returns:

Returns true if the control shows the axes.

Type: boolean

Example

The following statements are equivalents:

 oSurface.GetShowAxes() {boolean}, specifies whether the control shows or hides the axes
 oSurface.ShowAxes {boolean}, specifies whether the control shows or hides the axes

where oSurface is an instance of Surface control

GetShowAxes

GetShowGridLines() → {boolean}

The GetShowGridLines() method specifies whether the control displays grid lines, including minor and major grid lines. The MinorGridLines and MajorGridLines properties define the appearance of the surface's minor and major grid lines, respectively. When ShowGridLines is true, the grid lines are displayed, providing a reference when working with coordinates. When false, the grid lines are hidden, offering a cleaner view. This property is especially useful for diagrams or layouts that rely on a coordinate system.

Since:

Returns:

Returns true if the control shows the grid lines (minor and major grid-lines).

Type: boolean

Example

The following statements are equivalents:

 oSurface.GetShowGridLines() {boolean}, gets whether the control shows the grid lines (minor and major grid-lines)
 oSurface.ShowGridLines {boolean}, gets whether the control shows the grid lines (minor and major grid-lines)
 
where oSurface is an instance of Surface control

GetShowGridLines

GetShowLinks() → {exontrol.ShowLinksEnum}

The GetShowLinks() method determines whether the control displays links between elements. It is a bitwise combination of flags that control the visibility and style of the links, such as extended, cross, or orthogonal, and whether they appear in front of or behind elements. For example, links can be shown as extended lines with cross-links at the corners, or all links can be hidden. The available flags are defined in exontrol.ShowLinksEnum and can be combined to achieve the desired link display.

Returns:

Returns an exontrol.ShowLinksEnum expression that specifies whether the links between elements are visible or hidden

The exontrol.ShowLinksEnum type supports the following flags:

exHide (0), specifies that no links are visible
exExtended (0x01) specifies that links are shown as extended. This means the control automatically arranges both the start and end points of the links so they do not overlap. For example, if multiple links start from or end at the same element, the control ensures that each link uses a different start or end point instead of all sharing the same position. This helps keep the connections visually separated and easier to distinguish.
exShow (0x02), specifies that links are visible (the links are always shown while not exHide)
exFront (0x10), specifies that links are shown in front (by default, the control are shown on the background)
exCrossRect (0x20) specifies that links are shown with rectangular cross-links. When two links intersect, the control displays the crossing using a rectangular bridge so one link appears to pass over the other without merging. This makes intersections easier to read and helps visually distinguish overlapping links.
exCrossTriangle (0x20) specifies that links are shown with triangular cross-links. When two links intersect, the control displays the crossing using a triangular marker so one link appears to pass over the other without merging. This helps clearly indicate link intersections and improves the readability of overlapping connections.
exCrossMixt (0x60) specifies that links are shown using mixed cross-links. When two links intersect, the control displays the crossing using a combination of cross-link styles (such as rectangular or triangular bridges) so one link appears to pass over the other without merging. This mixed representation helps visually distinguish intersections and improves the readability of overlapping links.
exPreventOverlap (0x100), adjusts the links to prevent them from overlapping the connected objects. The exPreventOverlap flag has effect only for rectangular links. The exPreventOverlap option calculates the path between A and B using the A* (A-star) pathfinding algorithm, which can be a time-consuming operation. The exontrol.L.PO.dir.def specifies the default directions for determining the best route between two points, A and B. These directions are represented as a combination of the letters R (Right), L (Left), U (Up), and D (Down), separated by commas ("RLDU,DURL" {string}, indicates the shortest route between RLDU and DURL directional path). When used with the exPreventOverlapMixt flag, it ensures that links avoid overlapping with elements or obstacles, enabling their paths to include both rectangular and diagonal lines. (@since 4.0)
exPreventOverlapMixt (0x80), When used with the exPreventOverlap flag, it ensures that links avoid overlapping with elements or obstacles, enabling their paths to include both rectangular and diagonal lines. When combined with the exChangeColorOnOverlap flag, overlapping links alternately adjust their width in addition to changing colors. The exPreventOverlapMixt flag must always be used alongside either the exPreventOverlap or exChangeColorOnOverlap flag. (@since 4.0)
exChangeColorOnOverlap (0x200), changes the color for links in areas where they overlap with other links, enhancing clarity and distinction between them. The exontrol.L.PO.OverlapColors defines the list of colors, separated by commas, used to display overlapping links. When combined with the exPreventOverlapMixt flag, overlapping links alternately adjust their width in addition to changing colors. (@since 4.0)

Type: exontrol.ShowLinksEnum

Example

The following statements are equivalent:

 oSurface.GetShowLinks() {number}, gets the current setting for showing links between elements
 oSurface.ShowLinks {number}, gets the current setting for showing links between elements

where oSurface is an instance of Surface object

GetShowLinks

GetShowLinksOnCollapse() → {boolean}

The GetShowLinksOnCollapse() method specifies whether links between collapsed elements are visible. It is a boolean value: when true, links between collapsed elements are shown, allowing users to see connections even when elements are collapsed; when false, these links are hidden for a cleaner view. The appearance of links between collapsed elements can be customized using the CollapsedLink property. The Element.Expand property indicates whether an element is expanded or collapsed.

Returns:

Returns true if links between collapsed elements are visible

Type: boolean

Example

The following statements are equivalent:

 oSurface.GetShowLinksOnCollapse() {boolean}, gets whether the links between collapsed elements are shown or hidden
 oSurface.ShowLinksOnCollapse {boolean}, gets whether the links between collapsed elements are shown or hidden
 
where oSurface is an instance of Surface object

GetShowLinksOnCollapse

GetShowOrigin() → {boolean}

The GetShowOrigin() method specifies whether the control displays the origin. The origin represents the point (0,0) on the surface and is typically shown as a cross. The Origin property defines the appearance of the origin as an object of {size, width, color, style, cap} type. When ShowOrigin is set to true or null, the origin is displayed, which can be useful as a reference when working with coordinates. When set to false, the origin is hidden, providing a cleaner view when the reference point is not needed. This property is useful when working with diagrams or layouts that rely on a coordinate system.

Since:

Returns:

Returns true if the control shows the origin.

Type: boolean

Example

The following statements are equivalents:

 oSurface.GetShowOrigin() {boolean}, gets whether the control shows the origin
 oSurface.ShowOrigin {boolean}, gets whether the control shows the origin

where oSurface is an instance of Surface control.

GetShowOrigin

GetSingleSel() → {Surface.SingleSelEnum}

The GetSingleSel() method specifies whether the control supports single, multiple, toggle selection. The selection mode of the control is determined by the SingleSel property, which can be set to enable single-selection, multiple-selection, or toggle selection. When single-selection is enabled, only one element can be selected at a time. When multiple-selection is enabled, users can select multiple elements simultaneously. When toggle selection is enabled, clicking on an element toggles its selection state (selected/unselected). The Selection property holds the control's selected elements. The selection behavior can be further customized using additional flags that control how users can select elements, such as disabling selection with modifier keys or by dragging.

Returns:

Returns an OR combination of exontrol.Surface.SingleSelEnum flags that specifies how to select notes

The Surface.SingleSelEnum type defines the following flags:

exDisableSel(0), specifies that the control's selection is disabled (can not be combined with any other flags)
exEnableSel(1), specifies that the control's selection is enabled (multiple-selection, unless the exSingleSel is set )
exSingleSel(2), specifies that the user can select a element only
exToggleSel(4), specifies that the element's selection state is toggled once the user clicks a element.
exDisableCtrlSel(8), disables toggling the element's selection state when user clicks a element, while CTRL modifier key is pressed.
exDisableShiftSel(16), disables selecting elements using the SHIFT key.
exDisableDrag(32), disables selecting elements by drag.

Type: Surface.SingleSelEnum

GetSlinks() → {string}

The GetSlinks() method defines the links between elements of the control from a string-representation. The links are the connections between elements that can be shown as lines or arrows. The Slinks property is optional, because you can always use the Links.Add method to add links individually. However, it is very useful when you want to quickly define the control's links using a string. The Slinks property provides a getter and a setter to handle the control's links as a string: the setter calls Links.Load(), which reads the assigned string and creates the corresponding links in the control, while the getter calls Links.Save(), returning a string that represents all current links in the control. This makes it easy to define, store, or transfer the links using a string representation.

Returns:

A string expression that defines the links between elements of the control from a string-representation.

The format of the string representation is (everything between [] refers to flags):

"link1[flag=value]...[flag=value],...,linkn[flag=value]...[flag=value]"

where the link1, ... linkn defines the caption for each link (can include ex-HTML tags).

The string representation supports the following flags:

[link] {string} (required), indicates the link's in-out elements in "from-to" format, where from/to indicates the element's key, plain-caption or index (0-based). For instance, [link=11-1], links the elements with index 11 and 1, or [link=root-1] links the element with the key "root" or plain-caption "root" with the element of index 1.
[key] {string}, specifies the link's key (Key/GetKey()/SetKey(value) methods of Surface.Link). For instance, [key=L1], specifies that the link's key is "L1"
[vis]/[hid] {number}, shows or hides the link (Visible/GetVisible()/SetVisible(value) methods of Surface.Link). For instance, [hid] or [vis=0], hides the link, while [vis=1] shows the link
[type] {number}, specifies the type of the link as a value of 0 (rectangular), 1 (direct), 2(straight) or 3(round). For instance, [type=3] defines a round-link
[dir] {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides. For instance, [dir=3] shows the arrows in both-directions of the link.
[width] {number}, specifies the link's width or size. For instance, [width=4] shows a wider link.
[color] {string}, indicates the link's color. For instance, [color=red] specifies a red-link.
[arrow] {string}, indicates the arrow's color. For instance, [arrow=#808080] shows the link's arrow in gray.
[style] {number}, specifies the link's dash pattern to show the lines. For instance, [style=2] shows a dotted-link
[startPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of in-element, where the link can start from. For instance, [startPos=TR,MR,BR] specifies that the link can start anywhere on the in-element's right-side
[endPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of out-element, where the link can end into. For instance, [endPos=TL,ML,BL] specifies that the link can end anywhere on the out-element's left-side

The following flags have effect only when the link is shown between collapsed-elements

[coll-type] {number}, specifies the type of the link as a value of 0 (rectangular), 1 (direct), 2(straight) or 3(round). For instance, [coll-type=3] defines a round-link
[coll-dir] {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides. For instance, [coll-dir=3] shows the arrows in both-directions of the link.
[coll-width] {number}, specifies the link's width or size. For instance, [coll-width=4] shows a wider link.
[coll-color] {string}, indicates the link's color. For instance, [coll-color=red] specifies a red-link.
[coll-arrow] {string}, indicates the arrow's color. For instance, [coll-arrow=#808080] shows the link's arrow in gray.
[coll-style] {number}, specifies the link's dash pattern to show the lines. For instance, [coll-style=2] shows a dotted-link
[coll-startPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of in-element, where the link can start from. For instance, [coll-startPos=TR,MR,BR] specifies that the link can start anywhere on the in-element's right-side
[coll-endPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of out-element, where the link can end into. For instance, [coll-endPos=TL,ML,BL] specifies that the link can end anywhere on the out-element's left-side

Type: string

Example

The following statements are equivalents:

 oSurface.GetSlinks() {string}, gets the current links of the control as a string representation
 oSurface.Slinks {string}, gets the current links of the control as a

where oSurface is an instance of Surface control.

GetSlinks

GetSmooth() → {number}

The GetSmooth() method gets the time in ms the control goes from one layout to another. The smooth field is a number that defines the time in ms the control goes from one layout to another. Setting the smooth field to 0 means that no smooth changes are performed once the control goes from a layout to another. Setting the smooth field to 125 means that a smooth-transition is performed from a layout to another for 125 ms. The Smooth() method smoothly transitions the control from the current layout to a new layout, applying gradual changes rather than an immediate switch.

Returns:

Returns the time in ms the control goes from one layout to another.

Type: number

Example

The following statements are equivalent:

 oSurface.GetSmooth() {number}, returns the time in ms the control goes from one layout to another (0 indicates no smooth-transition is performed)
 oSurface.oSV.GetSmooth() {number}, returns the time in ms the control goes from one layout to another (0 indicates no smooth-transition is performed)

where oSurface is an instance of Surface control

GetSmooth

GetTfi() → {string|object}

The GetTfi() method gets the font attributes to apply on captions of the control. The GetTfi() method returns the font attributes as a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}. Correspondingly, the Tfi property defines the font attributes that are applied to the control's captions and can be set to customize their appearance.

Returns:

Returns the font attributes as a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.

The result as a {string} can include any of the following keywords separated by space characters:

bold, displays the text in bold (equivalent of tag)
italic, displays the text in italics (equivalent of tag)
underline, underlines the text (equivalent of tag)
strikeout, specifies whether the text is strike-through (equivalent of <s> tag)
<fontName name>, specifies the font's family (equivalent of tag)
<fontSize size>, specifies the size of the font (equivalent of tag)
<fgColor CSSColor>, specifies the text's foreground color (equivalent of <fgcolor> tag)
<bgColor CSSColor>, specifies the text's background color (equivalent of <bgcolor> tag)
<shaColor CSSColor;width;offset>, defines the text's shadow (equivalent of <sha color;width;offset> tag)
<outColor CSSColor>, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
<graColor CSSColor;mode;blend>, defines a gradient text (equivalent of <gra color;mode;blend> tag)

Any other word within the string result that's not recognized as a keyword is interpreted as:

name of the font (not a number), specifies the font's family (equivalent of tag)
size of the font (number), specifies the size of the font (equivalent of tag)

The result as {object} can include any of the following fields:

bold {boolean}, displays the text in bold (equivalent of tag)
italic {boolean}, displays the text in italics (equivalent of tag)
underline {boolean}, underlines the text (equivalent of tag)
strikeout {boolean}, specifies whether the text is strike-through (equivalent of <s> tag)
fontName {string}, specifies the font's family (equivalent of tag)
fontSize {number}, specifies the size of the font (equivalent of tag)
fgColor {string}, specifies the text's foreground color (CSScolor) (equivalent of <fgcolor> tag)
bgColor {string}, specifies the text's background color (CSScolor) (equivalent of <bgcolor> tag)
shaColor {object}, specifies an object of {color, width, offset} type that defines the text's shadow (equivalent of <sha color;width;offset> tag), where:
- color {string}, defines the color of the text's shadow (CSScolor)
- width {number}, defines the size of the text's shadow
- offset {number}, defines the offset to show the text's shadow relative to the text
outColor {string}, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
graColor {object}, specifies an object of {color, mode, blend} type that defines a gradient text (equivalent of <gra color;mode;blend> tag), where:
- color {string}, defines the gradient-color (CSScolor)
- mode {number}, defines the gradient direction as 0 (left-right), 1 (default, top-bottom), 2 (left-center-right), and 3 (top-center-bottom)
- blend {number}, defines the gradient blend as a value between 0 and 1

CSSColor or CSS legal color values can be specified by the following methods:

Hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF. For example, #0000ff value is rendered as blue, because the blue component is set to its highest value (ff) and the others are set to 00.
Hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF. For example, #0000ff80 defines a semi-transparent blue.
RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255. For example, rgb(0,0,255) defines the blue color.
RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, rgba(0,0,255,0.5) defines a semi-transparent blue.
HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors. For example, hsl(240, 100%, 50%) defines the blue color.
HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, hsla(240, 100%, 50%,0.5) defines a semi-transparent blue.
Predefined/Cross-browser color names, 140 color names are predefined in the HTML and CSS color specification. For example, blue defines the blue color.

Type: string | object

Example

The following statements are equivalent:

  oSurface.GetTfi() {string}, returns the control's font attributes as a string such as "b monospace 16"
  oSurface.Tfi {string}, returns the control's font attributes as a string such as "b monospace 16"

where oSurface is an instance of Surface control

GetTfi

GetWheelChange() → {number}

The GetWheelChange() method defines the amount the calendar scrolls when the user rolls the mouse wheel. This setting allows you to adjust the sensitivity of the mouse wheel interaction with the control.

Setting wheelChange to 0 disables mouse wheel actions, preventing the control from changing when the wheel is scrolled
Setting wheelChange to a positive number, such as 5, increases the control's value by that amount each time the wheel is rotated, enabling faster adjustments

By modifying this value, you can fine-tune the control's responsiveness, making it easier for users to perform precise changes or larger adjustments as needed.

Returns:

Returns the amount the control scrolls when the user rolls the mouse wheel.

Type: number

Example

The following statements are equivalent:

 oSurface.GetWheelChange() {number}, returns the amount the control scrolls when the user rolls the mouse wheel
 oSurface.WheelChange {number}, returns the amount the control scrolls when the user rolls the mouse wheel

where oSurface is an instance of Surface control

GetWheelChange

GetZoom() → {number}

The GetZoom() method defines the zoom factor of the control's content. The zoom factor determines how much the control's content is magnified or reduced. Once the user adjusts the browser's zoom level, the control automatically recalculates its zoom factor to maintain the correct scaling of its content. The ZoomLevels property defines the allowed zoom levels the user can select from. By default, the Zoom property is set to null, indicating a normal view (100% zoom).

Returns:

A numeric value between 10 and 1000 that specifies the zoom factor of the control's content.

Type: number

Example

null {null}, Specifies normal-view (100%)
150 {number}, Indicates that the control's content is magnfied to 150%

GetZoom

GetZoomLevels() → {string}

The GetZoomLevels() method defines the allowed zoom levels for the control and can be specified as a comma-separated string of numeric values (e.g., "50,100,150,200"). These values represent the percentage levels at which users can zoom in or out of the control's content. The ZoomLevels property works together with the Zoom property to provide a range of zoom options. For example, if ZoomLevels is set to "50,100,150,200", users can choose from these predefined zoom levels to adjust their view of the content.

Returns:

Specifies a list of numbers separated by comma that indicates the zoom-levels/zoom-margins the control's content is allowed to zoom.

Type: string

Example

The following statements are equivalent:

 oSurface.GetZoomLevels() {string}, gets the zoom-levels as a string of comma-separated values, for instance "50,100,150,200"
 oSurface.ZoomLevels {string}, gets the zoom-levels as a string of comma-separated values, for instance "50,100,150,200"

where oSurface is an instance of Surface object.

GetZoomLevels

Home()

The Home() method zooms to 100% and scrolls the control to origin (0,0). The Home() method is typically used to reset the view of the control's content to its default state, showing the entire content at its original size and position. This can be useful when users have zoomed in or out or scrolled away from the origin and want to quickly return to the default view. The Soom() method can be used to achieve this by setting the zoom factor to 100% and scrolling to the origin (0,0). The FitToClient() method ensures that the entire (null/undefined) or giving layout fits the control's client area.

Example

oSurface.Home(), zooms to 100% and scrolls the control to origin (0,0)

Home

Paste()

The Paste() method pastes the contents of the Clipboard onto the surface. The Cut/Copy/Paste methods work only if the control is visible. The Paste() method retrieves the clipboard data through the Clipboard API, and then calls the onPaste() method to add the elements and links represented by this data onto the surface. The onPaste() method can be overridden to customize how the clipboard data is processed for derived objects. By default, onPaste() expects an object of {e(lements), l(inks)} type, where e(lements) is a collection of [{ElementOptions}] objects representing the elements to be pasted, and l(inks) is either undefined or a collection of [{LinkOptions}] objects representing the links between those elements. The Paste() method also ensures that the newly pasted elements are visible within the surface's client area by calculating their bounding rectangle and adjusting the view if necessary.

Since:

Example

The following samples demonstrate how to implement the Copy, Cut, and Paste methods for the control using the Clipboard API when the user presses the CTRL + C, CTRL + X (the "See text and images copied to the clipboard /Allow/Block" message may occur due security permissions):

 oSurface.on("{CTRL + C}", oSurface.Copy)
 oSurface.on("{CTRL + X}", oSurface.Cut)
 oSurface.on("{CTRL + V}", oSurface.Paste)

Please note that the control requires focus, so CTRL + C, CTRL + X or CTRL + V to make it works. In the same manner, the tabIndex attribute must be present into the defintion of the canvas HTML element.

Paste

Refresh()

The Refresh() method forces the control to redraw and update its layout without modifying any of its properties or data. It is typically used when the visual appearance needs to be recalculated or repainted, even though no structural or state changes were made.

For example, call Refresh() when:

The control's container has been resized and the layout must be recalculated.
External CSS or styling changes affect the control's appearance.
The control becomes visible after being hidden.
You need to ensure the UI is visually synchronized with its current internal state.

The method does not alter the control's data, options, or configuration - it only updates the rendered output.

Example

oSurface.Refresh(), refreshes the control

Refresh

RemoveSelection()

The RemoveSelection() method deletes the focus-link if exists, otherwise deletes the selected-elements. The focus-link is a visual element that indicates the element currently in focus, which may be different from the selected elements. If the focus-link exists, it will be removed when this method is called. If there are selected elements and no focus-link, those selected elements will be removed instead. The FocusLink property can be used to set or retrieve the focus-link element, and the Selection property can be used to set or retrieve the selected elements. If the selection includes elements with child elements, the RemoveSelection() method will remove the entire hierarchy of those elements. The UnselectAll() method clears the control's selection.

Example

oSurface.RemoveSelection(), deletes the control's selection (focus-link or the selected-elements)

RemoveSelection

SelectAll()

The SelectAll() method selects all elements within the control. Selected elements are highlighted with a specific color to indicate their selection state. The Selection property can be used to set or retrieve the selected elements. It accepts or returns values that identify the elements selected within the control. This property is automatically updated when the Selection property changes or when the user selects or unselects elements in the control. The SingleSel property determines the selection mode of the control. When SingleSel is true, only one element can be selected at a time. When false, multiple elements can be selected simultaneously. The SelectAll() method selects all elements within the control, while the UnselectAll() method clears the control's selection.

Example

oSurface.SelectAll() {void}, selects all elements within the control
oSurface.UnselectAll() {void}, clears the control's selection

SelectAll

SetAlignObjectsToGridLines(value)

The SetAlignObjectsToGridLines() method specifies whether the object(s) are aligned to the minor or major grid lines when they are moved or resized. The MajorGridLines property defines the appearance of the surface's major grid lines as an object of {step, width, color, style, cap} type. The MinorGridLines property defines the appearance of the surface's minor grid lines in the same format. The ShowGridLines property specifies whether the control displays the minor and major grid lines.

Parameters:

Name	Type	Description
`value`	number	Indicates whether the object(s) are aligned to the minor or major grid lines when they are moved or resized. The value can be one of the following: 0 {number}, no alignment is performed -1 {number}, the objects are aligned to minor grid lines 1 {number}, the objects are aligned to major grid lines

Since:

Example

null {null} or 0 {number}, the property has no effect (by default)
-1 {number}, the objects on the surface are aligned to the minor grid lines
1 {number}, the objects on the surface are aligned to the major grid lines

SetAlignObjectsToGridLines

SetAllowActions(value)

The SetAllowActions() method customizes the actions the user can perform once the control is clicked or touched. The order of the actions is very important, as the control checks each action from left to right until it finds a matching action for the performed mouse/touch event. The first matched action is performed, and the rest of the actions are ignored. So if you want to perform a specific action once the user clicks an item, and perform another action if the user clicks an area that does not contain any item, you should place the first action before the second one in the AllowActions property.

Parameters:

Name Type Description

value

string

Indicates the actions the user can perform once the control is clicked or touched.

The format of the property is:

"action(shortcut,shortcut,...),action(shortcut,shortcut,...)..."

where

"action", defines the action to perform (as defined below)

Action	Description	Flags
"create"	Creates an element by drag (not available if the control is read-only)
"drag-drop"	Performs drag and drop of the element (the element can be dropped inside or outside of the control). The ExDrop(event, data) method of the target HTML element is invoked once the user drops the element. The event parameter contains information about the mouse/touch event. The data parameter contains information about the source-object that initiated the drag/drop operation as {object, source, client, shape}
"fit"	Fits the drag-area into the control's client area
"link"	Links elements by drag (not available if the control is read-only)	[toggle], the link is removed if the linked-elements has already a link between
"link-cp"	Allows customization of the link's path by drag (not available if the control is read-only). This action is effective only if allowLinkControlPoint field is not zero
"move"	Moves or resizes elements by drag (not available if the control is read-only). The allowChangeParent field specifies whether the element's position or parent can be changed at runtime by drag and drop
"scroll"	Scrolls the control's content by drag
"select"	Selects elements by drag
"zoom"	Zooms the control's content at dragging-point

The exswimlane/js control supports additional actions as listed in the table below:

Action	Description	Flags
"create"	Creates an element or a pool by drag (For instance "create[pool](Ctrl+Alt)" creates a pool if Ctrl + Alt is pressed, while "create[element](Alt)" creates an element while the Alt key is pressed, not available if the control is read-only)	[pool], specifies that a pool is created [element], specifies that an element is created
"move"	Moves or resizes elements by drag (For instance, "move[element]" indicates that only elements are allowed to be moved or resized, not available if the control is read-only). If flag is missing, the user can move or resize elements or pools	[pool], specifies that just pools are movable/resizable [element], specifies that just elements are movable/resizable
"resize-header"	Resizes the pool's header (For instance, "resize-header[left,top]" specifies that just the left and top-header of the pool are resizable, not available if the control is read-only). If no flag is present, all pool's headers are resizable	[left], indicates that the left-header of the pool is resizable [right], indicates that the right-header of the pool is resizable [top], indicates that the top-header of the pool is resizable [bottom], indicates that the bottom-header of the pool is resizable
"resize-lane"	Resizes the pool's lane (the lanes are vertically arranged)
"resize-phase"	Resizes the pool's phase (the phases are horizontally arranged)

"shortcut", defines the event's button or/and the modifier-keys that are required to perform the action. The "shortcut" can include one or more of the following: "Shift", "Ctrl", "Alt", "Meta", "LButton", "RButton", "MButton" and "+"

Example

null {null}, indicates the control's default allowActions value
"" {string}, specifies that no operation is allowed once the user clicks or touches the control
"scroll" {string}, specifies that only "scroll" operation is allowed, no matter of the event's button or modifier-keys is pressed.
"create(Alt+LButton),move,scroll" {string}, indicates that creating-elements is possible only if the user presses the mouse's left-button while ALT key is pressed, and "move" or "scroll" is possible no matter of the event's button or modifier-keys in this order. Also, if no "create"-operation is possible, do "move"-operation, if no "move"-operation is possible, do "scroll"-operation

SetAllowActions

SetAllowChangeParent(value)

The SetAllowChangeParent() method specifies whether an element's position or parent can be changed at runtime using drag and drop. When set to true, users can rearrange elements by dragging them to different positions or parents. When set to false, drag and drop cannot change the element's position or parent. This property is useful for maintaining a fixed structure or hierarchy within the control. AllowChangeParent is effective only if the "move" action is included in the AllowActions property and the control is not read-only. The Element.Parent property indicates the parent of an element, while Element.Position indicates the element's position within its parent's children collection.

Parameters:

Name	Type	Description
`value`	boolean	Indicates whether the element's position or parent can be changed at runtime by drag and drop.

Example

null {null}, allows element's parent or position to be changed at runtime by drag and drop.
false {boolean}, prevents changing the element's position or parent at runtime by drag and drop.

SetAllowChangeParent

SetAllowLinkControlPoint(value)

The SetAllowLinkControlPoint() method sets the control points of links that users can use to customize the link's path. This property applies to all links unless a different value is specified by the Link.AllowControlPoint property. Users can drag and drop control points to change the link's path or remove them by dragging one control point onto another. The ShowLinks property must be different from 0 to display the link's control points. AllowLinkControlPoint is effective only if the "link-cp" action is included in the AllowActions property and the control is not read-only. For instance, exStartControlPoint | exEndControlPoint specifies that the user can change only the start/end position of the link.

Parameters:

Name Type Description

Name	Type	Description
`value`	Surface.LinkControlPointEnum	Specifies the control points of the link, the user can use to customize the link's path. The Surface.LinkControlPointEnum type defines the following flags: exNoControlPoint(0), the link displays no control points exStartControlPoint(1), the link shows control point that changes the link's startPos field (the exStartControlPoint point is marked with black squares) exEndControlPoint(2), the link shows control point that changes the link's endPos field (the exEndControlPoint point is marked with black squares) exControlPoint(4), defines the corners of the link's path. You can remove a exControlPoint points by dragging to another, so intermediate exControlPoint points are removed. You can move all control points of the link at once, if SHIFT key is pressed (the exControlPoint points are marked black circles) exMiddleControlPoint(8), defines the link's middle control points that are displayed between two exControlPoint points, to let the use add new exControlPoint points, to redefine the link's path (The exMiddleControlPoint points are marked with gray circles) exOrthoArrange(0x10), specifies that the lines of the link are orthogonal arranged when the user drags and drops the middle or control-points of the path (excludes the start/end control-points) exAllowChangeFrom(0x20), allows the user to adjust the link's from element by dragging and dropping the start control point (requires the exStartControlPoint flag) exAllowChangeTo(0x40), indicates that the user can adjust the link's to element by dragging and dropping the end control point (requires the exEndControlPoint flag)

value

Surface.LinkControlPointEnum

Specifies the control points of the link, the user can use to customize the link's path.

The Surface.LinkControlPointEnum type defines the following flags:

exNoControlPoint(0), the link displays no control points
exStartControlPoint(1), the link shows control point that changes the link's startPos field (the exStartControlPoint point is marked with black squares)
exEndControlPoint(2), the link shows control point that changes the link's endPos field (the exEndControlPoint point is marked with black squares)
exControlPoint(4), defines the corners of the link's path. You can remove a exControlPoint points by dragging to another, so intermediate exControlPoint points are removed. You can move all control points of the link at once, if SHIFT key is pressed (the exControlPoint points are marked black circles)
exMiddleControlPoint(8), defines the link's middle control points that are displayed between two exControlPoint points, to let the use add new exControlPoint points, to redefine the link's path (The exMiddleControlPoint points are marked with gray circles)
exOrthoArrange(0x10), specifies that the lines of the link are orthogonal arranged when the user drags and drops the middle or control-points of the path (excludes the start/end control-points)
exAllowChangeFrom(0x20), allows the user to adjust the link's from element by dragging and dropping the start control point (requires the exStartControlPoint flag)
exAllowChangeTo(0x40), indicates that the user can adjust the link's to element by dragging and dropping the end control point (requires the exEndControlPoint flag)

Example

0 or Surface.LinkControlPointEnum.exNoControlPoint {number}, displays no link's control points (unless the link's allowControlPoint property is different)
3 or Surface.LinkControlPointEnum.exStartControlPoint | Surface.LinkControlPointEnum.exEndControlPoint {number}, displays link's start and end control points only, for all links (unless the link's allowControlPoint property is different)

SetAllowLinkControlPoint

SetAxes(value)

The SetAxes() method specifies the appearance used to draw the surface axes, as an object of {width, color, style, cap} type. The axes are typically represented by two perpendicular lines that intersect at the origin (0,0) of the surface. The ShowAxes property determines whether the control displays the horizontal and vertical axes. The Axes property allows you to customize their appearance, including width, color, line style, and other visual attributes.

Parameters:

Name Type Description

value

object

Specifies the appearance to draw the axes of the surface, as an object of {width, color, style, cap} type.

Properties

Name	Type	Description
`width`	number	specifies the line's width or size (1 by default) (if 0 no axes are shown). For instance: null {null}, indicates line of 1-pixel wide (default value) 0 {number}, indicates that no axes are shown 2 {number}, indicates line of 2-pixels wide
`color`	any	indicates the line's color ("#E8E8E8" by default). For instance: null {null}, indicates a light gray line (default value) "transparent" {string}, specifies a transparent line "red" {string}, specifies a red line "#00FF00" {string}, specifies a green line "rgba(255,0,0,0.5)" {string}, indicates 50% red line
`style`	any	defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance: null {null} or [] {array}, defines solid grid-lines (default style) 2 {number}, becomes [2, 2, ...] [5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
`cap`	string	determines the shape used to draw the end points of lines ("but" by default). Determines the shape used to draw the end points of lines, as one of the following: "butt" {string}, the ends of lines are squared off at the endpoints. "round" {string}, the ends of lines are rounded "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness For instance: null {null}, "butt" ends (default value) "round" {string}, the ends of lines are rounded

Since:

Example

null {null}, the control's axes is black, 1-pixel wide and solid
{color: "gray", width: 2} {object}, the control's axes is gray, solid and 2-pixel wide

SetAxes

SetCollapsedLink(value)

The SetCollapsedLink() method sets the appearance of links between collapsed elements. It allows customization of line style, color, thickness, and other visual attributes to differentiate these links from those between expanded elements. The ShowLinksOnCollapse property controls whether links between collapsed elements are visible. The Element.Expand property indicates whether an element is expanded or collapsed, and the CollapsedLink settings apply to links connecting elements that are collapsed.

Parameters:

Name Type Description

Name	Type	Description
`value`	DisplayLinkType	Specifies the appearance of the link between collapsed elements. The ShowLinksOnCollapse property controls whether links between collapsed elements are visible. The Element.Expand property indicates whether an element is expanded or collapsed, and the CollapsedLink settings apply to links connecting elements that are collapsed. The link object includes any of the following: type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round) dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides width {number}, specifies the link's width or size (1 by default) color {string}, indicates the link's color (partial-black by default) arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default) arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2) arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2) style {array}, specifies the link's dash pattern to show the lines (solid by default) startPos {any}, indicates the in-element's corners, the link can start from endPos {any}, indicates the out-element's corners , the link ends into

value

DisplayLinkType

Specifies the appearance of the link between collapsed elements. The ShowLinksOnCollapse property controls whether links between collapsed elements are visible. The Element.Expand property indicates whether an element is expanded or collapsed, and the CollapsedLink settings apply to links connecting elements that are collapsed.

The link object includes any of the following:

type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round)
dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides
width {number}, specifies the link's width or size (1 by default)
color {string}, indicates the link's color (partial-black by default)
arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default)
arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2)
arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2)
style {array}, specifies the link's dash pattern to show the lines (solid by default)
startPos {any}, indicates the in-element's corners, the link can start from
endPos {any}, indicates the out-element's corners , the link ends into

Example

{type: 0, color: "blue"} {object}, sets the link between collapsed elements as a blue rectangular line with width of 1
{type: 1, color: "red", width: 2} {object}, sets the link between collapsed elements as a red direct line with width of 2

SetCollapsedLink

SetCoord(value)

The SetCoord() method sets the coordinate system used to display the elements of the surface. It can be set to different values to control how element coordinates are interpreted and displayed. This allows you to choose between coordinate systems such as Cartesian or default coordinates, and to specify whether only positive coordinates should be used.

Parameters:

Name Type Description

Name	Type	Description
`value`	Surface.CoordEnum	Specifies the type of coordinates the elements of the surface display in. The Surface.CoordEnum type defines the following flags: exDefCoord(0), the positive coordinates are shown right-down to origin of the surface. exCartesian(1), the elements show in Cartesian coordinates. The positive coordinates are shown right-up to origin of the surface. exAllowPositiveOnly(0x10), only the positive panel of the surface is shown. The exAllowPositiveOnly flag can be combined with exDefCoord or exCartesian value. For instance, the exCartesian + exAllowPositiveOnly indicates that surface displays only the positive coordinates in Cartesian system.

value

Surface.CoordEnum

Specifies the type of coordinates the elements of the surface display in.

The Surface.CoordEnum type defines the following flags:

exDefCoord(0), the positive coordinates are shown right-down to origin of the surface.
exCartesian(1), the elements show in Cartesian coordinates. The positive coordinates are shown right-up to origin of the surface.
exAllowPositiveOnly(0x10), only the positive panel of the surface is shown. The exAllowPositiveOnly flag can be combined with exDefCoord or exCartesian value. For instance, the exCartesian + exAllowPositiveOnly indicates that surface displays only the positive coordinates in Cartesian system.

Example

0 or Surface.CoordEnum.exDefCoord {number}, displays elements as the positive coordinates are shown right-down to origin of the surface.
17 or Surface.CoordEnum.exCartesian | Surface.CoordEnum.exAllowPositiveOnly {number}, indicates that surface displays only the positive coordinates in Cartesian system

SetCoord

SetCursors(value)

The SetCursors() method specifies the mouse cursor to be displayed when pointing over a part of the control. Parts that can be customized include element, expand, and others, each corresponding to a different UI component - for example, element affects the cursor when hovering over any element, while expand defines the cursor when hovering over expand/collapse glyphs. The Cursors property allows you to assign different mouse cursors to control parts, enhancing the user experience by providing visual feedback on interactive areas. For instance, the string "pointer(element),crosshair(expand)" applies a pointer cursor to the element part and a crosshair cursor to the expand part of the control.

Parameters:

Name Type Description

value

string

A string expression that defines the mouse cursor to display when pointing over different parts of the control.

The format of the property is:

"cursor(part),cursor(part),..."

where:

"cursor", defines the CSS mouse cursor to display while cursor hovers the part
"part", defines the name of the part the cursor is applied on (as defined bellow)

The "cursor" can be any of the following:

Cursor Description

"alias" indicates a shortcut or alias will be created

"all-scroll" indicates scrolling in any direction

"auto" lets the browser decide the cursor based on context

"cell" indicates a table cell

"col-resize" indicates a column can be resized horizontally

"context-menu" indicates a context menu is available

"copy" indicates something will be copied

"crosshair" a precise crosshair cursor

"default" the default arrow cursor

"e-resize" resize east (right edge)

"ew-resize" resize horizontally

"grab" indicates an item can be grabbed

"grabbing" indicates an item is being grabbed

"help" indicates help information is available

"move" indicates something can be moved

"n-resize" resize north (top edge)

"ne-resize" resize northeast (top-right corner)

"nesw-resize" resize along the northeast–southwest axis

"no-drop" indicates dropping is not permitted

"not-allowed" indicates the action is not allowed

"ns-resize" resize vertically

"nw-resize" resize northwest (top-left corner)

"nwse-resize" resize along the northwest–southeast axis

"pointer" the pointer cursor (a hand with a pointing finger)

"progress" indicates background processing

"row-resize" indicates a row can be resized vertically

"s-resize" resize south (bottom edge)

"se-resize" resize southeast (bottom-right corner)

"sw-resize" resize southwest (bottom-left corner)

"text" the text selection cursor (I-beam)

"url(...)" uses a custom cursor image (with optional fallback)

"vertical-text" the vertical text selection cursor

"w-resize" resize west (left edge)

"wait" indicates the program is busy

"zoom-in" indicates zooming in

"zoom-out" indicates zooming out

The "part" can be any of the following:

Cursor Description

"anchor" (hyperlink) defines the mouse-cursor when the mouse pointer hovers the anchor (the <a> ex-HTML part marks an anchor or hyperlink element) (@since 2.2)

"drag-drop" defines the cursor while the node is being dragged using the "drag-drop" action

"element" defines the mouse-cursor when the mouse pointer hovers any element. The cursor field defines the element's indiviual cursor.

"expand" (expand/collapse) defines the mouse-cursor when the mouse pointer hovers the element's expand/collapse glyphs

"link-cp" (link-control-point) defines the mouse-cursor when the mouse pointer hovers any link's control point

"link-cp-all" (link-control-point-all) defines the mouse-cursor when the mouse pointer hovers any link's control point (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

"link-cp-h" (link-control-point-horizontal) defines the mouse-cursor when the mouse pointer hovers a horizontal line (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

"link-cp-v" (link-control-point-vertical) defines the mouse-cursor when the mouse pointer hovers a vertical line (while the link is orthogonally arranged by drag and drop ~ exOrthoArrange)

The exswimlane/js control supports additional parts as listed in the table below:

Cursor Description

"pool" (pool) defines the mouse-cursor when the mouse pointer hovers any pool

Example

"pointer(xxx,yy)" {string}, indicates that the "pointer" mouse cursor is shown while cursor hovers any "xxx" or "yyy" part of the control

SetCursors

SetExpandGlyphSize(value)

The SetExpandGlyphSize() method sets the size of the element's expand/collapse glyphs. These glyphs indicate whether an element can be expanded to show its children or collapsed to hide them. ExpandGlyphSize controls the dimensions of these glyphs, allowing you to adjust their visibility based on your design preferences. Setting this property to 0 hides the expand/collapse glyphs, while a positive value (for example 24) displays them at the specified size (such as 24x24 pixels). The Element.Expand property indicates whether an element is expanded or collapsed, and the "expand" part of the Shapes property defines the appearance of the expand/collapse glyphs.

Parameters:

Name	Type	Description
`value`	number	A value that specifies the size to show the element's expand/collapse glyphs.

Example

0 {number}, displays no element's expand/collapse glyphs
24 {number}, specifies a size of 24x24 to display the element's expand/collapse glyphs

SetExpandGlyphSize

SetFocusLink(value)

The SetFocusLink method sets the focused link, whose path the user can modify by dragging its control points when the AllowLinkControlPoint property enables them. The FocusLink property can be set to specify the focused link on the surface or read to retrieve the currently focused link. The "link-bs", "link-be", "link-m", and "link-p" parts of the Shapes property define the appearance of the link's control points (beginning, end, middle, and path control points, respectively). The onfocuslink event notifies your application when the user focuses on a new link.

Parameters:

Name	Type	Description
`value`	number \| string \| Link	Indicates the new focus link as one of the following: value {number}, indicates a numeric value that defines the index of the link focus value {string}, specifies a string expression that defines the identifier/key/plain-caption of the link focus value {Link}, specifies the object reference to the link to focus

Since:

Example

null {null}, removes or unfocuses the focused link (do not confuse this with removing the link entirely)
0 {number}, focuses the first link of the surface

SetFocusLink

SetFormatText(value)

The SetFormatText() method sets the format used to display labels or captions on the control. It is a bitwise combination of flags that control text alignment, word-breaking, tab expansion, and other rendering options. For example, you can align text to the center, enable word-breaking for long captions, or display text on a single line. The available flags are defined in the exontrol.DrawTextFormatEnum type and can be combined to achieve the desired text formatting.

Parameters:

Name Type Description

Name	Type	Description
`value`	exontrol.DrawTextFormatEnum	Specifies a value of exontrol.DrawTextFormatEnum value that defines the format to show the element's caption. The exontrol.DrawTextFormatEnum type support the following flags: exTextAlignTop (0x00), justifies the text to the top of the rectangle exTextAlignLeft (0x00), aligns text to the left exTextAlignCenter (0x01), centers text horizontally in the rectangle exTextAlignRight (0x02), aligns text to the right exTextAlignVCenter (0x04), centers text vertically exTextAlignBottom (0x08), justifies the text to the bottom of the rectangle. exTextAlignMask (0x0F), specifies the mask for text's alignment. exTextWordBreak (0x10), breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line. If this is not specified, output is on one line. exTextSingleLine (0x20), displays text on a single line only. Carriage returns and line feeds do not break the line. exTextExpandTabs (0x40), expands tab characters. The default number of characters per tab is eight. exPlainText (0x80), treats the text as plain text. exTextNoClip (0x0100), draws without clipping. exHTMLTextNoColors (0x0200), ignores the and tags. exTextCalcRect (0x0400), determines the width and height of the text. exHTMLTextNoTags (0x0800), ignores all HTML tags. exTextPathEllipsis (0x4000), for displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, exTextPathEllipsis preserves as much as possible of the text after the last backslash. exTextEndEllipsis (0x8000), for displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses. exTextWordEllipsis (0x040000), truncates any word that does not fit in the rectangle and adds ellipses.

value

exontrol.DrawTextFormatEnum

Specifies a value of exontrol.DrawTextFormatEnum value that defines the format to show the element's caption.

The exontrol.DrawTextFormatEnum type support the following flags:

exTextAlignTop (0x00), justifies the text to the top of the rectangle
exTextAlignLeft (0x00), aligns text to the left
exTextAlignCenter (0x01), centers text horizontally in the rectangle
exTextAlignRight (0x02), aligns text to the right
exTextAlignVCenter (0x04), centers text vertically
exTextAlignBottom (0x08), justifies the text to the bottom of the rectangle.
exTextAlignMask (0x0F), specifies the mask for text's alignment.
exTextWordBreak (0x10), breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-line feed sequence also breaks the line. If this is not specified, output is on one line.
exTextSingleLine (0x20), displays text on a single line only. Carriage returns and line feeds do not break the line.
exTextExpandTabs (0x40), expands tab characters. The default number of characters per tab is eight.
exPlainText (0x80), treats the text as plain text.
exTextNoClip (0x0100), draws without clipping.
exHTMLTextNoColors (0x0200), ignores the and tags.
exTextCalcRect (0x0400), determines the width and height of the text.
exHTMLTextNoTags (0x0800), ignores all HTML tags.
exTextPathEllipsis (0x4000), for displayed text, replaces characters in the middle of the string with ellipses so that the result fits in the specified rectangle. If the string contains backslash (\) characters, exTextPathEllipsis preserves as much as possible of the text after the last backslash.
exTextEndEllipsis (0x8000), for displayed text, if the end of a string does not fit in the rectangle, it is truncated and ellipses are added. If a word that is not at the end of the string goes beyond the limits of the rectangle, it is truncated without ellipses.
exTextWordEllipsis (0x040000), truncates any word that does not fit in the rectangle and adds ellipses.

Example

null {null}, centers the caption
32 or exontrol.DrawTextFormatEnum.exTextSingleLine {number}, defines a single-line caption
0x2A or exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom {number}, defines a single-line caption right/bottom-aligned

SetFormatText

SetImageAlign(value)

The SetImageAlign() method sets the alignment of the image within the element, while the ImageSize property defines its dimensions. Together, they control how the image is displayed within the element, with ImageSize specifying the image's size and ImageAlign determining its position relative to the caption.

Parameters:

Name	Type	Description
`value`	number	Defines the format to show the element's caption as one of the following: 0, the image is on the left of the element's caption 1, the image is on the right of the element's caption 2, the image is on the top of the element's caption 3, the image is on the bottom of the element's caption

Example

null {null}, the image is on top of the element's cation (default value)
1 {number}, the image is displayed to the right of the element's caption

SetImageAlign

SetImageSize(value)

The SetImageSize() method sets the size of the element's image, and the ImageAlign property defines its alignment within the element. Together, they control how the image is displayed relative to the caption. ImageSize sets the image dimensions, while ImageAlign determines its position in relation to the caption. For captions or labels that support ex-HTML formatting, images can be included using the ex-HTML tag; however, ImageSize does not affect these images. The tag supports a size attribute to specify the image's dimensions, for example: apple:182002 sets the image named "apple" to size 18.

Parameters:

Name	Type	Description
`value`	any	Indicates the size of the element's image as explained: {null}, indicates that the element's image is displayed as it is (full-sized). {number}, specifies that the element's image is displayed into a square of giving size (same width and height). If 0 the element displays no image, if negative the element's image is stretched to giving square, else the element's picture is scaled to fit the giving rectangle. {array}, specifies an array of [aspect-width,aspect-height] type that defines the limits for width or/and height. The aspect-width and aspect-height define the width/height of the element's picture to scale or stretch to.

Example

null {null}, indicates that the element's image is displayed as it is (full-sized).
0 {number}, no image is displayed
64 {number}, the image is scaled to fit a 64 x 64 rectangle
-64 {number}, the image is strected to a 64 x 64 rectangle
[32,64] {array}, scales the image to the largest ratio-rectangle (32 x 64) that fits the client
[-32,-64] {array}, stretches the image to a 32 x 64 rectangle

SetImageSize

SetLink(value)

The SetLink() method sets the default appearance of links between elements, including settings such as line style, color, thickness, and other visual attributes. The ShowLinks property determines whether links are displayed in the control. You can further customize link appearance based on their relationship to selected elements:

LinkStartFrom property, defines the appearance of links starting from a selected element (outgoing links)
LinkEndTo property, defines the appearance of links ending at a selected element (incoming links)
LinkUnselected property, defines the appearance of links not related to any selected element (unselected links)

Parameters:

Name	Type	Description
`value`	DisplayLinkType	Specifies the appearance of the link between elements. The link object includes any of the following: type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round) dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides width {number}, specifies the link's width or size (1 by default) color {string}, indicates the link's color (partial-black by default) arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default) arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2) arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2) style {array}, specifies the link's dash pattern to show the lines (solid by default) startPos {any}, indicates the in-element's corners, the link can start from endPos {any}, indicates the out-element's corners , the link ends into

Example

null {null}, sets the default appearance of links between elements
{type: 1, color: "red", width: 2} {object}, sets the default appearance of links between elements as direct red lines with width of 2

SetLink

SetLinkEndTo(value)

The SetLinkEndTo() method sets the appearance of links that end at selected elements (incoming links). It allows customization of line style, color, thickness, and other visual attributes to distinguish incoming links from other connections. The SV.SetLink method defines the default appearance of links between elements, and the ShowLinks property controls whether links are displayed in the control.

Parameters:

Name	Type	Description
`value`	DisplayLinkType	Specifies the appearance of the link that ends to any selected-element (incoming links). It can include any of the following: type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round) dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides width {number}, specifies the link's width or size (1 by default) color {string}, indicates the link's color (partial-black by default) arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default) arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2) arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2) style {array}, specifies the link's dash pattern to show the lines (solid by default) startPos {any}, indicates the in-element's corners, the link can start from endPos {any}, indicates the out-element's corners , the link ends into

Example

null {null}, sets the appearance of the link that ends to any selected-element (incoming links)
{type: 1, color: "red", width: 2} {object}, sets the appearance of the link that ends to any selected-element (incoming links) as direct red lines with width of 2

SetLinkEndTo

SetLinkStartFrom(value)

The SetLinkStartFrom() method sets the appearance of links that start from selected elements (outgoing links). It allows customization of line style, color, thickness, and other visual attributes to distinguish outgoing links from other connections. The SV.SetLink method defines the default appearance of links between elements, and the ShowLinks property determines whether links are displayed in the control.

Parameters:

Name	Type	Description
`value`	DisplayLinkType	Specifies the appearance of the link that starts from any selected-element (outgoing links). It can include any of the following: type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round) dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides width {number}, specifies the link's width or size (1 by default) color {string}, indicates the link's color (partial-black by default) arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default) arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2) arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2) style {array}, specifies the link's dash pattern to show the lines (solid by default) startPos {any}, indicates the in-element's corners, the link can start from endPos {any}, indicates the out-element's corners , the link ends into

Example

null {null}, sets the appearance of the link that starts from any selected-element (outgoing links)
{type: 1, color: "red", width: 2} {object}, sets the appearance of the link that starts from any selected-element (outgoing links) as direct red lines with width of 2

SetLinkStartFrom

SetLinkUnselected(value)

The SetLinkUnselected() method sets the appearance of links that are not connected to any selected elements (unselected links). It allows customization of line style, color, thickness, and other visual attributes to visually distinguish unselected links from those related to selected elements. The SV.SetLink method defines the default appearance of links between elements, and the ShowLinks property controls whether links are displayed in the control.

Parameters:

Name	Type	Description
`value`	DisplayLinkType	Specifies the appearance of the link not related to any selected-element (unselected links). It can include any of the following: type {exontrol.LinkTypeEnum}, specifies the type of the link 0 (rectangular), 1 (direct), 2(straight) or 3(round) dir {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides width {number}, specifies the link's width or size (1 by default) color {string}, indicates the link's color (partial-black by default) arrow {string}, indicates the arrow's color. If it is missing or not specified the arrow is shown using the link's color (gray by default) arrowSize {number}, indicates the arrow's size. If it is missing or not specified the arrow's size is defined by link's width (1 by default) (@since 2.2) arrowShape {object}, defines an object of exontrol.Def.Shape type to customize the shape of the link's arrow (for instance shows the link's arrow as a circle instead of a triangle) (@since 2.2) style {array}, specifies the link's dash pattern to show the lines (solid by default) startPos {any}, indicates the in-element's corners, the link can start from endPos {any}, indicates the out-element's corners , the link ends into

Example

null {null}, sets the appearance of the link not related to any selected-element (unselected links)
{type: 1, color: "red", width: 2} {object}, sets the appearance of the link not related to any selected-element (unselected links) as direct red lines with width of 2

SetLinkUnselected

SetLocked(value)

The SetLocked() method locks or unlocks the control. The locked state of the control determines whether users can interact with it. When the control is locked, users cannot scroll, select, or interact with any element within the control. When the control is unlocked, it behaves normally, allowing users to scroll, select, and interact with its elements. In contrast, when the control is read-only, users cannot create, resize, or move elements, but they can still scroll, select, and interact with existing elements. Therefore, Locked mode completely prevents user interaction with the control, while read-only mode only prevents modifications to the elements.

Parameters:

Name	Type	Description
`value`	boolean	A boolean value that indicates whether the control is locked(protected) or unlocked.

Example

false {boolean}, the user can create, resize or move any element
true {boolean}, the user can not create, resize or move any element.

SetLocked

SetMajorGridLines(value)

The SetMajorGridLines() method sets the appearance of major grid-lines, as an object of {step, width, color, style, cap} type. The MinorGridLines property defines the appearance of the surface's minor grid lines in the same format. The ShowGridLines property specifies whether the control displays both minor and major grid lines. When ShowGridLines is true, the grid lines are displayed according to the specifications in MinorGridLines and MajorGridLines. When false, the grid lines are hidden regardless of their specified appearance. The AlignObjectsToGridLines property specifies whether objects are aligned to minor or major grid lines when they are moved or resized.

Parameters:

Name Type Description

value

object

Specifies the appearance of major grid-lines, as an object of {step, width, color, style, cap} type.

Properties

Name	Type	Description
`step`	number	specifies the distance between two consecutive major grid-lines (100 by default) (if 0 the major grid-lines are ignored). For instance: null {null}, the distance between two consecutive major grid-lines is 10 (default value) 0 {number}, the major grid-lines are ignored 5 {number}, show the major grid-lines from 5 to 5
`width`	number	specifies the line's width or size (1 by default) (if 0 no major grid-lines are shown). For instance: null {null}, indicates line of 1-pixel wide (default value) 0 {number}, indicates that no major grid-lines are shown 2 {number}, indicates line of 2-pixels wide
`color`	any	indicates the line's color ("#E8E8E8" by default). For instance: null {null}, indicates a light gray line (default value) "transparent" {string}, specifies a transparent line "red" {string}, specifies a red line "#00FF00" {string}, specifies a green line "rgba(255,0,0,0.5)" {string}, indicates 50% red line
`style`	any	defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance: null {null} or [] {array}, defines solid grid-lines (default style) 2 {number}, becomes [2, 2, ...] [5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
`cap`	string	determines the shape used to draw the end points of lines ("but" by default). Determines the shape used to draw the end points of lines, as one of the following: "butt" {string}, the ends of lines are squared off at the endpoints. "round" {string}, the ends of lines are rounded "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness For instance: null {null}, "butt" ends (default value) "round" {string}, the ends of lines are rounded

Since:

Example

null {null}, the major grid-lines are shown from 100 to 100
{step: 0} {object}, the major grid-lines are ignored
{color: "gray"} {object}, the major grid-lines are shown in gray

SetMajorGridLines

SetMargins(value)

The SetMargins() method sets the control's margins and spacing. The value is an object of the form {x, y, indent, border}, where x is the horizontal distance between elements, y is the vertical distance, indent is the indentation for nested elements, and border is the distance from the control's edges. You can use the Margins property to adjust spacing around and between elements, improving the visual layout and organization. By default, Margins is {border: 16, x: 2, y: 2, indent: 16}, meaning the control has a 16-pixel border, 2-pixel horizontal and vertical spacing, and a 16-pixel indent. Chaning an attribute of the margins object (such as x, y, indent, or border) does not update the control's layout until you call the SetMargins() method to apply the changes.

Parameters:

Name	Type	Description
`value`	object	Indicates an object of {x,y,indent,border} type that specifies control's margins.

Example

null {null}, uses the default margins of {border: 16, x: 2, y: 2, indent: 16}
{border: 0, x: 0, y: 0, indent: 0} {object}, specifies no margins, so elements are drawn at the very edge of the control and without indent

SetMargins

SetMinorGridLines(value)

The SetMinorGridLines() method sets the appearance of the surface's minor grid lines as an object of {step, width, color, style, cap} type. The MajorGridLines property defines the appearance of the surface's major grid lines in the same format. The ShowGridLines property specifies whether the control displays both minor and major grid lines. When ShowGridLines is true, the grid lines are displayed according to the specifications in MinorGridLines and MajorGridLines. When false, the grid lines are hidden regardless of their specified appearance. The AlignObjectsToGridLines property specifies whether objects are aligned to minor or major grid lines when they are moved or resized.

Parameters:

Name Type Description

value

object

Specifies the appearance of minor grid-lines, as an object of {step, width, color, style, cap} type.

Properties

Name	Type	Description
`step`	number	specifies the distance between two consecutive minor grid-lines (10 by default) (if 0 the minor grid-lines are ignored). For instance: null {null}, the distance between two consecutive minor grid-lines is 10 (default value) 0 {number}, the minor grid-lines are ignored 5 {number}, show the minor grid-lines from 5 to 5
`width`	number	specifies the line's width or size (1 by default) (if 0 no minor grid-lines are shown). For instance: null {null}, indicates line of 1-pixel wide (default value) 0 {number}, indicates that no minor grid-lines are shown 2 {number}, indicates line of 2-pixels wide
`color`	any	indicates the line's color ("#F8F8F8" by default). For instance: null {null}, indicates a light gray line (default value) "transparent" {string}, specifies a transparent line "red" {string}, specifies a red line "#00FF00" {string}, specifies a green line "rgba(255,0,0,0.5)" {string}, indicates 50% red line
`style`	any	defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance: null {null} or [] {array}, defines solid grid-lines (default style) 2 {number}, becomes [2, 2, ...] [5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
`cap`	string	determines the shape used to draw the end points of lines ("but" by default). Determines the shape used to draw the end points of lines, as one of the following: "butt" {string}, the ends of lines are squared off at the endpoints. "round" {string}, the ends of lines are rounded "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness For instance: null {null}, "butt" ends (default value) "round" {string}, the ends of lines are rounded

Since:

Example

null {null}, the minor grid-lines are shown from 10 to 10
{step: 0} {object}, the minor grid-lines are ignored
{color: "gray"} {object}, the minor grid-lines are shown in gray

SetMinorGridLines

SetOptions(nOptions, bIncludeAllopt) → {boolean}

The SetOptions() method applies the giving options to the control. The options include different fields to specify the control's appearance such as showLinks, shapes, cursors, and so on. The options are stored in an object of Surface.Options type.

Every option of the Surface.Options type has associated a property of the link. For instance, the option:

showLinks, defines whether to show the links between elements

is associated with the property:

ShowLinks {string}, defines whether to show the links between elements

which means that the following statements are equivalent:

oSurface.Options = {showLinks: "show"}
oSurface.SetOptions({showLinks: "show"})
oSurface.ShowLinks = "show"
oSurface.SetShowLinks("show")

where oSurface is a reference to the Surface control.

It is important to note that changing a field of the Options object does not automatically update the control. For example, oSurface.Options.showLinks = "show" does not apply the change. Instead, you must assign the Options property again, such as oSurface.SetOptions({showLinks: "show"}), so the control updates and applies the new value.

Parameters:

Name	Type	Attributes	Description
`nOptions`	Surface.Options		Specifies an object of Surface.Options type that indicates the new options to apply.
`bIncludeAll`	boolean	<optional>	Indicates whether all fields of nOptions are included in the element's oOpts object.

Returns:

Returns true, if there were options applied to the element

Type: boolean

SetOrigin(value)

The SetOrigin() method specifies the appearance of the surface origin as an object of {size, width, color, style, cap} type. The origin represents the point (0,0) on the surface and is typically displayed as a cross. The ShowOrigin property determines whether the origin is visible. The Origin property allows you to customize the origin's appearance, including its size, color, line style, and other visual attributes.

Parameters:

Name Type Description

value

object

Specifies the appearance to draw the origin of the surface, as an object of {size, width, color, style, cap} type.

Properties

Name	Type	Description
`size`	number	indicates the size of the origin (the size of the cross) (8 by default). For instance: null {null}, defines an 8-pixels wide cross (default size) 16 {number}, defines a 16-pixels wide cross
`width`	number	specifies the line's width or size (1 by default) (if 0 no surface's origin is shown). For instance: null {null}, indicates line of 1-pixel wide (default width) 0 {number}, indicates that no surface's origin is shown 2 {number}, indicates line of 2-pixels wide
`color`	any	indicates the line's color (black by default). For instance: null {null}, indicates a black line (default color) "transparent" {string}, specifies a transparent line "red" {string}, specifies a red line "#00FF00" {string}, specifies a green line "rgba(255,0,0,0.5)" {string}, indicates 50% red line
`style`	any	defines the style of the line (solid by default). Indicates an Array of numbers which specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For instance: null {null} or [] {array}, defines solid grid-lines (default style) 2 {number}, becomes [2, 2, ...] [5, 15, 25] {array}, becomes [5, 15, 25, 5, 15, 25, ...]
`cap`	string	determines the shape used to draw the end points of lines. Determines the shape used to draw the end points of lines, as one of the following: "butt" {string}, the ends of lines are squared off at the endpoints. Default value. "round" {string}, the ends of lines are rounded "square" {string}, the ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness For instance: null {null}, "butt" ends (default value) "round" {string}, the ends of lines are rounded

Since:

Example

null {null}, the control's origin is black, 1-pixel wide and solid
{color: "gray", width: 2} {object}, the control's origin is gray, solid and 2-pixel wide

SetOrigin

SetPad(value)

The SetPad() method sets the space between an element's content and its border. It can be a single number for equal horizontal and vertical padding, or a pair of values ("x,y" or [x, y]) for different horizontal and vertical padding. For example, 8 adds 8 pixels on all sides, while "8,4" adds 8 pixels horizontally and 4 pixels vertically. The Surface.Pad property defines a default padding for all elements, which can be overridden for individual elements using Element.Pad property.

Parameters:

Name	Type	Description
`value`	number \| Array.<number> \| string	Specifies a value that could be: {number} a numeric value, to pad horizontal and vertical size with the same value {(number[]\|string)} a "x,y" or [x,y] type to specify the padding on h/v size

Example

null {null}, indicates that the default padding value of [4,4] is applied
0 {number}, indicates no padding
"8,4" {string}, increases the element's width with 2 * 8-pixels and element's height with 2 * 4-pixels
[8,4] {array}, increases the element's width with 2 * 8-pixels and element's height with 2 * 4-pixels

SetPad

SetReadOnly(value)

The SetReadOnly() method sets the control to read-only mode. When the control is set to read-only, users can still scroll, select, and interact with existing elements, but they cannot create, resize, or move any element within the control. This allows users to view and interact with the content without making any modifications to it. The Locked property, on the other hand, completely prevents user interaction with the control, while read-only mode only prevents modifications to the elements.

Parameters:

Name	Type	Description
`value`	boolean	A boolean value that indicates whether the control is read-only.

Example

false {boolean}, the user can create, resize or move any element
true {boolean}, the user can not create, resize or move any element, but can scroll, select or interact with any element.

SetReadOnly

SetScrollBarsHome(value)

The SetScrollBarsHome() method defines the color used to highlight the position of the origin (0,0) on the control's scroll bars. It accepts a CSS color to display the origin marker, or null to hide it. The ScrollBarsLayout property specifies the color used to highlight the position of the current layout within the control's scroll bars. It accepts a CSS color to display the layout marker, or null to hide it. To display these markers, the ScrollBars property must be set to a value other than exNoScroll so the control shows scroll bars. Additionally, ScrollBarsHome must be set to a CSS color to display the origin marker. By default, ScrollBarsHome is set to "black", which highlights the position of the origin (0,0) on the scroll bars. This feature is useful when the control's content extends in multiple directions from the origin, as it helps users quickly identify their position relative to (0,0) and navigate the content more easily. The onscroll event is fired whenever the user scrolls the control's content. This event can be used to implement custom behavior when the user scrolls, such as updating the position of other elements on the page or loading additional content dynamically. The user can right-click on the scroll bars over the origin marker to automatically scroll the control's content to the origin position (0,0).

Parameters:

Name	Type	Description
`value`	string	Specifies null, to prevent showing the position of origin (0,0) on the control's scroll bars, or a CSS color.

Example

null {null}, hides the origin (0,0) on the control's scroll bar
"black" {string}, shows the origin (0,0) on the control's scroll bar in black

SetScrollBarsHome

SetScrollBarsLayout(value)

The SetScrollBarsLayout() method sets the color used to highlight the position of current layout within the control's scrollbars. It can be set to a CSS color to display the layout marker, or null to hide it. To display this marker, the ScrollBars property must be set to a value other than exNoScroll so the control shows scroll bars. The onscroll event is fired whenever the user scrolls the control's content. By default, ScrollBarsLayout is null, so the position of the current layout is not shown on the scroll bars. This feature is useful when the control's content extends in multiple directions from the origin, as highlighting the current layout on the scroll bars helps users easily identify their position relative to the layout and navigate the content more effectively. The user can right-click on the scroll bars over the layout marker to automatically scroll the control's content to the current layout position.

Parameters:

Name	Type	Description
`value`	string	Specifies null, to prevent showing the position of current layout within the control's scrollbars, or a CSS color.

Example

null {null}, hides the position of the current layout within the control's scroll bars.
"black" {string}, shows in black  the position of the current layout within the control's scroll bars.

SetScrollBarsLayout

SetSelection(value)

The SetSelection() method sets the control's selection. Selected elements are highlighted with a specific color to indicate their selection state. The "select" part of the shapes field defines the appearance of the selected elements, including their color, border, and other visual attributes. The Selection property can be used to set or retrieve the selected elements. It accepts or returns values that identify the elements selected within the control. This property is automatically updated when the Selection property changes or when the user selects or unselects elements in the control. The SingleSel property determines the selection mode of the control. When SingleSel is true, only one element can be selected at a time. When false, multiple elements can be selected simultaneously. The onselchange event is fired whenever the control's selection changes, either by user interaction or programmatically through the Selection property. This event can be used to implement custom behavior when the selection changes, such as updating other parts of the user interface or performing actions based on the selected elements.

Parameters:

Name	Type	Description
`value`	any	The value can be any of the following: value {null}, clears the entire selection (unselect all) value {number}, selects an element giving index within the elements collection value {string}, selects an element giving its identifier/key/plain-caption value {Element}, selects an element giving its reference value {Elements}, selects all elements within the control value {array}, specifies an array of [type] type, where type could be any number, string or Element type

Example

oSurface.SetSelection(null) {any}, clears the entire selection (unselect all)
oSurface.SetSelection(3) {any}, selects an element giving index within the elements collection

SetSelection

SetSelements(value)

The SetSelements() method loads elements of the control from a string-representation. The Selements property is optional, because you can always use the Elements.Add method to add elements individually. However, it is very useful when you want to quickly define the control's elements using a string. The Selements property provides a getter and a setter to handle the control's elements as a string: the setter calls Elements.Load(), which reads the assigned string and creates the corresponding elements in the control, while the getter calls Elements.Save(), returning a string that represents all current elements in the control. This makes it easy to define, store, or transfer the elements using a string representation.

Parameters:

Name Type Description

Name	Type	Description
`value`	string	A string expression that defines the elements of the control from a string-representation. The format of the string representation is (everything between () refers to children, and everything between [] refers to flags): "element1[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value]),...,elementn[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value])" where the element1, sub-element1 ... elementn defines the caption for each element (can include ex-HTML tags). The string representation supports the following flags: [key] {string}, specifies the element's key (Key/GetKey()/SetKey(value) methods of Surface.Element). For instance, [key=root], specifies that the element's key is "root" [vis]/[hid] {number}, shows or hides the element (Visible/GetVisible()/SetVisible(value) methods of Surface.Element). For instance, [hid] or [vis=0], hides the element, while [vis=1] shows the element [dis] {number}, enables or disables the element (Enabled/GetEnabled()/SetEnabled(value) methods of Surface.Element). For instance, [dis] or [dis=0], disables the element, while [dis=1] enables the element [nsel] {number}, indicates whether the user can select, resize or move the element (Selectable/GetSelectable()/SetSelectable(value) methods of exontrol.Surface.Element). For instance, [nsel] or [nsel=0], forces the element to be unselectable, while [nsel=1] makes the element selectable [pos] {number}, changes the element's position (0-based) (Position/GetPosition()/SetPosition(value) methods of Surface.Element). For instance, [pos=0] indicates that the element should be displayed first [img] {string}, assigns a image/picture to the element (Image/GetImage()/SetImage(value) methods of Surface.Element). For instance, [img=logo] assigns the "logo" picture to the element. The image can be added using the exontrol.HTMLPicture.Add method. You can use the [simg] flag to define the element's image to be displayed on the "sub-items" portion of the control. [imgs] {string}, defines the size of the element's image as a string of "aspect-width,aspect-height" type (without quotes) (ImageSize/GetImageSize()/SetImageSize(value) methods of Surface.Element). For instance, [imgs=-32] stretches the element's image into a square of 32x32 size, while [imgs=32,32] fits the element's image into a square of 32x32 size. [imga] {number}, specifies the alignment of the image within the element relative to its caption. The value of "imga" flag can be 0(left), 1(right), 2(top) or 3(bottom). (ImageAlign/GetImageAlign()/SetImageAlign(value) methods of Surface.Element). For instance, [imga=3] aligns the element's image at the bottom of its box [client] {string}, specifies the element's client-rectangle as a string of "x,y,width,height" type (without quotes) (Client/GetClient()/SetClient(value) methods of Surface.Element). For instance, [client=0,0,128,128] specifies the element's client are to [0,0,128,128] [coll] {string}, indicates a collapsed-element (Expand/GetExpand()/SetExpand(value) methods of Surface.Element). For instance, [coll] or [coll=0], collapses the element, while [c=1] expands the element [ft] {number}, specifies the format to display the element's caption. The value of "ft" flag can be a combination of one or more values of exontrol.DrawTextFormatEnum type (FormatText/GetFormatText()/SetFormatText(value) methods of Surface.Element). For instance, [ft=32] displays the element's caption on a single line only. Carriage returns and line feeds do not break the line (32 indicates the value of exontrol.DrawTextFormatEnum.exTextSingleLine) [pad] {string}, defines the element's padding (space between the element's content and its border) (Pad/GetPad()/SetPad(value) methods of Surface.Element). For instance, [pad=4] defines a 4-pixels padding for all edges [shape] {string}, defines the shape for individual element (Shape/GetShape()/SetShape(value) methods of Surface.Element). For instance, [shape=Button] specifies that the element is shown as a "button". [cursor] {string}, defines the mouse-cursor for individual element (Cursor/GetCursor()/SetCursor(value) methods of Surface.Element). For instance, [cursor=wait] indicates that the "wait" mouse-cursor is displayed while the cursor hovers the element [auto] {number}, resizes the element to fit its content (AutoSize/GetAutoSize()/SetAutoSize(value) methods of Surface.Element). For instance, [auto] resizes the element to fit its content [nres] {number}, defines a non-resizable element (Resizable/GetResizable()/SetResizable(value) methods of Surface.Element). For instance, [nres] indicates that the user can not resize the element by drag and drop [nmov] {number}, defines a non-movable element (Movable/GetMovable()/SetMovable(value) methods of Surface.Element). For instance, [nmov] indicates that the user can not move the element by drag and drop

value

string

A string expression that defines the elements of the control from a string-representation.

The format of the string representation is (everything between () refers to children, and everything between [] refers to flags):

"element1[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value]),...,elementn[flag=value]...[flag=value](sub-element1[flag=value]...[flag=value],...,sub-elementn[flag=value]...[flag=value])"

where the element1, sub-element1 ... elementn defines the caption for each element (can include ex-HTML tags).

The string representation supports the following flags:

[key] {string}, specifies the element's key (Key/GetKey()/SetKey(value) methods of Surface.Element). For instance, [key=root], specifies that the element's key is "root"
[vis]/[hid] {number}, shows or hides the element (Visible/GetVisible()/SetVisible(value) methods of Surface.Element). For instance, [hid] or [vis=0], hides the element, while [vis=1] shows the element
[dis] {number}, enables or disables the element (Enabled/GetEnabled()/SetEnabled(value) methods of Surface.Element). For instance, [dis] or [dis=0], disables the element, while [dis=1] enables the element
[nsel] {number}, indicates whether the user can select, resize or move the element (Selectable/GetSelectable()/SetSelectable(value) methods of exontrol.Surface.Element). For instance, [nsel] or [nsel=0], forces the element to be unselectable, while [nsel=1] makes the element selectable
[pos] {number}, changes the element's position (0-based) (Position/GetPosition()/SetPosition(value) methods of Surface.Element). For instance, [pos=0] indicates that the element should be displayed first
[img] {string}, assigns a image/picture to the element (Image/GetImage()/SetImage(value) methods of Surface.Element). For instance, [img=logo] assigns the "logo" picture to the element. The image can be added using the exontrol.HTMLPicture.Add method. You can use the [simg] flag to define the element's image to be displayed on the "sub-items" portion of the control.
[imgs] {string}, defines the size of the element's image as a string of "aspect-width,aspect-height" type (without quotes) (ImageSize/GetImageSize()/SetImageSize(value) methods of Surface.Element). For instance, [imgs=-32] stretches the element's image into a square of 32x32 size, while [imgs=32,32] fits the element's image into a square of 32x32 size.
[imga] {number}, specifies the alignment of the image within the element relative to its caption. The value of "imga" flag can be 0(left), 1(right), 2(top) or 3(bottom). (ImageAlign/GetImageAlign()/SetImageAlign(value) methods of Surface.Element). For instance, [imga=3] aligns the element's image at the bottom of its box
[client] {string}, specifies the element's client-rectangle as a string of "x,y,width,height" type (without quotes) (Client/GetClient()/SetClient(value) methods of Surface.Element). For instance, [client=0,0,128,128] specifies the element's client are to [0,0,128,128]
[coll] {string}, indicates a collapsed-element (Expand/GetExpand()/SetExpand(value) methods of Surface.Element). For instance, [coll] or [coll=0], collapses the element, while [c=1] expands the element
[ft] {number}, specifies the format to display the element's caption. The value of "ft" flag can be a combination of one or more values of exontrol.DrawTextFormatEnum type (FormatText/GetFormatText()/SetFormatText(value) methods of Surface.Element). For instance, [ft=32] displays the element's caption on a single line only. Carriage returns and line feeds do not break the line (32 indicates the value of exontrol.DrawTextFormatEnum.exTextSingleLine)
[pad] {string}, defines the element's padding (space between the element's content and its border) (Pad/GetPad()/SetPad(value) methods of Surface.Element). For instance, [pad=4] defines a 4-pixels padding for all edges
[shape] {string}, defines the shape for individual element (Shape/GetShape()/SetShape(value) methods of Surface.Element). For instance, [shape=Button] specifies that the element is shown as a "button".
[cursor] {string}, defines the mouse-cursor for individual element (Cursor/GetCursor()/SetCursor(value) methods of Surface.Element). For instance, [cursor=wait] indicates that the "wait" mouse-cursor is displayed while the cursor hovers the element
[auto] {number}, resizes the element to fit its content (AutoSize/GetAutoSize()/SetAutoSize(value) methods of Surface.Element). For instance, [auto] resizes the element to fit its content
[nres] {number}, defines a non-resizable element (Resizable/GetResizable()/SetResizable(value) methods of Surface.Element). For instance, [nres] indicates that the user can not resize the element by drag and drop
[nmov] {number}, defines a non-movable element (Movable/GetMovable()/SetMovable(value) methods of Surface.Element). For instance, [nmov] indicates that the user can not move the element by drag and drop

Example

"" {string}, clears the elements collection
"A(A1,A2,A3),B[client=128,128,32,32](B1,B2(B2.1,B2.2),B3)" {string}, defines the element "A" with three child-elements "A1", "A2" and "A2", and element "B" with child-elements "B1", "B2", and "B3", also defines the "B2.1" and "B2.2" as children of element "B2"
"A[img=logo][hid],B[client=128,128,32,32][dis]" {string}, defines the element "A" hidden and with the image "logo" and element "B" as disabled.

SetSelements

SetShapes(value)

The SetShapes() method sets the shapes that each part of the control can display, allowing you to customize its visual appearance. A shape can be specified as a JSON representation of a shape object, the name of a predefined shape within exontrol.Shapes.Surface or exontrol.Shapes, or a CSS color value. Parts that can be customized include element, expand, and others, each corresponding to a different UI component - for example, element affects all elements in the control, while expand defines the look of expand/collapse glyphs. The Shapes property enables you to apply different shapes and colors to control parts, enhancing its overall appearance. For instance, the string "red(element),blue(expand)" applies a red shape to the element part and a blue shape to the expand part of the control.

Parameters:

Name Type Description

value

string

A string expression that defines the shapes each part of the control can display.

The format of the property is:

"shape(part),shape(part),..."

where:

"shape", defines the shape to apply on the UI part as one of the following:
◦ any of 140 color names any browser supports (such as red, blue, green, ...)
◦ hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF (such as #0000ff which defines a blue background)
◦ hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF (such as #0000ff80 which defines a semi-transparent blue background)
◦ RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255( such as rgb(0,0,255) that defines a blue background)
◦ RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) ( such as rgba(0,0,255,0.5) which defines a semi-transparent blue background)
◦ HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors (such as hsl(240, 100%, 50%) that defines a blue background)
◦ HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque) (such as hsla(240, 100%, 50%,0.5) that defines a semi-transparent blue background)
◦ a JSON representation of the shape object to apply (while it starts with { character, such as '{"normal": {"primitive": "RoundRect","fillColor":"black","tfi": {"fgColor": "white"}}}')
◦ specifies the name of the field within the exontrol.Shapes.Surface object (while it starts with a lowercase letter, such as element which refers to exontrol.Shapes.Surface.element shape)
◦ specifies the name of the field within the exontrol.Shapes object (while it starts with an uppercase letter, such as Button which refers to exontrol.Shapes.Button shape)
"part", defines the name of the part the shape is applied on (as defined bellow)

The shapes property supports any of the following parts:

Part Description

"element" defines the visual-appearance of all elements within the control. The shape field defines the shape for individual element.

"expand" specifies the visual appearance for expand/collapse glyphs. The expandGlyphSize field specifies the size to show the element's expand/collapse glyphs.

"frameDrag" specifies the visual appearance to display the frame while dragging the objects

"frameFit" defines the visual-appearance to display the frame while fitting objects into the control's client area by drag

"frameSel" defines the visual appearance to display a frame while selecting objects by drag

"link-be" defines the visual-appearance of the link's end control-point (it changes the end-position of the link)

"link-bs" defines the visual-appearance of the link's start control-point (it changes the start-position of the link)

"link-m" defines the visual-appearance of the link's middle control-point

"link-p" defines the visual-appearance of the link's intermediate control-point

"multiSel" specifies the visual appearance to show the count of multiple-selected items

"select" defines the visual-appearance of selected-element

The exswimlane/js control supports additional parts as listed in the table below:

Part Description

"header" defines the visual-appearance of all headers within the control

"lane" defines the visual-appearance of all lanes for all pools

"laneAlt" defines the visual-appearance of alternate lanes for all pools

"phase" defines the visual-appearance of all phases for all pools

"phaseAlt" defines the visual-appearance of alternate phases for all pools

"pool" defines the visual-appearance of all pools within the control

Example

null {null}, specifies the default visual appearance
"" {string}, no shape (no visual appearance is applied to any part of the control)
"red(element)", "#FF0000(element)", "rgb(255,0,0)(element)", "rgba(255,0,0,1)(element)" {string}, shows all-elements in red
'{"hover":{"frameColor":"black","pad":-0.5}}(element)' {string}, draws a black-frame arround the element being hovered
"xxx(d),yyy(d,m),zzz(y)"  {string}, specifies that the exontrol.Shapes.Surface.xxx combined with exontrol.Shapes.Surface.yyy object defines the visual appearance of "d" part of the control, exontrol.Shapes.Surface.yyy object defines the visual appearance of "m" part of the control and exontrol.Shapes.Surface.zzz object defines the visual appearance of "y" part of the control

SetShapes

SetShowAxes(value)

The SetShowAxes() method specifies whether the control shows or hides the axes (horizontal and vertical). The axes are typically represented by two perpendicular lines that intersect at the origin (0,0) of the surface. The Axes property defines the appearance of the axes as an object of {width, color, style, cap} type. ShowAxes allows you to control the visibility of the axes, which can be useful when working with diagrams or layouts that use a coordinate system. By default, ShowAxes is false, meaning the axes are hidden unless explicitly enabled.

Parameters:

Name	Type	Description
`value`	boolean	Indicates whether the control shows or hides the axes.

Since:

Example

false {boolean}, the control hides the axes
null {null} or true {boolean}, the control shows the axes

SetShowAxes

SetShowGridLines(value)

The SetShowGridLines() method specifies whether the control shows or hides the grid lines, including minor and major grid lines. The MinorGridLines and MajorGridLines properties define the appearance of the surface's minor and major grid lines, respectively. When ShowGridLines is true, the grid lines are displayed, providing a reference when working with coordinates. When false, the grid lines are hidden, offering a cleaner view. This property is especially useful for diagrams or layouts that rely on a coordinate system.

Parameters:

Name	Type	Description
`value`	boolean	Indicates whether the control shows or hides the grid lines (minor and major grid-lines).

Since:

Example

false {boolean}, the control hides the grid lines (minor and major grid-lines)
null {null} or true {boolean}, the control shows the grid lines (minor and major grid-lines)

SetShowGridLines

SetShowLinks(value)

The SetShowLinks() method determines whether the control displays links between elements. It is a bitwise combination of flags that control the visibility and style of the links, such as extended, cross, or orthogonal, and whether they appear in front of or behind elements. For example, links can be shown as extended lines with cross-links at the corners, or all links can be hidden. The available flags are defined in exontrol.ShowLinksEnum and can be combined to achieve the desired link display.

Parameters:

Name Type Description

value

exontrol.ShowLinksEnum

Indicates an exontrol.ShowLinksEnum expression that specifies whether the links between elements are visible or hidden

The exontrol.ShowLinksEnum type supports the following flags:

exHide (0), specifies that no links are visible
exExtended (0x01) specifies that links are shown as extended. This means the control automatically arranges both the start and end points of the links so they do not overlap. For example, if multiple links start from or end at the same element, the control ensures that each link uses a different start or end point instead of all sharing the same position. This helps keep the connections visually separated and easier to distinguish.
exShow (0x02), specifies that links are visible (the links are always shown while not exHide)
exFront (0x10), specifies that links are shown in front (by default, the control are shown on the background)
exCrossRect (0x20) specifies that links are shown with rectangular cross-links. When two links intersect, the control displays the crossing using a rectangular bridge so one link appears to pass over the other without merging. This makes intersections easier to read and helps visually distinguish overlapping links.
exCrossTriangle (0x20) specifies that links are shown with triangular cross-links. When two links intersect, the control displays the crossing using a triangular marker so one link appears to pass over the other without merging. This helps clearly indicate link intersections and improves the readability of overlapping connections.
exCrossMixt (0x60) specifies that links are shown using mixed cross-links. When two links intersect, the control displays the crossing using a combination of cross-link styles (such as rectangular or triangular bridges) so one link appears to pass over the other without merging. This mixed representation helps visually distinguish intersections and improves the readability of overlapping links.
exPreventOverlap (0x100), adjusts the links to prevent them from overlapping the connected objects. The exPreventOverlap flag has effect only for rectangular links. The exPreventOverlap option calculates the path between A and B using the A* (A-star) pathfinding algorithm, which can be a time-consuming operation. The exontrol.L.PO.dir.def specifies the default directions for determining the best route between two points, A and B. These directions are represented as a combination of the letters R (Right), L (Left), U (Up), and D (Down), separated by commas ("RLDU,DURL" {string}, indicates the shortest route between RLDU and DURL directional path). When used with the exPreventOverlapMixt flag, it ensures that links avoid overlapping with elements or obstacles, enabling their paths to include both rectangular and diagonal lines. (@since 4.0)
exPreventOverlapMixt (0x80), When used with the exPreventOverlap flag, it ensures that links avoid overlapping with elements or obstacles, enabling their paths to include both rectangular and diagonal lines. When combined with the exChangeColorOnOverlap flag, overlapping links alternately adjust their width in addition to changing colors. The exPreventOverlapMixt flag must always be used alongside either the exPreventOverlap or exChangeColorOnOverlap flag. (@since 4.0)
exChangeColorOnOverlap (0x200), changes the color for links in areas where they overlap with other links, enhancing clarity and distinction between them. The exontrol.L.PO.OverlapColors defines the list of colors, separated by commas, used to display overlapping links. When combined with the exPreventOverlapMixt flag, overlapping links alternately adjust their width in addition to changing colors. (@since 4.0)

Example

0 or exontrol.ShowLinksEnum.exHide {number}, hides the links
1 or exontrol.ShowLinksEnum.exShow {number}, shows the links (on the background)
33 or exontrol.ShowLinksEnum.exExtended | exontrol.ShowLinksEnum.exCrossRect {number}, shows "extended" and "cross" links

SetShowLinks

SetShowLinksOnCollapse(value)

The SetShowLinksOnCollapse() method shows or hides links between collapsed elements. When set to true, links between collapsed elements are shown, allowing users to see connections even when elements are collapsed; when set to false, these links are hidden for a cleaner view. The appearance of links between collapsed elements can be customized using the CollapsedLink property. The Element.Expand property indicates whether an element is expanded or collapsed.

Parameters:

Name	Type	Description
`value`	boolean	An boolean expression that specifies whether the links between collapsed elements are visible or hidden.

Example

null {null}, shows links between collapsed elements
false {boolean}, hides the links between collapsed elements

SetShowLinksOnCollapse

SetShowOrigin(value)

The SetShowOrigin() method specifies whether the control shows or hides the origin. The origin represents the point (0,0) on the surface and is typically shown as a cross. The Origin property defines the appearance of the origin as an object of {size, width, color, style, cap} type. When ShowOrigin is set to true or null, the origin is displayed, which can be useful as a reference when working with coordinates. When set to false, the origin is hidden, providing a cleaner view when the reference point is not needed. This property is useful when working with diagrams or layouts that rely on a coordinate system.

Parameters:

Name	Type	Description
`value`	boolean	Indicates whether the control shows or hides the origin.

Since:

Example

false {boolean}, the control hides the origin
null {null} or true {boolean}, the control shows the origin

SetShowOrigin

SetSingleSel(value)

The SetSingleSel() method defines whether the control supports single, multiple, toggle selection. The selection mode of the control is determined by the SingleSel property, which can be set to enable single-selection, multiple-selection, or toggle selection. When single-selection is enabled, only one element can be selected at a time. When multiple-selection is enabled, users can select multiple elements simultaneously. When toggle selection is enabled, clicking on an element toggles its selection state (selected/unselected). The Selection property holds the control's selected elements. The selection behavior can be further customized using additional flags that control how users can select elements, such as disabling selection with modifier keys or by dragging.

Parameters:

Name Type Description

value

Surface.SingleSelEnum

An OR combination of exontrol.Surface.SingleSelEnum flags to specify how user can select notes

The Surface.SingleSelEnum type defines the following flags:

exDisableSel(0), specifies that the control's selection is disabled (can not be combined with any other flags)
exEnableSel(1), specifies that the control's selection is enabled (multiple-selection, unless the exSingleSel is set )
exSingleSel(2), specifies that the user can select a element only
exToggleSel(4), specifies that the element's selection state is toggled once the user clicks a element.
exDisableCtrlSel(8), disables toggling the element's selection state when user clicks a element, while CTRL modifier key is pressed.
exDisableShiftSel(16), disables selecting elements using the SHIFT key.
exDisableDrag(32), disables selecting elements by drag.

Example

0 or Surface.SingleSelEnum.exDisableSel {number}, disables selecting any element
3 or Surface.SingleSelEnum.exSingleSel | Surface.SingleSelEnum.exEnableSel {number}, enables control's single selection, so only a single element can be selected
6 or Surface.SingleSelEnum.exToggleSel | Surface.SingleSelEnum.exSingleSel {number}, enables control's single and toggle selection, which means that once a element is selected it gets unselected once it is clicked, or reverse, and only a single-element can be selected at once.

SetSingleSel

SetSlinks(value)

The SetSlinks() method loads links between elements of the control from a string-representation. The links are the connections between elements that can be shown as lines or arrows. The Slinks property is optional, because you can always use the Links.Add method to add links individually. However, it is very useful when you want to quickly define the control's links using a string. The Slinks property provides a getter and a setter to handle the control's links as a string: the setter calls Links.Load(), which reads the assigned string and creates the corresponding links in the control, while the getter calls Links.Save(), returning a string that represents all current links in the control. This makes it easy to define, store, or transfer the links using a string representation.

Parameters:

Name Type Description

value

string

A string expression that defines the links between elements of the control from a string-representation.

The format of the string representation is (everything between [] refers to flags):

"link1[flag=value]...[flag=value],...,linkn[flag=value]...[flag=value]"

where the link1, ... linkn defines the caption for each link (can include ex-HTML tags).

The string representation supports the following flags:

[link] {string} (required), indicates the link's in-out elements in "from-to" format, where from/to indicates the element's key, plain-caption or index (0-based). For instance, [link=11-1], links the elements with index 11 and 1, or [link=root-1] links the element with the key "root" or plain-caption "root" with the element of index 1.
[key] {string}, specifies the link's key (Key/GetKey()/SetKey(value) methods of Surface.Link). For instance, [key=L1], specifies that the link's key is "L1"
[vis]/[hid] {number}, shows or hides the link (Visible/GetVisible()/SetVisible(value) methods of Surface.Link). For instance, [hid] or [vis=0], hides the link, while [vis=1] shows the link
[type] {number}, specifies the type of the link as a value of 0 (rectangular), 1 (direct), 2(straight) or 3(round). For instance, [type=3] defines a round-link
[dir] {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides. For instance, [dir=3] shows the arrows in both-directions of the link.
[width] {number}, specifies the link's width or size. For instance, [width=4] shows a wider link.
[color] {string}, indicates the link's color. For instance, [color=red] specifies a red-link.
[arrow] {string}, indicates the arrow's color. For instance, [arrow=#808080] shows the link's arrow in gray.
[style] {number}, specifies the link's dash pattern to show the lines. For instance, [style=2] shows a dotted-link
[startPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of in-element, where the link can start from. For instance, [startPos=TR,MR,BR] specifies that the link can start anywhere on the in-element's right-side
[endPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of out-element, where the link can end into. For instance, [endPos=TL,ML,BL] specifies that the link can end anywhere on the out-element's left-side

The following flags have effect only when the link is shown between collapsed-elements

[coll-type] {number}, specifies the type of the link as a value of 0 (rectangular), 1 (direct), 2(straight) or 3(round). For instance, [coll-type=3] defines a round-link
[coll-dir] {number}, specifies whether the link's direction is shown or hidden as 0 (hidden), 1(shows the direction/arrow where the link begins), 2(shows the direction where the link ends, default) or 3 shows the arrows in both sides. For instance, [coll-dir=3] shows the arrows in both-directions of the link.
[coll-width] {number}, specifies the link's width or size. For instance, [coll-width=4] shows a wider link.
[coll-color] {string}, indicates the link's color. For instance, [coll-color=red] specifies a red-link.
[coll-arrow] {string}, indicates the arrow's color. For instance, [coll-arrow=#808080] shows the link's arrow in gray.
[coll-style] {number}, specifies the link's dash pattern to show the lines. For instance, [coll-style=2] shows a dotted-link
[coll-startPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of in-element, where the link can start from. For instance, [coll-startPos=TR,MR,BR] specifies that the link can start anywhere on the in-element's right-side
[coll-endPos] {string}, indicates a list of corners separated by comma(,) which can be any of "TL", "TC", "TR", "ML", "MR", "BL", "BC" or "BR" of out-element, where the link can end into. For instance, [coll-endPos=TL,ML,BL] specifies that the link can end anywhere on the out-element's left-side

Example

"" {string}, clears all the links
"L1[link=A-L]" {string}, defines a link between elements with the key "A" and "B" with the caption "L1"
"L1[link=A-L],L2[link=A-0]" {string}, defines two links, one between "A" and "L" with the caption "L1", and another between "A" and element with the index 0, with the caption "L2"

SetSlinks

SetSmooth(value)

The SetSmooth() method sets the time in ms the control goes from one layout to another. The smooth field is a number that defines the time in ms the control goes from one layout to another. Setting the smooth field to 0 means that no smooth changes are performed once the control goes from a layout to another. Setting the smooth field to 125 means that a smooth-transition is performed from a layout to another for 125 ms. The Smooth() method smoothly transitions the control from the current layout to a new layout, applying gradual changes rather than an immediate switch.

Parameters:

Name	Type	Description
`value`	number	Indicates the time in ms the control goes from one layout to another.

Example

0 {number}, no smooth changes once the control goes from a layout to another
125 {number}, specifies that a smooth-transition is performed from a layout to another for 125 ms.

SetSmooth

SetTfi(value)

The SetTfi() method sets the font attributes for the control's captions, allowing precise customization of their appearance by specifying the text style (such as bold or italic), font family, and font size, either as a string (e.g., "b monospace 16") or as an object (e.g., {bold: true, italic: false, fontName: "monospace", fontSize: 16}), and immediately applies these settings to update the displayed captions.

Parameters:

Name Type Description

value

string | object

Indicates a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.

The value as {string} supports any of the following keywords (each keyword can be specified using first letters only such as "b" for "bold) separated by space characters:

bold, displays the text in bold (equivalent of tag)
italic, displays the text in italics (equivalent of tag)
underline, underlines the text (equivalent of tag)
strikeout, specifies whether the text is strike-through (equivalent of <s> tag)
<fontName name>, specifies the font's family (equivalent of tag)
<fontSize size>, specifies the size of the font (equivalent of tag)
<fgColor CSSColor>, specifies the text's foreground color (equivalent of <fgcolor> tag)
<bgColor CSSColor>, specifies the text's background color (equivalent of <bgcolor> tag)
<shaColor CSSColor;width;offset>, defines the text's shadow (equivalent of <sha color;width;offset> tag)
<outColor CSSColor>, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
<graColor CSSColor;mode;blend>, defines a gradient text (equivalent of <gra color;mode;blend> tag)

Any other word within the string value that's not recognized as a keyword is interpreted as:

name of the font (not a number), specifies the font's family (equivalent of tag)
size of the font (number), specifies the size of the font (equivalent of tag)

The value as {object} supports any of the following fields:

bold {boolean}, displays the text in bold (equivalent of tag)
italic {boolean}, displays the text in italics (equivalent of tag)
underline {boolean}, underlines the text (equivalent of tag)
strikeout {boolean}, specifies whether the text is strike-through (equivalent of <s> tag)
fontName {string}, specifies the font's family (equivalent of tag)
fontSize {number}, specifies the size of the font (equivalent of tag)
fgColor {string}, specifies the text's foreground color (CSScolor) (equivalent of <fgcolor> tag)
bgColor {string}, specifies the text's background color (CSScolor) (equivalent of <bgcolor> tag)
shaColor {object}, specifies an object of {color, width, offset} type that defines the text's shadow (equivalent of <sha color;width;offset> tag), where:
- color {string}, defines the color of the text's shadow (CSScolor)
- width {number}, defines the size of the text's shadow
- offset {number}, defines the offset to show the text's shadow relative to the text
outColor {string}, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
graColor {object}, specifies an object of {color, mode, blend} type that defines a gradient text (equivalent of <gra color;mode;blend> tag), where:
- color {string}, defines the gradient-color (CSScolor)
- mode {number}, defines the gradient direction as 0 (left-right), 1 (default, top-bottom), 2 (left-center-right), and 3 (top-center-bottom)
- blend {number}, defines the gradient blend as a value between 0 and 1

CSSColor or CSS legal color values can be specified by the following methods:

Hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF. For example, #0000ff value is rendered as blue, because the blue component is set to its highest value (ff) and the others are set to 00.
Hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF. For example, #0000ff80 defines a semi-transparent blue.
RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255. For example, rgb(0,0,255) defines the blue color.
RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, rgba(0,0,255,0.5) defines a semi-transparent blue.
HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors. For example, hsl(240, 100%, 50%) defines the blue color.
HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, hsla(240, 100%, 50%,0.5) defines a semi-transparent blue.
Predefined/Cross-browser color names, 140 color names are predefined in the HTML and CSS color specification. For example, blue defines the blue color.

Example

null {null}, the tfi field is ignored
"bold monospace 16 &lt;fg blue&gt;" {string}, defines Monospace font of 16px height, bold and blue
{bold: true, fontName: "monospace", fontSize: 16, fgColor: "blue"} {object}, defines Monospace font of 16px height, bold and blue

SetTfi

SetWheelChange(value)

The SetWheelChange() method changes the amount the calendar scrolls when the user rolls the mouse wheel. This setting allows you to adjust the sensitivity of the mouse wheel interaction with the control.

Setting wheelChange to 0 disables mouse wheel actions, preventing the control from changing when the wheel is scrolled
Setting wheelChange to a positive number, such as 5, increases the control's value by that amount each time the wheel is rotated, enabling faster adjustments

By modifying this value, you can fine-tune the control's responsiveness, making it easier for users to perform precise changes or larger adjustments as needed.

Parameters:

Name	Type	Description
`value`	number	A value that specifies the amount the control scrolls when the user rolls the mouse wheel.

Example

0 {number}, locks any action the mouse's wheel performs
18 {number}, scrolls the control by 18-pixels when mouse's wheel is rotated (CTRL + wheel scrolls horizontally)

SetWheelChange

SetZoom(value)

The SetZoom() method defines the zoom factor of the control's content. The zoom factor determines how much the control's content is magnified or reduced. Once the user adjusts the browser's zoom level, the control automatically recalculates its zoom factor to maintain the correct scaling of its content. The ZoomLevels property defines the allowed zoom levels the user can select from.

Parameters:

Name	Type	Description
`value`	number	A numeric value between 10 and 1000 that specifies the zoom factor of the control's content.

Example

null {null}, Specifies normal-view (100%)
150 {number}, Indicates that the control's content is magnfied to 150%

SetZoom

SetZoomLevels(value)

The SetZoomLevels() method defines the allowed zoom levels for the control and can be specified as a comma-separated string of numeric values (e.g., "50,100,150,200"). These values represent the percentage levels at which users can zoom in or out of the control's content. The ZoomLevels property works together with the Zoom property to provide a range of zoom options. For example, if ZoomLevels is set to "50,100,150,200", users can choose from these predefined zoom levels to adjust their view of the content.

Parameters:

Name	Type	Description
`value`	string	specifies a list of numbers separated by comma that indicates the zoom-levels/zoom-margins the control's content is allowed to zoom.

Example

null {null}, Specifies that the control's zoom factor is always 100%
150 {number}, Specifies that the control's zoom factor is always 150%
"50,100,200,350" {string}, Indicates that the zoom-factor can be any of selected values, and the margins of zoom-factor is 50% to 350%

SetZoomLevels

Shuffle(ratio)

The Shuffle() method arranges randomly all elements within the control. The arrangement is applied only to the current layout and is not saved as part of the control's state, so once the layout is changed the elements are restored to their original positions. However, if you want to restore the original layout without changing it, you can use the Unshuffle() method.

Parameters:

Name	Type	Description
`ratio`	number	specifies how far each element is randomized relative to the current size of the layout. For instance, 0 indicates that the element is not moved/shuffled, while 1, indicates that the element can randomize its position up to one width/height.

Example

The following samples show how to shuffle/unshuffle the control's elements when the mouse enters/leaves the control's area:

oSurface.GetCanvas().addEventListener("mouseleave", function()
{
  oSurface.oSV.Shuffle();
})

oSurface.GetCanvas().addEventListener("mouseenter", function()
{
  oSurface.oSV.Unshuffle();
})

Shuffle

Smooth(callback, thisArg)

The Smooth() method makes the control transition smoothly from the current layout to a new layout. In short, it applies a gradual, animated change to the layout generated by the callback, instead of switching instantly. The smooth-transition goes from the current layout to the new layout generated by the callback. The smooth field defines the time in ms the control goes from one layout to another.

Parameters:

Name	Type	Description
`callback`	callback	Indicates a callback function that generates the new layout for the control ( such as removing or adding new elements to the control). The callback is provided with no arguments.
`thisArg`	any	Specifies the value of this keyword for callback functions. If missing, the SV object reference is used instead.

Example

The following sample demonstrates how to use the Smooth() method to perform a smooth transition, such as when adding or removing elements from the control:

 oSurface.Smooth(function()
 {
  ...
 });

Smooth

Soom(zoomTo, oPointAbsopt, rgrOriginopt)

The Soom() method zooms or/and scrolls the control's content. The Soom() method can be used to smoothly zoom in or out of the control's content and scroll to a specific point within the content. This method is particularly useful for providing a better user experience when navigating through large or detailed content, allowing users to focus on specific areas while maintaining context. The zoomTo parameter specifies the target zoom factor, while the oPointAbs and rgrOrigin parameters determine the point to scroll into view and its relative position within the control's client area. By using the Soom() method, developers can create interactive and dynamic interfaces that enhance user engagement with the control's content. The Home() method can be used to reset the view to the default state, showing the entire content at its original size and position, while the FitToClient() method ensures that the entire (null/undefined) or given layout fits the control's client area.

Parameters:

Name	Type	Attributes	Description
`zoomTo`	number		Indicates a numeric value that defines the target-zoom factor as a value between 10 and 1000 (no zoom if null or undefined).
`oPointAbs`	object	<optional>	Specifies an object of {x,y} or array as [x,y] type that specifies the absolute-coordinates of the point to scroll into the client at rgrOrigin relative-position.
`rgrOrigin`	array	<optional>	Specifies a two-elements array of [x,y] type that specifies the ratio on x and y axis to determine the position of the oPointAbs relative to the view page. The x and y values should be value between 0 and 1.

Example

oSurface.Soom(100, [0,0]), zooms to 100% and brings the origin (0,0) at its original position
 oSurface.Soom(150, [0,0], [0,0]), zooms to 150% and brings the origin (0,0) at top-left corner

Soom

Unshuffle()

The Unshuffle() method restores the elements of the control in case they were shuffled. The Shuffle() method arranges randomly all elements within the control. The arrangement is applied only to the current layout and is not saved as part of the control's state, so once the layout is changed the elements are restored to their original positions. However, if you want to restore the original layout without changing it, you can use the Unshuffle() method.

Example

The following samples show how to shuffle/unshuffle the control's elements when the mouse enters/leaves the control's area:

oSurface.GetCanvas().addEventListener("mouseleave", function()
{
  oSurface.oSV.Shuffle();
})

oSurface.GetCanvas().addEventListener("mouseenter", function()
{
  oSurface.oSV.Unshuffle();
})

Unshuffle

onCopy() → {object}

The onCopy() method creates the data to export to the clipboard from selected elements and links between then. The method is used by the Copy method, and allows you to override the format for derived objects. The Copy method is used to copy the selected elements and links to the clipboard, and the Paste method is used to paste them back to the surface. The Selection property indicates the currently selected elements on the surface, as an array of Element type.

Since:

Returns:

Returns an object of {e(lements),l(inks)} type that defines the elements and links to copy, as explained: e(lements), {array} specifies a collection of [{ElementOptions}] type that holds the selected-elements l(inks), {array} undefined or a collection of [{LinkOptions}] type that holds the links between selected-elements

Type: object

onPaste(oData)

The onPaste() method adds elements/links from an object of {e(lements),l(inks)} type (allows you to override the format for derived objects). The Paste method is used to paste the elements and links from the clipboard to the surface, and the Copy method is used to copy them to the clipboard. The Selection property indicates the currently selected elements on the surface, as an array of Element type.

Parameters:

Name	Type	Description
`oData`	object	Indicates an object of {e(lements),l(inks)} type as explained: e(lements), {array} specifies a collection of [{ElementOptions}] type that holds the elements l(inks), {array} undefined or a collection of [{LinkOptions}] type that holds the links between elements.

Since:

Events

onanchorclick

The onanchorclick event occurs once the user clicks an anchor element (the <a id;options> ex-HTML part marks an anchor or hyperlink element). The Element.Caption property can include any number of anchor elements, which are defined by the <a id;options> ex-HTML part. The onclick event occurs when the user clicks the surface, a link or an element, while the onanchorclick event occurs only when the user clicks an anchor element.

The onanchorclick event carries the following information:

id: specifies null (no identifier has been specified for the anchor) or the anchor's identifier, as defined by the id part of <a id;options> ex-HTML part
options: specifies null (no options has been specified for the anchor) or the anchor's options, as defined by the options part of <a id;options> ex-HTML part

which can be used to perform different actions according to the anchor being clicked.

Parameters:

Name Type Description

oEvent

object

Holds information about anchor being clicked.

Properties

Name	Type	Description
`id`	string	specifies null (no identifier has been specified for the anchor) or the anchor's identifier.
`options`	string	specifies null (no options has been specified for the anchor) or the anchor's options.

Since:

Example

The following samples display information about the element being clicked:

oSurface.Listeners.Add("onanchorclick", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.on("anchorclick", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.oSV.onanchorclick = function (oEvent)
{
 console.log(oEvent);
}

where oSurface is an object of Surface type, oSV is member of Surface type, of SV type.

onanchorclick

onchange

The onchange event notifies your application that an element, or more has been changed (create, move/resize, link or expand/collapse). The event is fired once the change has been done, for instance when the user finishes to drag an element, or clicks the expand/collapse glyph. The event is not fired while the change is still in progress, for instance while the user is dragging an element, or before the element is expanded/collapsed. The "undo-redo" action is available starting from 2.0, and it is fired once the control's Undo() or Redo() method is called, or a new Undo/Redo operation is added to the queue.

Parameters:

Name Type Description

oEvent

object

Holds information about the object / action that occured.

Properties

Name	Type	Description
`element`	Element	specifies an object of Element type that indicates the element being changed.
`action`	string	specifies the action such as "create", "move", "link" or "expand" the element is suffer. The "undo-redo" action is available starting from 2.0. In this case the element parameter can be one of the following: 32 (0x20) {number}, specifies that a new Undo/Redo operation has been added to the queue 33 (0x21) {number}, indicates that the control's Undo() method has been called 34 (0x22) {number}, indicates that the control's Redo() method has been called

Example

The following samples display the change within the control that just occured:

oSurface.Listeners.Add("onchange", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.on("change", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.oSV.onchange = function (oEvent)
{
 console.log(oEvent);
}

where oSurface is an object of Surface type, oSV is member of Surface type, of SV type.

onchange

onclick

The onclick event occurs once the user clicks or double-clicks a link or an element. The onanchorclick() event occurs once the user clicks an anchor element (the <a id;options> ex-HTML part marks an anchor or hyperlink element). The onclick event occurs when the user clicks the surface, a link or an element, while the onanchorclick event occurs only when the user clicks an anchor element.

The onclick event carries the following information:

element: specifies null or an object of Element type that indicates the element being clicked
link: specifies null or an object of Link type that indicates the link being clicked
dblClick: indicates whether the user clicks or double-clicks the element
button: indicates which button is pressed while clicking the element as 1 (left), 2 (right) or 4 (middle)
modifiers: specifies a combination of 1, 2, 4 and 16 according with modifier keys (ALT, CTRL, META and SHIFT), or 0 if no modifier keys

which can be used to perform different actions according to the element or link being clicked, and the click type (click/double-click, mouse-button, modifier keys).

Parameters:

Name Type Description

oEvent

object

Holds information about element/link being clicked.

Properties

Name	Type	Description
`element`	Element	specifies null or an object of Element type that indicates the element being clicked.
`link`	Link	specifies null or an object of Link type that indicates the link being clicked.
`dblClick`	boolean	indicates whether the user clicks or double-clicks the element.
`button`	number	indicates which button is pressed while clicking the element as 1 (left), 2 (right) or 4 (middle).
`modifiers`	number	specifies a combination of 1, 2, 4 and 16 according with modifier keys (ALT, CTRL, META and SHIFT), or 0 if no modifier keys.

Example

The following samples display information about the element being clicked:

oSurface.Listeners.Add("onclick", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.on("click", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.oSV.onclick = function (oEvent)
{
 console.log(oEvent);
}

where oSurface is an object of Surface type, oSV is member of Surface type, of SV type.

onclick

onfocuslink

The onfocuslink event notifies your application whenever the user focuses on a new link. The focus link is the link that was last clicked by the user or the link specified programmatically using the FocusLink property. The onfocuslink event is fired whenever the user focuses on a new link, either by clicking on it or programmatically through the FocusLink property. The focus link serves as a visual indicator of the link whose path can be modified by dragging its control points while it is focused. The RemoveSelection method removes the focus link if it exists; if no focus link is present, it instead deletes the currently selected elements. The AllowLinkControlPoint property defines the control points of links that users can use to customize the link's path.

Parameters:

Name	Type	Description
`oEvent`	object	Specifies the control's selection as one of the following: oEvent {null}, indicates that the control has no focused link oEvent {Link}, indicates an object of Link type that defines the newly focused link

Since:

Example

The following samples display the control's selection as soon as it changes:

oSurface.Listeners.Add("onfocuslink", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.on("focuslink", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.oSV.onfocuslink = function (oEvent)
{
 console.log(oEvent);
}

where oSurface is an object of Surface type, oSV is member of Surface type, of SV type.

onfocuslink

onscroll

The onscroll event notifies your application whenever the view is scrolled. The ScrollBars property specifies which scroll bars the control displays. The user can right-click on the scroll bars over the layout marker to automatically scroll the control's content to the current layout position. Similarly, the user can scroll the content by dragging the layout marker along the scroll bars. The onscroll event is triggered whenever the view is scrolled by any of these methods, as well as by using the mouse wheel or touch gestures.

Parameters:

Name Type Description

oEvent

object

Specifies an object of {view,type,value} that holds information about the view's scroll that has been changed.

Properties

Name	Type	Description
`view`	SV	specifies the view, where the scroll occurs.
`type`	exontrol.SB.ModeEnum	specifies the view's scroll that has changed as 0(vertical), 1(horizontal).
`value`	number	specifies the scroll's value as a number.

Example

The following samples display the view's scroll position once it is changed:

oSurface.Listeners.Add("onscroll", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.on("scroll", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.oSV.onscroll = function (oEvent)
{
 console.log(oEvent);
}

where oSurface is an object of Tree type. The oSV is member of Tree type, of SV type.

onscroll

onselchange

The onselchange event notifies your application that the control's selection has been changed. The Selection property can be used to set or retrieve the selected elements. The SelectAll method can be used to select all elements within the control, while the UnselectAll() method clears the control's selection. The onselchange event is fired whenever the control's selection changes, either by user interaction or programmatically through the Selection property. This event can be used to implement custom behavior when the selection changes, such as updating other parts of the user interface or performing actions based on the selected elements.

Parameters:

Name	Type	Description
`oEvent`	object	Specifies the control's selection as one of the following: oEvent {null} indicates that the control has no selected elements oEvent {Element} indicates an object of Element type that defines the control's single-element selected oEvent {Element[]}, specifies an array of [Element] type that holds all selected elements within the control

Example

The following samples display the control's selection as soon as it changes:

oSurface.Listeners.Add("onselchange", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.on("selchange", function (oEvent)
{
 console.log(oEvent);
})

or

oSurface.oSV.onselchange = function (oEvent)
{
 console.log(oEvent);
}

where oSurface is an object of Surface type, oSV is member of Surface type, of SV type.

onselchange