Link class (Swimlane)

Link(oLinks, oLinkOptsopt)

The Link object holds information(options) about a link within the control. A link is a line that connects two elements of the control, and has its own options such as caption, visibility, color and so on. You can use the Links.Add method to create and add a new link into the control, and then use the link's methods to set its options.

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

caption, defines the link's caption
is associated with the property:
Caption {string}, defines the link's caption
which means that the following statements are equivalent:
oLink.Options = {caption: "name"}
oLink.SetOptions({caption: "name"})
oLink.Caption = "name"
oLink.SetCaption("name")
where oLink is an object of Link type
Parameters:
Name Type Attributes Description
oLinks Links Indicates an object of Links type that's the owner collection of this link.
oLinkOpts object <optional>
 Specifies the options to create the link, as an object of LinkOptions type.

Members

AllowControlPoint :Swimlane.LinkControlPointEnum

The AllowControlPoint property defines the control points available for a specific link. Control points allow users to customize the link's path by dragging them to new positions. The CustomPath property defines the link's custom path as a string of x,y proportions separated by commas. When defined, AllowControlPoint overrides the control-wide AllowLinkControlPoint property and applies only to the current link. Users can drag and drop the displayed control points to change the link's path or remove intermediate control points by dragging them onto another control point. Control points are displayed only if the ShowLinks property is different from 0. AllowControlPoint is effective only if the "link-cp" action is included in the AllowActions property and the control is not read-only.
Type:
Example
0 or exontrol.Swimlane.LinkControlPointEnum.exNoControlPoint {number}, displays no link's control points
3 or exontrol.Swimlane.LinkControlPointEnum.exStartControlPoint | exontrol.Swimlane.LinkControlPointEnum.exEndControlPoint {number}, displays link's start and end control points only
AllowControlPoint

Caption :string

The Caption property defines the link's caption. The CaptionAlign property specifies the alignment of the link's caption. The caption can include plain text or ex-HTML tags to format the text or display images. For example, you can use <b> tags to make the caption bold, or <img> tags to display an image as the caption. The Caption property allows you to provide descriptive text for the link, making it clearer what the link represents or where it leads. By using ex-HTML tags, you can further customize the appearance of the caption to make it more visually appealing and informative.
Type:
  • string
Example
null {null}, indicates no caption
"caption" {string}, declares a plain-caption
"&lt;b&gt;text&lt;/b&gt;" {string}, displays the text in bold
"&lt;img&gt;logo&lt;/img&gt;" {string}, displays the "logo" image. The image can be added using the exontrol.HTMLPicture.Add method
Caption

CaptionAlign :exontrol.AlignEnum

The CaptionAlign property defines the alignment of the link's caption. The caption field defines the link's caption. The caption can be aligned to the left, right, top, or bottom of the link. By default, the caption is centered on the link. This property allows you to control the placement of the caption in relation to the link, enabling you to create visually appealing designs that suit your application's needs. For example, aligning the caption to the left can create a more traditional layout, while aligning it to the top can give a more modern look.
Type:
  • exontrol.AlignEnum
Since:
  • 3.4
Example
null {null}, (default) the link's caption is displayed in the center
"left" {string}, exontrol.AlignEnum.exAlignLeft {exontrol.AlignEnum} or exontrol.AlignEnum.exAlignTop {exontrol.AlignEnum}, indicates that the link's caption is displayed at the starting element
"alignr" {string}, exontrol.AlignEnum.exAlignRight {exontrol.AlignEnum} or exontrol.AlignEnum.exAlignBottom {exontrol.AlignEnum}, indicates that the link's caption is displayed at the ending element
CaptionAlign

CaptionFormat :exontrol.DrawTextFormatEnum

The CaptionFormat property defines the format or flags used to display the link's caption. The Caption property defines the link's caption, while the CaptionAlign property specifies the alignment of the caption relative to the link. The caption can include plain text or ex-HTML tags to format the text or display images. The CaptionFormat property allows you to apply specific formatting options to the caption, such as text alignment, word wrapping, tab expansion, and other text display features.
Type:
  • exontrol.DrawTextFormatEnum
Since:
  • 3.4
Example
null {null}, (default) the link's caption is displayed in the center of the alignment point
"left,vcenter" {string}, exontrol.DrawTextFormatEnum.exTextAlignLeft | exontrol.DrawTextFormatEnum.exTextAlignVCenter {exontrol.DrawTextFormatEnum} , the link's caption is centered and aligned to the left of the alignment point
CaptionFormat
The CollapsedLink property defines the appearance of the link between collapsed elements. The Element.Expand property indicates whether an element is expanded or collapsed. When an element is collapsed, the links connecting it to other elements can be displayed differently to visually indicate the collapsed state. The Swimlane.Link property specifies the appearance of the link between elements. The Swimlane.CollapsedLink property defines the default appearance for links between collapsed elements, while the Link.CollapsedLink property allows you to define a custom appearance for a specific link when it connects collapsed elements.

