PoolOptions class (Swimlane)

The PoolOptions class holds all options a pool can display or own. A pool is a container that organizes elements using lanes and phases. Lanes divide the pool horizontally, while phases divide it vertically. Pools are displayed as rectangles on the control, while lanes and phases appear as subdivisions within the pool. Elements can be assigned to a specific lane and phase so they are displayed within the corresponding section of the pool. Almost all properties of a pool refer to the pool itself. To access the elements contained within the pool, including those in its inner-pools (recursively), you can use the Pool.Objects property.

The client field specifies the pool's client area using an array in the format [x, y, width, height]. A pool appears as a rectangle on the control, and this field determines its position and size. The headers field defines the pool's headers using a string representation. Note that the client field accounts for the size of all headers, meaning the client area includes the headers within the pool's total rectangle.

The client field can be any of the following:

• {number[]}, specifies the pool's client area as an array of [x,y,width,height] type
• {null}, specifies the union all visible-elements (collapsed child-elements or hidden elements are ignored) (@since 2.0)
• {Elements[]}, specifies the union of the giving visible-elements (collapsed child-elements or hidden elements are ignored).
• {String[]}, specifies the union of the giving keys of the visible-elements (collapsed child-elements or hidden elements are ignored). For instance, ["A","B"] changes the pool's client-rectangle to cover the elements with the key "A" and "B" (@since 2.0)
• {Element}, indicates the element's client-rectangle (@since 2.0)

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

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

null {null}, specifies the union all visible-elements (collapsed child-elements or hidden elements are ignored) (@since 2.0)
[0,0,128,128] {array}, defines the pool at the center of the control of 128 x 128 pixels size
oControl.Elements {Elements[]}, sets the pool's client-rectangle to cover all visible-elements (@since 2.0)
oControl.Selection {Elements[]}, sets the pool's client-rectangle to cover all selected-elements (@since 2.0)
["A","B"] {String[]}, sets the pool's client-rectangle to cover the elements with the key "A" and "B" (@since 2.0)

The cursor field defines the mouse-cursor for individual pool. 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 pool, you can provide visual feedback to users about the interactivity of the pool. For example, setting the cursor to "pointer" can indicate that the pool is clickable, while "move" can suggest that the pool can be dragged. This enhances the user experience by making it clear how they can interact with different pools 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 Pool.Cursor property, which means that the following statements are equivalent:

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

The enabled field indicates whether the pool is enabled or disabled (unselectable). Disabling the pool affects only the pool itself (its client-area and headers), not its elements. When disabled, the pool is displayed using disabled colors. The Element.Enabled property enables or disables the element itself, while the Pool.Enabled property enables or disables the pool without affecting its elements.

The enabled field is mapped to Pool.Enabled property, which means that the following statements are equivalent:

oPool.Options = {enabled: false}
oPool.SetOptions({enabled: false})
oPool.Enabled = false
oPool.SetEnabled(false)

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

The excludeHeaders field indicates whether the lanes and phases are not displayed over the pool's headers. If set to false, the lanes and phases are displayed over the pool's headers, meaning they can overlap with the headers. If set to true, the lanes and phases are not displayed over the pool's headers, ensuring that the headers remain visible and unobstructed by the lanes and phases. The headers field specifies the pool's headers using a string representation.

The excludeHeaders field is mapped to Pool.ExcludeHeaders property, which means that the following statements are equivalent:

oPool.Options = {excludeHeaders: true}
oPool.SetOptions({excludeHeaders: true})
oPool.ExcludeHeaders = true
oPool.SetExcludeHeaders(true)

false {boolean}, the pool's lanes and phases are displayed over the pool's headers
true {boolean}, the pool's lanes and phases are not displayed over the pool's headers

The headers field specifies the pool's headers using a string representation. Headers are displayed around the pools client area and can be anchored to any of the four sides: left, top, right, or bottom. Each header can have its own attributes, such as size and shape, allowing you to customize both the appearance and layout of the pools headers. The phases field defines the pools phases, which run horizontally from the left to the right side, while the lanes field defines the pools lanes, which run vertically from top to bottom. The excludeHeaders field determines whether lanes and phases are prevented from overlapping the pools headers.

The format of headers property is:

"type[flag=value]...[flag=value],...,type[flag=value]...[flag=value]"

where:

• "type", defines the type of the header, which can be any of the following
  • "left", defines the pool's header anchored to the left-side
  • "top", defines the pool's header anchored to the top-side
  • "right", defines the pool's header anchored to the right-side
  • "bottom", defines the pool's header anchored to the right-side
• "flag", defines a property of the header such as:
  • [size=value], defines the size of the header, where value is a numeric value
  • [shape=value], defines the shape of the header.

  The headers field is mapped to Pool.Headers property, which means that the following statements are equivalent:

  oPool.Options = {headers: "left[size=24][shape=Button],top[size=24]"}
  oPool.SetOptions({headers: "left[size=24][shape=Button],top[size=24]"})
  oPool.Headers = "left[size=24][shape=Button],top[size=24]"
  oPool.SetHeaders("left[size=24][shape=Button],top[size=24]")
  

null {null}, defines no visible headers, but the user can resize and show them, equivalent with "left[size=0],right[size=0],top[size=0],bottom[size=0]".
"" {string}, defines no visible headers.
"left[size=24][shape=Button],top[size=24]", shows the left and top-headers of the pool with specified size and shape.

