CellOptions class (Pivot)

The cursor field defines the mouse-cursor for individual cell. The Column.CellCursor property defines the mouse cursor for all cells within the column, and it is overridden by the cursor field. If neither the cell nor the column specifies a cursor, the control's cursors field defines the mouse cursor for the cell. The cursors field specifies the mouse cursor to be displayed when pointing over a part of the control.

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

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

"pointer" {string}, The cursor is a pointer that indicates a link (typically an image of a pointing hand)

The data field associates any extra data to the current cell (can be requested within format-expression using the %CD syntax). This feature is particularly useful for storing additional information that may not be directly displayed in the cell but can be utilized for formatting or other purposes. For example, you can store a date object in the data field and then use it in a format-expression to display the date in a specific format. The flexibility of the data field allows you to enhance the functionality of your cells by providing access to custom data that can influence how the cell's content is presented.

The data field is mapped to the Cell.Data property, which means that the following statements are equivalent:

oCell.Options = {data: "extraData"}
oCell.SetOptions({data: "extraData"})
oCell.Data = "extraData"
oCell.SetData("extraData")

0 {number}, the cell's data is 0. For instance, "%CD0 == 0" format-expression selects all cells with the cell's data on 0
"name" {string}, the cell's data is "name". For instance, "%CD0 like `name*`" format-expression selects all cells with the cell's data starting with "name"

The enabled field indicates whether the cell is enabled or disabled. A disabled cell appears dimmed and does not respond to user interactions. The Locked property specifies whether the control is locked or unlocked. A locked control is read-only, and the user cannot interact with it. If the control is locked, all cells within the control are disabled, regardless of their individual enabled state. If the control is unlocked, the enabled state of each cell determines whether it is interactive or not.

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

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

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

The format field specifies the expression to format the cell. If the cell's format field is not specified, the column's format field defines the format to display the cell. If the cell's format field is specified, it overrides the column's format field for the cell. The format field can be used to specify various formats for individual cells, such as displaying half of the value, adding the value of first and second cell and displaying it as a currency, concatenating the caption of first and second cell and so on.

The format-expression supports the following keywords:

value, indicates the value of the current cell ( "value/2 format ``", displays half of the value using current regional format )
%0, %1, %2, ... {any} specifies the value of the cell in the column with the index 0, 1 2, ... ( "currency(%0 + %1)", adds the value of first and second cell and displays it as a currency )
%C0, %C1, %C2, ... {string} specifies the caption of the cell, or the string the cell displays in the column with the index 0, 1 2, ... ( "%C0 + %C1", concatenates the caption of first and second cell )
%CD0, %CD1, %CD2, ... {any} specifies the cell's user-date in the column with the index 0, 1 2, ... ( "%CD0 ? value : ``", displays the cell's value only if the cell's data is not empty )
%CS0, %CS1, %CS2, ... {number} specifies the cell's state in the column with the index 0, 1 2, ... ( "(%CS0 ? `<b>` : ``) + value", displays the cell's value in bold only if the first cell is checked )
%CT0, %CT1, %CT2, ... {boolean} returns true if the cell displays a total field; otherwise, it returns false. The exTotalField / exTotalColumn flag specifies whether the cell displays a total field. For instance, "%CT1" refers to all cells in the second column that display totals, while "not %CT1" refers to all cells in the second column that do not display totals (@since 3.3)
%CE0, %CE1, %CE2, ... {boolean} returns true if the cell is editable; otherwise, it returns false.. For example, "%CE0" refers to all editable cells in the first column, while "not %CE1" refers to all cells in the second column that are read-only (@since 3.3)
%CC0, %CC1, %CC2, ... {number} retrieve the number of child items (this keyword consistently returns identical results for all cells since it pertains to the item that hosts each cell). The ChildCount property returns the number of child items. For example, "%CC0" identifies all parent items, while "%CC0 = 0" identifies all leaf items (@since 3.3)
%CX0, %CX1, %CX2, ... {boolean} returns true if the item hosting the cell is expanded, or false if it is collapsed (this keyword consistently returns identical results for all cells since it pertains to the item that hosts each cell). The Item.Expanded property specifically indicates whether the item is expanded or collapsed. For example, "%CX0" refers to all expanded items, while "not %CX0" identifies all collapsed items (@since 3.3)

