ElementOptions class (Swimlane)

The lane field specifies the lane of the pool that hosts the element, as a PoolSplitter object. The phase field specifies the phase of the pool that hosts the element. The lane is determined by the element's center point. A lane is a horizontal subdivision of a pool used to group elements, and an element belongs to a lane when its center point lies within the lane's area. The lane option is read-only and can only be changed using the Center() method. The lane field maps to the Element.Lane property.

oSwimlane.Element(0).Center(oSwimlane.Pool(0), oSwimlane.Lane(0,1), oSwimlane.Phase(0,0)), // centers the first-element within the first-pool, lane with index 1 and phase with index 0

The phase field specifies the phase of the pool that hosts the element, as a PoolSplitter object. The lane field specifies the lane of the pool that hosts the element. The phase is determined by the element's center point. A phase is a vertical subdivision of a pool used to group elements, and an element belongs to a phase when its center point lies within the phase's area. The phase option is read-only and can only be changed using the Center() method. The phase field maps to the Element.Phase property.

oSwimlane.Element(0).Center(oSwimlane.Pool(0), oSwimlane.Lane(0,1), oSwimlane.Phase(0,0)), // centers the first-element within the first-pool, lane with index 1 and phase with index 0

The pool field defines the element's pool as a Pool object. An element belongs to a pool when its center point lies within the pool's client area. A pool contains lanes and phases, so the element is also associated with the lane and phase that include its center point. The element can be moved to a different pool, lane, or phase by updating the pool, lane, or phase options, or by using the Center() method to position the element within another pool, lane, or phase. The lane field specifies the lane of the pool that hosts the element. The phase field specifies the phase of the pool that hosts the element. The pool option is read-only, so it can only be updated by using the Center() method. The pool field is mapped to Element.Pool property.

oSwimlane.Element(0).Center(oSwimlane.Pool(0), oSwimlane.Lane(0,1), oSwimlane.Phase(0,0)), // centers the first-element within the first-pool, lane with index 1 and phase with index 0

The autoSize field indicates whether the element's size is automatically computed based on its content. The client field defines the element's client area as an array of [x,y,width,height] type. When autoSize is set to true, the element's size is determined by its content, such as the caption and image, and the client area is automatically adjusted to fit this content. This allows for dynamic resizing of elements based on their content, ensuring that all information is displayed properly without manual adjustments. When autoSize is false, you can manually specify the size of the element using the client field, giving you more control over the layout and appearance of the element on the surface control.

The autoSize field is mapped to the Element.AutoSize property, which means that the following statements are equivalent:

oElement.Options = {autoSize: true}
oElement.SetOptions({autoSize: true})
oElement.AutoSize = true
oElement.SetAutoSize(true)

true {boolean}, the element is automatically resized to fit its content

The caption field defines the element's caption. The caption is a string value that represents the text or content displayed on the element. It can include plain text, ex-HTML tags for formatting (such as <b> for bold), or even references to images (using <img> tags). The caption provides a way to label or describe the element visually, making it easier for users to understand its purpose or function within the surface control. The formatText field specifies the format to display the element's caption. The autoSize field indicates whether the element's size is automatically computed based on its content.

The caption field is mapped to the Element.Caption property, which means that the following statements are equivalent:

oElement.Options = {caption: "name"}
oElement.SetOptions({caption: "name"})
oElement.Caption = "name"
oElement.SetCaption("name")

null {null}, indicates no caption
"caption" {string}, declares a plain-caption
"<b>text</b>" {string}, displays the text in bold
"<img>logo</img>" {string}, displays the "logo" image. The image can be added using the exontrol.HTMLPicture.Add method

The client field defines the element's client area as an array of [x,y,width,height] type. The resizable field specifies whether the user can resize the element by drag and drop. The movable field indicates whether the user can move the element by drag and drop. The autoSize field indicates whether the element's size is automatically computed based on its content. The client field can be used to specify the position and size of the element's content area, allowing for precise control over the layout of the element. By defining the client area, you can ensure that the content is displayed correctly within the element, regardless of its overall size or shape. This is particularly useful when autoSize is set to false, as it allows you to manually manage the element's dimensions and how its content is arranged.

The client field is mapped to the Element.Client property, which means that the following statements are equivalent:

oElement.Options = {client: [0,0,128,128]}
oElement.SetOptions({client: [0,0,128,128]})
oElement.Client = [0,0,128,128]
oElement.SetClient([0,0,128,128])

null {null}, defines an element quivalent with [0,0,32,32]
[0,0,128,128] {number[]}, defines the element at the center of the control of 128 x 128 pixels size

