new Elements(oSurfaceView)
The Elements object holds a collection of Element type (element of the control). The Elements object provides methods to manage the elements of the control, such as adding, removing, clearing, saving and loading elements. The Elements object is accessible through the Elements property of the control. You can use the Elements.Add() method to create and add a new element to the control, Element.Add() to create and add a new child element to an element, and the Element.Remove() method to remove an element from the control. The Elements.Save() and Elements.Load() methods allow you to save and load the elements of the control as a string representation, which can be useful for persisting the state of the control or for transferring it between different instances. The Elements.OnCreate() method can be overridden to customize the options for a new element created by drag.
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 elements in the collection. The Item() method returns an element given its index, identifier/key, or reference, while the Remove() method removes an element using its index, identifier/key, or reference. The Clear() method removes all elements from the control. The Item() and Count methods can be used together to enumerate the elements in the collection.
Type:
- number
Example
The following statements are equivalent:
oSwimlane.Elements.GetCount() {number}, returns the number of elements within the collection
oSwimlane.Elements.Count {number}, returns the number of elements within the collection
where oSwimlane is an object of Swimlane typeMethods
Add(oElementOpts) → {Element}
The Add() method creates and adds a new element to the control. It accepts an object of ElementOptions type to specify the options for the new element and returns the newly created element as an Element object. The parent field of the ElementOptions object specifies the parent element for the new element; if omitted, the element is added to the root of the control. The client field defines the element's client area as an array of [x, y, width, height] type. You can override the OnCreate() method to customize the options for the new element created by drag. The Element.Add method adds child elements to the current element, while the Elements.Add method adds root elements to the control (while no parent is specified in the options).
Parameters:
| Name | Type | Description |
|---|---|---|
oElementOpts |
ElementOptions | Specifies the options to create the new element as an object of ElementOptions type. |
Returns:
Returns the newly created element, as an object of Element type
- Type
- Element
Example
The following code assigns a new caption for the newly created element, which is equal to the number of elements within the collection plus one:
oSwimlane.Elements.OnCreate = function(oElementOpts)
{
oElementOpts.caption = this.Count + 1;
}
The following code creates and adds a new element with a caption "New Element" and a client area of [10, 10, 100, 50] (x=10, y=10, width=100 and height=50):
oSwimlane.Elements.Add({ caption: "New Element", client: [10, 10, 100, 50] });Clear()
The Clear() method removes all elements of the control. Removing an element also removes all its descendant elements and any links that use the element or any of its descendant elements as a source or target. The Remove() method removes an element from the collection. The Element.Remove() method removes the element itself from its collection. The RemoveRange() method removes multiple-elements at once. The RemoveSelection() method deletes the selected-elements.
Example
The following statements are equivalent:
oSwimlane.Elements.Clear(), removes all elements of the control
oSwimlane.Clear(), removes all elements of the control
where oSwimlane is an object of Swimlane typeItem(id) → {Element}
The Item() method gets the element giving its index, identifier/key or reference. The Count property returns the number of elements in the collection. The Remove() method removes an element using its index, identifier/key, or reference. The Clear() method removes all elements from the control. The Item() and Count methods can be used together to enumerate the elements in the collection. The Swimlane.Element() method is equivalent to the Elements.Item() method, as it gets the element giving its index, identifier/key or reference.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
any | The id parameter could be any of the following:
|
Returns:
Returns null if the element is not found, or an object of Element type, if the elements collection contains the giving id.
- Type
- Element
Example
The following statements are equivalent:
oSwimlane.Elements.Item(id) {Element}, gets the element giving its index, identifier/key or reference
oSwimlane.Element(id) {Element}, gets the element giving its index, identifier/key or reference
where oSwimlane is an object of Swimlane typeLoad(value)
The Load() method loads the control's elements from a string, while Save() saves the elements to a string. Together, Load() and Save() allow storing and restoring the control's elements. The Selements property mirrors this behavior: its setter calls Elements.Load(), and its getter calls Elements.Save(), handling elements as a string representation.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string | Indicates a string to load elements from.
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:
|
Example
"" {string}, an empty string, loads no element into the control
"Store[auto](Clothing[auto],Electronics[auto],Groceries[auto]),Manager[client=140,0,96,24]" {string}, loads two elements, "Store" and "Manager", where "Store" element has three children ("Clothing", "Electronics" and "Groceries"), and all elements are auto-sized except "Manager" element that has a client area of [140,0,96,24]OnCreate(oElementOpts) → {boolean}
The OnCreate() method allows you to customize the options for a newly created element when it is added by drag and drop. It accepts an object of ElementOptions type to specify the element's options and returns false to allow creation or true to prevent it. The caption field of ElementOptions defines the element's caption, while the client field specifies the element's client area as an array [x, y, width, height]. Unlike the Add() method, which programmatically adds a new element to the control, OnCreate() is triggered when the user creates an element by dragging.
Parameters:
| Name | Type | Description |
|---|---|---|
oElementOpts |
ElementOptions | Specifies the options to create the new element as an object of ElementOptions type. The oElementOpts contains 'client' field, that defines the element's client area as an array of [x,y,width,height] type. |
Returns:
Returns false to create the element, or true to prevent creating a new element
- Type
- boolean
Example
The following code assigns a new caption for the newly created element, which is equal to the number of elements within the collection plus one:
oSwimlane.Elements.OnCreate = function(oElementOpts)
{
oElementOpts.caption = this.Count + 1;
}
The following code creates and adds a new element with a caption "New Element" and a client area of [10, 10, 100, 50] (x=10, y=10, width=100 and height=50):
oSwimlane.Elements.Add({ caption: "New Element", client: [10, 10, 100, 50] });Remove(id)
The Remove() method removes an element from the collection. Removing an element also removes all its descendant elements and any links that use the element or any of its descendant elements as a source or target. The Element.Remove() method (equivalent of Remove method) removes the element itself from its collection. The RemoveRange() method removes multiple-elements at once. The Clear() method removes all elements from the control. The RemoveSelection() method deletes the selected-elements.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
any | The id parameter could be any of the following:
|
Example
The following statements are equivalent:
oSwimlane.Elements.Remove(id), removes the element giving its index, identifier/key or reference
oSwimlane.Element(id).Remove(), removes the element giving its index, identifier/key or reference
where oSwimlane is an object of Swimlane typeRemoveRange(range)
The RemoveRange() method removes multiple-elements at once. Removing an element also removes all its descendant elements and any links that use the element or any of its descendant elements as a source or target. The Element.Remove() method removes the element itself from its collection. The Remove() method removes an element from the collection. The Clear() method removes all elements from the control. The RemoveSelection() method deletes the selected-elements.
Parameters:
| Name | Type | Description |
|---|---|---|
range |
Swimlane.Element | Array.<Swimlane.Element> | Indicates an element of Element type, an array [{Element}], or exontrol.Arr. |
Example
oSwimlane.Elements.RemoveRange([oSwimlane.Element(0),oSwimlane.Element(1)]), removes the first two elements of the controlSave() → {string}
The Save() method saves the control's elements to a string representation. The Load() method loads the control's elements from a string, while Save() saves the elements to a string. Together, Load() and Save() allow storing and restoring the control's elements. The Selements property mirrors this behavior: its setter calls Elements.Load(), and its getter calls Elements.Save(), handling elements as a string representation.
Returns:
Returns the control's element into 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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 exontrol.Swimlane.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 Swimlane.Element). For instance, [auto] resizes the element to fit its content
- [nres] {number}, defines a non-resizable element (Resizable/GetResizable()/SetResizable(value) methods of Swimlane.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 Swimlane.Element). For instance, [nmov] indicates that the user can not move the element by drag and drop
- Type
- string
Example
"" {string}, an empty string, saves no element into the control
"Store[auto](Clothing[auto],Electronics[auto],Groceries[auto]),Manager[client=140,0,96,24]" {string}, saves two elements, "Store" and "Manager", where "Store" element has three children ("Clothing", "Electronics" and "Groceries"), and all elements are auto-sized except "Manager" element that has a client area of [140,0,96,24]