new Links(oSurfaceView)
The Links object holds a collection of Link type (link of the control). The link is a connection between two elements of the control, where one element is the source (from) and the other is the target (to). The Links object provides methods to create, manage, and manipulate links between elements on the surface control. You can use the Add() method to create and add a new link to the control, specifying the options for the link as an object of LinkOptions type. The OnCreate() method can be overridden to customize the options for a newly created link by drag-and-drop. The Count/GetCount() method returns the number of links within the collection, while the Item() method retrieves a link based on its index, identifier/key, or reference. The Remove() method allows you to remove a link from the control using its index, identifier/key, or reference. The Clear() method removes all links from the control. Additionally, you can use the Save() and Load() methods to save and load links between elements of the control using string representations.
Parameters:
| Name | Type | Description |
|---|---|---|
oSurfaceView |
SV | Indicates an object of exontrol.Swimlane.SV type. |
Members
(readonly) Count :number
The Count property returns the number of links within the collection. The Add, Remove, RemoveRange, and Clear methods update the count of links in the collection. The Item method gets the link giving its index, identifier/key or reference. The Item and Count properties can be used to enumerate the links within the collection, the same way as using feL and feLU methods of the control.
Type:
- number
Example
The following statements are equivalent:
oSwimlane.Links.Count {number}, returns the number of links within the collection
oSwimlane.Links.GetCount(), returns the number of links within the collection
where oSwimlane is an object of Swimlane typeMethods
Add(oLinkOpts) → {Link}
The Add() method creates and adds a new link to the control. The OnCreate() event can be used to customize the options of a link that is created by drag and drop. The Link.Remove() method removes the link from the control. The Count property returns the number of links in the collection, while the Item() method retrieves a link by its index, identifier/key, or reference.
Parameters:
| Name | Type | Description |
|---|---|---|
oLinkOpts |
LinkOptions | Specifies the options to create the new link as an object of LinkOptions type. |
Returns:
Returns the newly created link, as an object of Link type, or null if adding the new link fails
- Type
- Link
Example
The following example creates and adds a new link into the control:
oSwimlane.Links.Add(
{
from: oElement1, // specifies the in-element of the link as an object of Element type
to: oElement2 // specifies the out-element of the link as an object of Element type
});Clear()
The Clear() method removes all links of the control. The Item method gets the link giving its index, identifier/key or reference. The Count property returns the number of links within the collection. The Item and Count properties can be used to enumerate the links within the collection, the same way as using feL and feLU methods of the control.
Example
oSwimlane.Links.Clear(), removes all links of the controlItem(id) → {Link}
The Item() method gets the link giving its index, identifier/key or reference. The Count property returns the number of links within the collection. The Add, Remove, RemoveRange, and Clear methods update the count of links in the collection. The Item and Count properties can be used to enumerate the links within the collection, the same way as using feL and feLU methods of the control.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
any | The id parameter could be any of the following:
|
Returns:
Returns null if the link is not found, or an object of Link type, if the links collection contains the giving id.
- Type
- Link
Example
The following statements are equivalent:
oSwimlane.feL(function(oLink) { ... });
oSwimlane.Links.forEach(function(oLink) { ... });
for ( var i = 0, n = oSwimlane.Links.Count; i < n; i++ )
var oLink = oSwimlane.Links.Item(i);
where oSwimlane is an object of Swimlane type, and oLink is an object of Link typeLoad(value)
The Load() method loads the control's links from a string, while Save() saves the links to a string. Together, Load() and Save() allow storing and restoring the control's links. The Slinks property mirrors this behavior: its setter calls Links.Load(), and its getter calls Links.Save(), handling links as a string representation.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string | Indicates a string to load links from.
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:
|
Example
"" {string}, loads no link
"link1[link=0-1],link2[link=root-1][key=L3][color=red]" {string}, loads two links, where the first link has caption "link1", links the elements of index 0 and 1, while the second link has caption "link2", links the element with key or plain-caption "root" with the element of index 1, has a key of "L3" and is shown in red color.OnCreate(oLinkOpts) → {boolean}
The OnCreate() method customizes the options for the newly created link by drag. The oLinkOpts parameter contains "from" and "to" fields, that defines link's in and out elements. You can override this method to supply different options for the newly link created by drag. The available options are:
- allowControlPoint {exontrol.Swimlane.LinkControlPointEnum}, defines the control points for an individual link, the user can use to customize the link
- caption {string}, defines the link's caption
- captionAlign {exontrol.AlignEnum}, specifies the alignment of the link's caption (@since 3.4)
- captionFormat {exontrol.DrawTextFormatEnum}, specifies the format/flags to display the caption of the link (@since 3.4)
- collapsedLink {DisplayLinkType}, specifies the appearance of the link between collapsed elements
- customPath {any}, specifies the link's custom path, as a string of x,y proportions separated by comma.
- from {any}, indicates the index, identifier/key or reference of the element the link starts from (in-element)
- key {string}, specifies the key associated with the link
- link {DisplayLinkType}, specifies the appearance of the link between elements
- to {any}, indicates the index, identifier/key or reference of the element the link ends to (out-element)
- visible {boolean}, indicates whether the link is visible or hidden
Parameters:
| Name | Type | Description |
|---|---|---|
oLinkOpts |
LinkOptions | Specifies the options to create the link as an object of LinkOptions type. The oLinkOpts contains "from" and "to" fields, that defines link's in and out elements. |
Returns:
Returns false to create the link, or true to prevent creating a new link
- Type
- boolean
Example
The following example assigns a caption for the newly created link by drag:
oSwimlane.Links.OnCreate = function(oLinkOpts)
{
oLinkOpts.caption = "<bgcolor white>" + (this.Count + 1);
}
The following code creates and adds a new link into the control with a caption, using the Add() method:
oSwimlane.Links.Add(
{
from: oSwimlane.Element(0),
to: oSwimlane.Element(1),
caption: "Link caption"
});
where oSwimlane is an object of Swimlane typeRemove(id)
The Remove() method removes a link from the collection. The Link.Remove() method is equivalent to this method, and removes the link from the control. The Item method gets the link giving its index, identifier/key or reference. The Count property returns the number of links within the collection. The Item and Count properties can be used to enumerate the links within the collection, the same way as using feL and feLU methods of the control.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
any | The id parameter could be any of the following:
|
Example
The following statements are equivalent:
oLink.Remove();
oSwimlane.Links.Remove(oLink);
oSwimlane.Links.Remove(id); // where id is the index, identifier/key or reference of the link to remove
where oSwimlane is an object of Swimlane type, and oLink is an object of Link typeRemoveRange(range)
The RemoveRange() method removes multiple-links at once. The method accepts a link of Link type, an array [Link] contains the links to remove. The Item method gets the link giving its index, identifier/key or reference. The Count property returns the number of links within the collection. The Item and Count properties can be used to enumerate the links within the collection, the same way as using feL and feLU methods of the control.
Parameters:
| Name | Type | Description |
|---|---|---|
range |
Link | Array.<Link> | Indicates a link of Link type, an array [Link], or exontrol.Arr. |
Example
oSwimlane.Links.RemoveRange([oSwimlane.Link(0), oSwimlane.Link(1))]), removes the links of index 0 and 1Save() → {string}
The Save() method saves the control's links into a string representation, while Load() loads the control's links from a string. Together, Load() and Save() allow storing and restoring the control's links. The Slinks property mirrors this behavior: its setter calls Links.Load(), and its getter calls Links.Save(), handling links as a string representation.
Returns:
Returns the control's links into 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 exontrol.Swimlane.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 exontrol.Swimlane.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
- [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
"" {string}, indicates that the control has no link
"link1[link=0-1]" {string}, indicates that the control has a link with caption "link1" that links the elements of index 0 and 1