The cursor field defines the mouse-cursor for individual element. The "element" part of the control's cursors field sets the default cursor for all elements. The cursor can be set to any valid CSS cursor value, such as "pointer", "default", "move", "crosshair", and so on. By specifying a custom cursor for an element, you can provide visual feedback to users about the interactivity of the element. For example, setting the cursor to "pointer" can indicate that the element is clickable, while "move" can suggest that the element can be dragged. This enhances the user experience by making it clear how they can interact with different elements on the surface control.

The valid CSS cursor values include, but are not limited to:

• "pointer", a hand cursor, indicating a link or clickable element
• "move", a cursor with four arrows, indicating that the element can be moved
• "crosshair", a cross-shaped cursor, often used for precision selection
• "text", an I-beam cursor, indicating that text can be selected
• "wait", a cursor with an hourglass or spinning circle, indicating that the user should wait
• "help", a cursor with a question mark, indicating that help is available
• "not-allowed", a cursor with a circle and a line through it, indicating that the action is not allowed

The cursor field is mapped to the Element.Cursor property, which means that the following statements are equivalent:

oElement.Options = {cursor: "pointer"}
oElement.SetOptions({cursor: "pointer"})
oElement.Cursor = "pointer"
oElement.SetCursor("pointer")

null {null}, the mouse cursor is determined by the "element" part of the control's cursors field
"pointer" {string}, the mouse cursor changes to a pointer when hovering over the element, indicating that it is clickable

The enabled field enables or disables an element. When enabled is set to false, the element becomes disabled and appears as disabled. The disabled attribute of the shape applied to the element defines its visual appearance in this state. The Selectable property specifies whether the user can select, move, or resize the element, so both properties can be combined to control the element's interactivity. For example, you can set enabled to false to disable the element and Selectable to false to prevent the user from selecting, moving, or resizing it. When enabled is true, the element can be interacted with normally. By default, enabled is true, but it can be changed at any time to enable or disable individual elements.

false {boolean}, disables the element
true {boolean}, enables the element

The expand field indicates whether the element is expanded or collapsed. The expand field is particularly useful for managing the visibility of child elements within a parent element. When an element is collapsed (expand set to false), all of its child elements are hidden, allowing you to create a cleaner and more organized interface. The parent field defines the element's parent, and the position field specifies the element's position in the z-order, with 0 being the background and higher values being displayed on top (if the element is a child of another element, the position is relative to its siblings).

The expand field is mapped to the Element.Expand property, which means that the following statements are equivalent:

oElement.Options = {expand: false}
oElement.SetOptions({expand: false})
oElement.Expand = false
oElement.SetExpand(false)

false {boolean}, collapses the element

The formatText field specifies the format to display the element's caption. The caption field defines the element's caption. The formatText field is a bitwise combination of flags that control the alignment, word-breaking, tab expansion, and other aspects of how text is rendered within the control. For example, you can choose to align text to the center, enable word-breaking for long captions, or specify that text should be displayed on a single line. The exontrol.DrawTextFormatEnum type defines various flags that can be combined to achieve the desired text formatting.

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.

The formatText field is mapped to the Element.FormatText property, which means that the following statements are equivalent:

oElement.Options = {formatText: exontrol.DrawTextFormatEnum.exTextAlignCenter | exontrol.DrawTextFormatEnum.exTextWordBreak}
oElement.SetOptions({formatText: exontrol.DrawTextFormatEnum.exTextAlignCenter | exontrol.DrawTextFormatEnum.exTextWordBreak})
oElement.FormatText = exontrol.DrawTextFormatEnum.exTextAlignCenter | exontrol.DrawTextFormatEnum.exTextWordBreak
oElement.SetFormatText(exontrol.DrawTextFormatEnum.exTextAlignCenter | exontrol.DrawTextFormatEnum.exTextWordBreak)

where oElement is an object of Element type.

The image field specifies the name of the image or picture displayed by the element. Images can be added using the exontrol.HTMLPicture.Add method. The imageSize field defines the size of the element's image, while the imageAlign field defines its alignment within the element. Although the <img> tag can be used in the caption to display an image, the image field provides a more direct way to associate an image with an element. By setting the image property, you can manage and update the image displayed on the element without modifying the caption's HTML content. This approach offers greater flexibility and a clear separation of concerns when designing the layout and appearance of your surface control.

The image field is mapped to the Element.Image property, which means that the following statements are equivalent:

oElement.Options = {image: "logo"}
oElement.SetOptions({image: "logo"})
oElement.Image = "logo"
oElement.SetImage("logo")