The format-expression supports the following unary-operators:

• exp(``), checks whether the item is expanded or collapsed ( "(exp(``) ? `<b>` : ``) + value", shows expanded-items in bold )
• get(`aggregate(list,direction,formula)`), summarizes the cell based on "aggregate(list,direction,formula)" syntax, where:

  aggregate, must be one of the following:
  

  • sum, performs addition of values
  • min, retrieves the minimum value
  • max, retrieves the maximum value
  • count, counts the number of items
  • avg, calculates the average of values
  • std, gets standard-deviation of numbers
  • unique, counts how many distinct values are in the set (@since 4.3)

  list, must be one of the following:
  

  • a number expression that specifies the index of the item being referred
  • all, indicates all items, so the formula is being applied to all items
  • current, refers the current item
  • parent, refers to the parent item
  • root, refers to the root item (the root item has no parent items)

  direction, must be one of the following:

  • dir, collects only direct descendents (child-items)
  • rec, collects recursivelly the leaf descendents ( leaf items ). A leaf item is an item with no child items
  • all, collects all descendents
    

  Currently, the following items are excluded by aggregate functions:

  not-sortable items. The Item.Sortable property specifies whether the item can be sorted ( a sortable item can change its position after sorting, while a not-sortable item keeps its position after sorting. not-selectable items. The Item.Selectable property specifies whether the user can selects/focus the specified item. divider items. The Item.Divider property specifies whether the item displays a single cell, instead displaying whole cells.

  In conclusion, aggregate functions counts ONLY items that are sortable, selectable and not a divider-item.
  
  For instance:

  "get(`count(current,dir,1)`)", gets the count of child-items
  "get(`count(current,all,1)`)", gets the count of all child-items (implies recursively child items)
  "get(`count(current,rec,1)`)", counts the number of leaf items ( a leaf item is an item with no child items )
  "get(`sum(current,dir,%1 ? 1 : 0)`)", counts the number of child-items that have not-empty cells within the second-column
  "get(`sum(current,dir,value)`)", gets the total of values of child-items (direct descendent) within the same column
  "get(`sum(all,rec,value)`)", gets the total of values of leaf-items within the same column
  "get(`sum(parent,dir,dbl(%1) + dbl(%2))`)", gets the addition of all cells in the second (%1) and third (%2) column that are directly descendent of the parent item (sibling)

The format-expression supports the following binary-operators:

0 index `format`, gets the index of the item (0-based). The first added item has the index 0, the second added item has the index 1, and so on. The index of the item remains the same even if the order of the items is changed by sorting or grouping ( "1 index ``", gets the index of the item starting from 1 )
0 rindex `delimiter|format|format|...`, returns the recursive-index of the item ("1 rindex `.|A-Z`", returns values as A, A.1, A.2, B, ...)
0 pos `format`, returns the relative position of the item (the position within the parent's children collection) ( "1 pos ``", returns the position of the item (1-based) within the parent's child items collection )
0 rpos `delimiter|format|format|...`, returns the recursive relative-position of the item (the position within the parent's children collection) ( "1 rpos `.|A-Z`", returns values as A, A.1, A.2, B, ... )
0 opos `format`, returns the relative old position of the item (the position within the parent's children collection) ( "1 opos ``", returns the position of the item (1-based) within the parent's child items collection )
0 ropos `delimiter|format|format|...`, returns the recursive relative-old-position of the item (the position within the parent's children collection) ( "1 ropos `.|A-Z`", returns values as A, A.1, A.2, B, ... )
0 apos `format`, returns the absolute position of the item (the position from the first visible item) ( "1 apos ``", gets absolute position of the item )
0 rapos `delimiter|format|format|...`, returns the recursive absolute-position of the item (the position from the first visible item) ( "1 rapos `.|A-Z`", returns values as A, A.1, A.2, B, ... )

where:

• `delimiter`, is a character to separated recursive-operators such as "rindex", "rpos", "ropos" and "rapos"
• `format`, is a set of characters to be used for specifying the index

Additionally, it supports parent and root unary operators to access the values of parent or root items as explained:

parent (unary operator), refers to the parent item of the current item. This expression allows access to values or properties associated with the immediate parent in the hierarchy or structure ( "parent(1 index ``)", gets the index of the parent-item (1-based) ) (@since 4.3)
root (unary operator), refers to the root item of the current item's hierarchy. This expression allows access to values or properties of the highest-level item in the entire structure, regardless of how deeply nested the current item is ("root(%C0)", retrieves the caption of the first column for the root item) (@since 4.3)

The format field is mapped to the Cell.Format property, which means that the following statements are equivalent:

oCell.Options = {format: "value format ``"}
oCell.SetOptions({format: "value format ``"})
oCell.Format = "value format ``"
oCell.SetFormat("value format ``")

"value format ``" {string}, shows the cell's value formatted as a number (as in regional settings)
"1 index ``" {string}, gets the index (1-based) of the item
"1 rpos `.|A-Z`" {string}, displays A, B, C for root-items, and A.1, A.2, A.1.1, ... B.1, B.2, ... for child-items
"currency(dbl(%0) + dbl(%1))" {string}, adds columns 0 and 1 and displays the result as currency

The formatText field specifies the format to display the cell's caption, as a combination of one or more exontrol.DrawTextFormatEnum flags. If the formatText field is not specified, the control's formatText field defines the format to display the cell's caption. The formatText field can be used to specify various formatting options for the cell's caption, such as alignment, word breaking, ellipsis, and so on.

The exontrol.DrawTextFormatEnum type supports 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 Cell.FormatText property, which means that the following statements are equivalent:

oCell.Options = {formatText: exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom}
oCell.SetOptions({formatText: exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom})
oCell.FormatText = exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom
oCell.SetFormatText(exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom)

null {null}, centers the caption
32 or exontrol.DrawTextFormatEnum.exTextSingleLine {number}, defines a single-line caption
0x2A or exontrol.DrawTextFormatEnum.exTextSingleLine | exontrol.DrawTextFormatEnum.exTextAlignRight | exontrol.DrawTextFormatEnum.exTextAlignBottom {number}, defines a single-line caption right/bottom-aligned

The hasCheck field specifies whether the cell's check-box, radio-button is visible or hidden. The state field specifies the cell's state (unchecked or checked) (can be requested within format-expression using the %CS syntax).

Defines whether the cell's check-box, radio-button is visible as follows:

• null {null}, the column's hasCheck field determines whether the cell's check-box, radio-button is visible or hidden
• 0 {number}, the cell displays no check-box or radio-button
• 1 {number}, the cell displays its check-box.
• 2 {number}, the cell displays its radio-button (only a cell within the children of the parent-item can be checked).

The hasCheck field is mapped to the Cell.HasCheck property, which means that the following statements are equivalent:

oCell.Options = {hasCheck: 2}
oCell.SetOptions({hasCheck: 2})
oCell.HasCheck = 2
oCell.SetHasCheck(2)

null {null}, the cell's check-box or radio-button is determined by the column's hasCheck field
2 {number}, the cell displays its radio-button (cells of the same parent-item make the group of radio-cells, so only once can be checked at the time). By using the cell's individual hasCheck field on 2, you can specify multiple group of radio-buttons within the same column.

The image field specifies the name of the image/picture the cell displays. The image can be added using the exontrol.HTMLPicture.Add method. If the image field is not specified, no image is shown within the cell. You can show extra images in a cell by using the ex-HTML syntax imageName in the Cell.Value property, where imageName refers to an image previously added via the exontrol.HTMLPicture.Add method.

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

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

null {null}, indicates that no image is shown within the cell
"logo" {string}, displays the "logo" image. The image can be added using the exontrol.HTMLPicture.Add method

The imageAlign field defines the individual alignment of the image within the cell as follows:

• 0, the image is on the left of the cell's caption
• 1, the image is on the right of the cell's caption
• 2, the image is on the top of the cell's caption
• 3, the image is on the bottom of the cell's caption

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

oCell.Options = {imageAlign: 1}
oCell.SetOptions({imageAlign: 1})
oCell.ImageAlign = 1
oCell.SetImageAlign(1)

null {null}, the image is aligned left to the caption (default)
1 {number}, the image is displayed to the right of the cell's caption

The imageSize field defines the individual size of the cell's image.

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

• {null}, Indicates that the cell's image is displayed as it is (full-sized).
• {number}, Specifies that the cell's image is displayed into a square of giving size (same width and height). If 0 the object displays no image, if negative the object's image is stretched to giving square, else the object'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 object's picture to scale or stretch to.

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

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

null {null}, indicates that the object'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 pad field defines the individual cell's padding (space between the cell's content and its border), as one of the following:

• {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 horizontal and vertical side

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

oCell.Options = {pad: 8}
oCell.SetOptions({pad: 8})
oCell.Pad = 8
oCell.SetPad(8)

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

The shape field defines the shape for individual cell. The "cell" field of Shapes property defines the visual-appearance for all cells within the control. The Cell.Shape property changes the shape for the cell itself. The Column.CellShape property gets or sets the shape to apply on the column's body/data/cells. , while the shape field defines the visual-appearance for individual cell. If the shape field is not specified, the "cell" field of Shapes property defines the cell's shape. If the shape field is specified, it overrides the "cell" field of Shapes property for the cell. The shape field can be used to specify various shapes for individual cells, such as button-shape, round-rectangle shape and so on.

The shape field can be any of the following:

• the shape's name within the exontrol.Shapes.Pivot 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 Cell.Shape property, which means that the following statements are equivalent:

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

null {null}, no custom shape is applied (default object's shape may be applied)
"" {string}, no custom shape is applied (no default object's shape is be applied)
"red" {string}, fills the object's background in red (CSS color)
'{"fillColor": "red"}' or '{"normal":{"fillColor": "red"}}' {string}, fills the object's background in red (JSON-representation of an object of exontrol.Def.Shape type)
"xxx" {string}, indicates that exontrol.Shapes.Pivot.xxx or exontrol.Shapes.xxx is applied on the object's background. If the xxx field is missing, no custom shape is applied (no default object's shape is be applied)
"Button" or exontrol.Shapes.Button {object}, applies the "Button" shape on the object as defined into exontrol.Shapes namespace (@since 5.2)

The state field specifies the cell's state (unchecked or checked) (can be requested within format-expression using the %CS syntax). The hasCheck field specifies whether the cell's check-box, radio-button is visible or hidden. The state field is valid only for cells that display a check-box or a radio-button, which can be defined by the hasCheck field. The state field defines the cell's state as follows:

• 0, the cell is unchecked
• 1, the cell is checked
• 2, the cell is partially-checked (valid for cells of check-box type)

The state field is mapped to the Cell.State property, which means that the following statements are equivalent:

oCell.Options = {state: 1}
oCell.SetOptions({state: 1})
oCell.State = 1
oCell.SetState(1)

0 {number}, the cell is unchecked
1 {number}, the cell is checked
2 {number}, the cell is partially-checked (valid for cells of check-box type)

The toolTip field defines the cell's predefined tooltip. The tooltip supports ex-HTML tags, such as <fgcolor>, <bgcolor>, <img> and so on. The value field defines the cell's caption, while the toolTip field defines the tooltip for the cell.

The toolTip field is mapped to the Cell.ToolTip property, which means that the following statements are equivalent:

oCell.Options = {toolTip: "tooltip"}
oCell.SetOptions({toolTip: "tooltip"})
oCell.ToolTip = "tooltip"
oCell.SetToolTip("tooltip")

null {null}, the cell's caption is shown once the mouse pointer hovers it, and it is not fully displayed
"" {string}, no tooltip for the cell is displayed
"<img>image</img> and text" {string}, the image and text is being shown once the mouse pointer hovers the cell. The image can be added using the exontrol.HTMLPicture.Add method

The value field defines the cell's value (can be requested within format-expression using the % syntax). The onanchorclick event is fired when the user clicks an anchor element (the <a id;options> ex-HTML part marks an anchor or hyperlink element), and provides information about the anchor being clicked, such as the anchor's identifier and options.

The value field is mapped to the Cell.Value property, which means that the following statements are equivalent:

oCell.Options = {value: "caption"}
oCell.SetOptions({value: "caption"})
oCell.Value = "caption"
oCell.SetValue("caption")

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