The object includes any of the following:

  • type {exontrol.TypeEnum}, 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 list of corners of in-element, the link can start from
  • endPos {any}, indicates the list of corners of out-element, the link can end to
Type:
Example
null {null}, indicates the link uses the control's default appearance for collapsed links
{color:"red", width:2} {object}, defines a link with red color and width of 2 for collapsed links
CollapsedLink

CustomPath :any

The CustomPath property defines the link's custom path as a string of x,y proportions separated by commas ("x,y,x,y,..."). The x and y values represent the proportions of the link's control points relative to the start and end points of the link. The value 0,0 indicates the link's start point, while 1,1 indicates the link's end point. For example, "0.5,0,0.5,1" defines a path that goes from the start (0,0) to (0.5,0), then to (0.5,1), and finally to the end (1,1). The CustomPath property is considered only if AllowControlPoint is different from 0 and the "link-cp" action is included in the AllowActions property.
Type:
  • any
Example
"0.5,0,0.5,1" defines the link to go from start (0,0) to (0.5,0), then (0.5,1), and finally to the end (1,1)
CustomPath

From :any

The From property defines the index, identifier/key, or reference of the element the link starts from (in-element). The To property indicates the index, identifier/key, or reference of the element the link ends to (out-element). The From and To properties define the connection between two elements on the surface control, where From represents the starting element of the link and To represents the ending element.

The property can be one of the following types:

  • {number}, indicates a numeric value that defines the index of the element
  • {string}, specifies a string expression that defines the identifier/key/plain-caption of the element
  • {Element}, specifies the object reference to the element
Type:
  • any
Example
"0" {string}, defines the link starts from the element with index 0
"logo" {string}, defines the link starts from the element with the key "logo"
From

Index :number

The Index property gets the link's index. The index is a zero-based number that indicates the position of the link within the control's links collection. The first link has an index of 0, the second link has an index of 1, and so on. You can use the index to reference and manipulate the link programmatically, such as retrieving the link using the Swimlane.Link() method, Links.Item(index) method or removing the link using the Links.Remove(index) method. You can use the Key property to assign a unique identifier to a link, making it more reliable to reference than by its index, which may change when links are added or removed.
Type:
  • number
Example
The following statements are equivalent:

 oLink.GetIndex() {number}, retrieves the link's index
 oLink.Index {number}, retrieves the link's index

where oLink is an object of Link type
Index

Key :string

The Key property specifies the key associated with the link. The key is a string identifier that allows the link to be easily referenced and manipulated programmatically. If no key is provided, the link's plain-caption can be used to request the link. The plain-caption contains no ex-HTML tags, such as <b> or <fgcolor>, and represents the caption text without formatting.
Type:
  • string
Example
"logo" {string}, defines the link with the giving key (logo). You can use the Root.Item("logo") method to request the link giving its key.
Key
The Link property defines the appearance of the link between elements. The CollapsedLink property specifies the appearance of the link when it connects collapsed elements. The Swimlane.GetLink() method returns the control's default link appearance, while the Link.Link property sepcifies the custom appearance of a specific link, if it is defined. By default, the Link property is null, which means the link uses the control's default appearance. To customize the appearance of a specific link, you can set the Link property to a DisplayLinkType object that defines visual attributes such as the link's color, width (thickness), style, and other display characteristics.

The object includes any of the following:

  • type {exontrol.TypeEnum}, 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 list of corners of in-element, the link can start from
  • endPos {any}, indicates the list of corners of out-element, the link can end to
Type:
Example
null {null}, indicates the link uses the control's default appearance
{color:"red", width:2} {object}, defines a link with red color and width of 2
Link

Options :LinkOptions

The Options property defines all properties of a link at once using a LinkOptions object, including caption, visibility, and more. You can define these options when creating the link with Links.Add(oLinkOpts) or modify them later using the link's Options property, allowing flexible control over its settings at any time.

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

caption, defines the link's caption
is associated with the property:
Caption {string}, defines the link's caption
Type:
Example
{caption: "name"} {LinkOptions}, defines the link's caption as "name"
{link: {type: 3, color: "red"}} {LinkOptions}, defines the link's type as round and color as red
Options

To :any

The To property defines the index, identifier/key or reference of the element the link ends to (out-element). The From property indicates the index, identifier/key or reference of the element the link starts from (in-element). The From and To properties define the connection between two elements on the surface control, where From represents the starting element of the link and To represents the ending element.