The key field specifies the key associated with the pool. If no key is provided, the pool can be referenced using its plain-caption, which excludes any ex-HTML tags such as <b>, <fgcolor>, and others. Using the key field is recommended to ensure the pool can be reliably identified even if its caption changes. The Element.Key property specifies the key associated with an element, while the Pool.Key property specifies the key associated with a pool.

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

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

"logo" {string}, defines the pool with the giving key (logo). You can use the Swimlanel.Pool("logo") method to request the pool giving its key.

The lanes field defines the pool's lanes using a string representation (the lanes extend vertically from the top to the bottom side of the pool). Lanes represent horizontal sections within a pool and can be used to group elements. Each lane can have its own attributes, such as size and shape, allowing you to customize the appearance and layout of the lanes within the pool. The phases field defines the pool's phases, which run horizontally from the left to the right side of the pool, while the headers field defines the pool's headers, which can be anchored to any of the four sides: left, top, right, or bottom.

The format of lanes field is:

"caption[flag=value]...[flag=value],...,caption[flag=value]...[flag=value]"

where:

• "caption", defines the lane's ex-HTML caption (shown into the pool's header). The headers field specifies the pool's headers.
• "flag", defines a property of the lane such as:
  • [size=value], defines the size of the lane (in percent), where value is a numeric value. 0 or negative value hides the lane
  • [shape=value], defines the shape of the lane.

The lanes field is mapped to Pool.Lanes property, which means that the following statements are equivalent:

oPool.Options = {lanes: "Lane 1[size=20],Lane 2,Lane 3,Lane 4[shape=FrameSel]"}
oPool.SetOptions({lanes: "Lane 1[size=20],Lane 2,Lane 3,Lane 4[shape=FrameSel]"})
oPool.Lanes = "Lane 1[size=20],Lane 2,Lane 3,Lane 4[shape=FrameSel]"
oPool.SetLanes("Lane 1[size=20],Lane 2,Lane 3,Lane 4[shape=FrameSel]")

null {null}, displays no lanes for the pool
"Lane 1,Lane 2", displays two-lanes for the pool named Lane 1 and Lane 2
"Lane 1[size=20],Lane 2,Lane 3,Lane 4[shape=FrameSel]", displays four-lanes where Lane 1 takes 20% from the pool, while the rest of lanes shares equaly the available space on the pool. The Lane 4 displays the FrameSel shape.

The phases field defines the phases of the pool using a string-representation (the phases goes horizontally from left to right side of the pool). Phases represent vertical sections within a pool and can be used to group elements. Each phase can have its own attributes, such as size and shape, allowing you to customize the appearance and layout of the phases within the pool. The lanes field defines the pool's lanes, which run vertically from top to bottom, while the headers field defines the pool's headers, which can be anchored to any of the four sides: left, top, right, or bottom.

The format of phases field is:

"caption[flag=value]...[flag=value],...,caption[flag=value]...[flag=value]"

where:

• "caption", defines the phase's ex-HTML caption (shown into the pool's header)
• "flag", defines a property of the phase such as:
  • [size=value], defines the size of the phase (in percent), where value is a numeric value. 0 or negative value hides the phase
  • [shape=value], defines the shape of the phase.

The phases field is mapped to Pool.Phases property, which means that the following statements are equivalent:

oPool.Options = {phases: "Phase 1[size=20],Phase 2,Phase 3,Phase 4[shape=FrameSel]"}
oPool.SetOptions({phases: "Phase 1[size=20],Phase 2,Phase 3,Phase 4[shape=FrameSel]"})
oPool.Phases = "Phase 1[size=20],Phase 2,Phase 3,Phase 4[shape=FrameSel]"
oPool.SetPhases("Phase 1[size=20],Phase 2,Phase 3,Phase 4[shape=FrameSel]")

null {null}, displays no phases for the pool
"Phase 1,Phase 2", displays two-phases for the pool named Phase 1 and Phase 2
"Phase 1[size=20],Phase 2,Phase 3,Phase 4[shape=FrameSel]", displays four-phases where Phase 1 takes 20% from the pool, while the rest of phases shares equaly the available space on the pool. The Phase 4 displays the FrameSel shape.

The shape field defines the visual shape of an individual pool. It determines the appearance of the pool's client-area, the area containing the pool's elements, excluding the pool's headers. If the shape field is not specified, the shapes field provides the default visual appearance for various parts of the control, including all pools, such as:

• "pool", defines the visual-appearance of all pools within the control
• "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

In other words, the "pool" shape defines the default visual-appearance for all pools, but the shape field of a pool can override the "pool" shape for individual pool. For instance, if the "pool" shape is set to "Frame", but a pool has its shape field set to "Button", then that pool is shown using the "Button" shape, while the rest of pools are shown using the "Frame" shape.

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

oPool.Options = {shape: "Button"}
oPool.SetOptions({shape: "Button"})
oPool.Shape = "Button"
oPool.SetShape("Button")

The shape field can be any of the following:

• {null}, no custom-shape is applied
• 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 visible field indicates whether the pool is visible or hidden. The visible field does not hide the pool's elements, but hides the pool itself (the pool's client-area and headers). If the pool is hidden, its elements are shown as if the pool does not exist. The Element.Visible property shows or hides the element itself, while the Pool.Visible property shows or hides the pool (the pool's client-area and headers) but not its elements.

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

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

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