null {null}, indicates that the element displays no image
"logo" {string}, specifies that the element displays the "logo" image. The image can be added using the exontrol.HTMLPicture.Add method

The imageAlign field defines the alignment of the image within the element. The image can be aligned to the left, right, top, or bottom of the element's caption. By default, the image is aligned to the left of the caption. This property allows you to control the layout of the image in relation to the text, enabling you to create visually appealing designs that suit your application's needs. For example, aligning the image to the top can create a more vertical layout, while aligning it to the right can balance the visual weight of the element.

The imageAlign propery can be any of the following:

• {null}, the image is aligned according to the control's imageAlign option (Swimlane.ImageAlign property), so the element's image is aligned according to the control's imageAlign option
• 0, the image is on the left of the node's caption
• 1, the image is on the right of the node's caption
• 2, the image is on the top of the node's caption
• 3, the image is on the bottom of the node's caption

The imageAlign field is mapped to the Element.ImageAlign property, which means that the following statements are equivalent:

oElement.Options = {imageAlign: 2}
oElement.SetOptions({imageAlign: 2})
oElement.ImageAlign = 2
oElement.SetImageAlign(2)

null {null}, the image is on top of the node's cation, as indicated by the control's imageAlign field
1 {number}, the image is displayed to the left of the node's caption

The imageSize field defines the size of the element's image. The imageAlign field defines the alignment of the image within the element. The imageSize field can be set to various types to control how the image is displayed. For example, setting imageSize to null displays the image at its full size, while setting it to a number scales the image to fit within a square of that size. You can also specify an array of aspect-width and aspect-height to define limits for scaling or stretching the image.

The imageSize could be of one of the following types:

• {undefined}, indicates that the control's imageSize option (Swimlane.ImageSize property) is considered, so the element's image is measured according to the control's imageSize option.
• {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 node's picture is scaled to fit the giving rectangle.
• {number[]}, 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 node's picture to scale or stretch to.

The imageSize field is mapped to the Element.ImageSize property, which means that the following statements are equivalent:

oElement.Options = {imageSize: 64}
oElement.SetOptions({imageSize: 64})
oElement.ImageSize = 64
oElement.SetImageSize(64)

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

The key field specifies the key associated with the element. The key is a string value that serves as an identifier for the element, allowing you to easily reference and manipulate it within your code. By assigning a unique key to each element, you can quickly access specific elements using methods such as Swimlane.Element("key"), which retrieves the element associated with the given key. This is particularly useful when multiple elements exist on the surface control and you need to perform operations on specific ones without looping through all elements. If no key is provided, the element's plain-caption or its index can be used to request the element. The plain-caption contains no ex-HTML tags, such as <b>, <fgcolor>, and so on, and represents the caption's text content without any formatting. By using the key or the plain-caption, you can efficiently manage and interact with elements on the surface control in your application.

The key field is mapped to the Element.Key property, which means that the following statements are equivalent:

oElement.Options = {key: "logo"}
oElement.SetOptions({key: "logo"})
oElement.Key = "logo"
oElement.SetKey("logo")

"logo" {string}, defines the element with the giving key (logo). You can use the Root.Item("logo") method to request the element giving its key.

The movable field specifies whether the user can move the element, by drag and drop. When movable is set to true, users can click and drag the element itself to reposition it on the surface control. This allows for a more interactive and customizable user experience, as users can arrange elements according to their preferences. The resizable field specifies whether the user can resize the element, by drag and drop. The autoSize field indicates whether the element's size is automatically computed based on its content. The client field defines the element's client area as an array of [x,y,width,height] type. The "move" action must be included in the control's allowActions field to enable moving the element via drag-and-drop.

The movable field is mapped to the Element.Movable property, which means that the following statements are equivalent:

oElement.Options = {movable: false}
oElement.SetOptions({movable: false})
oElement.Movable = false
oElement.SetMovable(false)

false {boolean}, the user can not move the element (by drag and drop)

The pad field 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 Swimlane.Pad property defines the default padding for all elements.

The pad field can be of one of the following types:

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

The pad field is mapped to the Element.Pad property, which means that the following statements are equivalent:

oElement.Options = {pad: "8,4"}
oElement.SetOptions({pad: "8,4"})
oElement.Pad = "8,4"
oElement.SetPad("8,4")

where oElement is an object of Element type.

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

The parent field defines the element's parent. The expand field indicates whether the element is expanded or collapsed. The position field specifies the element's position in the z-order, with 0 being the background and higher values being displayed on top (if the element is a child of another element, the position is relative to its siblings). The parent field can be used to create hierarchical relationships between elements, allowing for the creation of complex structures and layouts on the surface control. For example, when a parent element is collapsed, all of its child elements will also be hidden, providing a way to manage the visibility of groups of elements together.

The parent field can be of one of the following types:

• {null}, indicates that the element is a root element, so it has no parent
• {number}, indicates a numeric value that defines the index of the parent's element (0-based)
• {string}, specifies a string expression that defines the identifier/key/plain-caption of the parent's element
• {Element}, specifies the object reference to the parent's element

The parent field is mapped to the Element.Parent property, which means that the following statements are equivalent:

oElement.Options = {parent: 0}
oElement.SetOptions({parent: 0})
oElement.Parent = 0
oElement.SetParent(0)

0 {number}, indicates that the element with the index 0 is the parent of the current element
"key" {string}, specifies that the parent of the current element is the element with the giving key

The position field specifies the element's position. The position determines the z-order of the element, with 0 being the background and higher values being displayed on top. If the element is a child of another element, the position is relative to its siblings. This property allows you to control the stacking order of elements on the surface control, ensuring that important elements are displayed prominently while less critical ones can be placed in the background.

The position field is mapped to the Element.Position property, which means that the following statements are equivalent:

oElement.Options = {position: 0}
oElement.SetOptions({position: 0})
oElement.Position = 0
oElement.SetPosition(0)

0 {number}, indicates the first-child of the parent element, or an element displayed on the background

The resizable field specifies whether the user can resize the element, by drag and drop. When resizable is set to true, users can click and drag the edges or corners of the element to adjust its size according to their needs. The movable field specifies whether the user can move the element, by drag and drop. The autoSize field indicates whether the element's size is automatically computed based on its content. The client field defines the element's client area as an array of [x,y,width,height] type. The "move" action must be included in the control's allowActions field to enable moving the element via drag-and-drop.

The resizable field is mapped to the Element.Resizable property, which means that the following statements are equivalent:

oElement.Options = {resizable: false}
oElement.SetOptions({resizable: false})
oElement.Resizable = false
oElement.SetResizable(false)

false {boolean}, the user can not resize the element (by drag and drop)

The selectable field indicates whether the user can select, move or resize the element. When selectable is set to false, the element cannot be selected, moved, or resized by the user. This property is useful when you want to prevent user interaction with certain elements on the surface control while still keeping them visible. For example, you might have background elements that provide context but should not be interactable. By setting selectable to false for those elements, you can ensure that users can only interact with the relevant elements in your application. When selectable is true, the user can select, move, and resize the element as needed. By default, selectable is true, allowing for full interactivity with the element.

The selectable field is mapped to the Element.Selectable property, which means that the following statements are equivalent:

oElement.Options = {selectable: false}
oElement.SetOptions({selectable: false})
oElement.Selectable = false
oElement.SetSelectable(false)

false {boolean}, the user can't select, resize or move the element
true {boolean}, the user can select, resize or move the element

The shape field defines the shape of an individual element. While the element part of the shapes field sets the default shape for all elements, the shape field allows you to specify a unique shape for a single element that differs from the control's default. This enables the creation of visually distinct elements on the surface control, improving usability and making it easier to differentiate between elements. The shape field accepts various types of values, providing flexibility in defining an element's appearance. The disabled attribute of the shape determines the element's visual appearance when it is disabled.

The shape field can be one of the following:

• the shape's name within the exontrol.Shapes.Swimlane or exontrol.Shapes namespace
• a CSS color
• a JSON string-representation of an object of exontrol.Def.Shape type
• an object of {normal,hover,click,disabled} type. The normal, hover, click and disabled are objects of exontrol.Def.Shape type

The shape field is mapped to the Element.Shape property, which means that the following statements are equivalent:

oElement.Options = {shape: "red"}
oElement.SetOptions({shape: "red"})
oElement.Shape = "red"
oElement.SetShape("red")

"red" {string}, the element is displayed with a red background color

The visible field determines whether an element is shown or hidden on the surface control. It is a boolean value: when set to true, the element is displayed and can be interacted with by the user; when set to false, the element is hidden and cannot be interacted with. This property allows you to dynamically show or hide elements based on user actions or specific conditions in your application. By default, visible is true, so elements are visible when created. You can modify this property at any time to control the visibility of individual elements on the surface control.

The visible field is mapped to the Element.Visible property, which means that the following statements are equivalent:

oElement.Options = {visible: false}
oElement.SetOptions({visible: false})
oElement.Visible = false
oElement.SetVisible(false)

false {boolean}, hides the element
true {boolean}, shows the element