The property can be one of the following types:

  • {number}, indicates a numeric value that defines the index of the element
  • {string}, specifies a string expression that defines the identifier/key/plain-caption of the element
  • {Element}, specifies the object reference to the element
Type:
  • any
Example
"0" {string}, defines the link ends to the element with index 0
"logo" {string}, defines the link ends to the element with the key "logo"
To

Visible :boolean

The Visible property shows or hides the link. The ShowLinks property of the control specifies whether links are displayed on the surface control. If ShowLinks is set to a non-zero value, links can be displayed according to their Visible property. However, if ShowLinks is set to 0, all links are hidden regardless of their Visible property. By default, Visible is true, which means that links are shown unless they are explicitly hidden.
Type:
  • boolean
Example
false {boolean}, hides the link
true {boolean}, shows the link
Visible

Methods

The EndUpdateLink() method adds programmatically updated properties of the link to undo/redo queue. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property specifies whether the control supports undo/redo operations for objects (links, links, ...). No entry is added to the Undo/Redo queue if no property is changed for the current link. The UpdateLink() method automatically calls StartUpdateLink and EndUpdateLink methods, so you can use it to record changes to a link's properties in the control's Undo/Redo queue without calling those methods directly.
Parameters:
Name Type Description
startUpdateLink any Holds the result of a StartUpdateLink() method.
Since:
  • 2.0
Example
The following samples are equivalent:

 var oStartLinkUpdate = oLink.StartUpdateLink();
 // ... changes to the link's properties
 oLink.EndUpdateLink(oStartLinkUpdate);

or 

 oLink.UpdateLink(function()
 {
  // ... changes to the link's properties
 });
EndUpdateLink

EnsureVisible()

The EnsureVisible() method scrolls the control's content to ensure that the link fits the control's visible area (expands its from/to elements if case). The method has no effect if the link is not displayed in the control (for instance, if one of its from/to elements is collapsed, or the link is between collapsed elements). The EnsureVisibleClient() method of the view is used to ensure that the link fits the control's visible area.
Since:
  • 2.0
Example
oLink.EnsureVisible(), scrolls the control's content to ensure that the link fits the control's visible area (expands its from/to elements if case)
EnsureVisible

Remove() → {boolean}

The Remove() method removes the link itself from its collection. It is equivalent to calling the Links.Remove(oLink) method, where oLink is the link to remove. The Links.Clear() method can be used to remove all links at once. The Visible property of the link can be used to hide the link without removing it from the collection.
Returns:
Returns true if the link is successfully removed, else false
Type
boolean
Example
oLink.Remove() {boolean}, removes the link itself from its collection, returns true if the link is successfully removed, else false
Remove
The StartUpdateLink() method starts changing properties of the link, so EndUpdateLink method adds programmatically updated properties to undo/redo queue. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property specifies whether the control supports undo/redo operations for objects (links, links, ...). No entry is added to the Undo/Redo queue if no property is changed for the current link. The UpdateLink() method automatically calls StartUpdateLink and EndUpdateLink methods, so you can use it to record changes to a link's properties in the control's Undo/Redo queue without calling those methods directly.
Since:
  • 2.0
Returns:
Returns undefined (no undo/redo is allowed) or an object to be passed to EndUpdateLink method.
Type
object
Example
The following samples are equivalent:

 var oStartLinkUpdate = oLink.StartUpdateLink();
 // ... changes to the link's properties
 oLink.EndUpdateLink(oStartLinkUpdate);

or 

 oLink.UpdateLink(function()
 {
  // ... changes to the link's properties
 });
StartUpdateLink
The UpdateLink() method records the changes of link's properties into control's Undo/Redo queue. You can use the StartBlockUndoRedo / EndBlockUndoRedo methods to group multiple Undo/Redo operations into a single-block. The AllowUndoRedo property specifies whether the control supports undo/redo operations for objects (links, links, ...). No entry is added to the Undo/Redo queue if no property is changed for the current link. The UpdateLink() method automatically calls StartUpdateLink and EndUpdateLink methods, so you can use it to record changes to a link's properties in the control's Undo/Redo queue without calling those methods directly.
Parameters:
Name Type Description
callback callback Specifies a function of callback() type.
thisArg any Indicates the value of "this" keyword during the callback, or the object itself if missing.
Example
The following samples are equivalent:

 var oStartLinkUpdate = oLink.StartUpdateLink();
 // ... changes to the link's properties
 oLink.EndUpdateLink(oStartLinkUpdate);

or 

 oLink.UpdateLink(function()
 {
  // ... changes to the link's properties
 });
UpdateLink