Cell class (Pivot)

The Caption property gets the cell's caption (the cell's caption includes any column's format). The Value property gets or sets the cell's value. The Column.Format property of the Column defines how the cell's value is displayed. The Caption property is equivalent with the GetCaption() method. The Image property gets or sets the cell's individual image. The ToolTip property gets or sets the cell's predefined tooltip.

The following sample shows how to get the cell's caption:

 oCell.Caption {string}, gets the cell's caption including any column's format

where oCell is an object of Cell type

The Column property gets the cell's column, as an object of Column type. The Item property gets the cell's item, as an object of Item type. The Column property is equivalent with the GetColumn() method. The Pivot.Cell(item, column) method accesses a cell by the specified item and column, and returns an object of Cell type, which represents the cell.

The following statements are equivalents:

 oCell.GetColumn(), gets the cell's column, as an object of Column type
 oCell.Column, gets the cell's column, as an object of Column type

where oCell is an object of Cell type

The Cursor property gets or sets the mouse cursor for the cell itself. The Cursors/GetCursors()/SetCursors(value) {string}, defines the mouse cursor to display when pointing over different parts of the control. The Cursor property is equivalent with the GetCursor()/SetCursor(value) methods.

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

The Data property gets or sets the cell's extra data. The cell's extra data can be any type of data such as number, string, object, etc. The cell's extra data is not displayed within the cell, but it can be used to store additional information related to the cell. The Value property gets or sets the value displayed within the cell. The Data property is equivalent with the GetData()/SetData(value) methods.

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 property enables or disables the cell. A disabled cell cannot be edited and shows its content in a disabled-appearance. The Enabled property is equivalent with the GetEnabled()/SetEnabled(value) methods. The Pivot.Locked property locks or unlocks the control. The user can't select any item, sort any column, or edit any item when the control is locked(protected). By default, the cell is enabled.

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

The Format property formats the cell's content itself. 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 property is equivalent with the GetFormat()/SetFormat(value) methods.

"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 property gets or sets the format to display the cell's value itself. The FormatText property specifies a value of exontrol.DrawTextFormatEnum value that defines how the cell's value is displayed. 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.

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
"right" {string}, defines a caption right-aligned

The HasCheck property shows or hides the cell's check-box or radio-button is visible or hidden, as explained bellow.

• null {null}, the Column.HasCheck property 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 State property of the Cell object indicates the cell's state (unchecked or checked). The onchange("check-cell") event notifies that a cell has been checked or unchecked through user interaction only (not programmatically). The Image property gets or sets the cell's individual image. The HasCheck property is equivalent with the GetHasCheck()/SetHasCheck(value) methods.

null {null}, the cell's check-box or radio-button is determined by the Column.HasCheck property
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 property gets or sets the cell's individual image. The image can be added using the exontrol.HTMLPicture.Add method. The Value property gets or sets the cell's value. The HasCheck property shows or hides the cell's check-box or radio-button is visible or hidden. The Column.FormatImage property defines the expression to determine the images the column display. The Image property is equivalent with the GetImage()/SetImage(value) methods. The image is displayed in the cell according to the ImageAlign property. The image's size is defined by the ImageSize property.

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

The ImageAlign property gets or sets the alignment of the cell's image relative to its value, as one of the following:

• 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 Column.ImageAlign property takes priority over the control's ImageAlign property, and the Cell.ImageAlign property takes priority over the Column.ImageAlign property. When the Cell.ImageAlign property is null, the alignment falls back to the Column.ImageAlign property, and if the Column.ImageAlign property is also null, the control's ImageAlign property is used. By default, the image is aligned left to the caption. The ImageAlign property is equivalent with the GetImageAlign()/SetImageAlign(value) methods.

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 property defines the size of the cell's image, as one of the following:

• {undefined}, Indicates that the control's imageSize option is considered, so the cell's image is measured according to the control's imageSize option
• {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 Column.ImageSize property takes priority over the control's ImageSize property, and the Cell.ImageSize property takes priority over the Column.ImageSize property. When the Cell.ImageSize property is null, the size falls back to the Column.ImageSize property, and if the Column.ImageSize property is also null, the control's ImageSize property is used. In short, the size priority is: Cell -> Column -> Control. The ImageSize property is equivalent with the GetImageSize()/SetImageSize(value) methods.

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 Item property gets the cell's item, as an object of Item type. The Column property gets the cell's column, as an object of Column type. The Item property is equivalent with the GetItem() method. The Pivot.Cell(item, column) method accesses a cell by the specified item and column, and returns an object of Cell type, which represents the cell.

The following statements are equivalents:

 oCell.GetItem(), gets the cell's item, as an object of Item type
 oCell.Item, gets the cell's item, as an object of Item type

where oCell is an object of Cell type

The Options property changes the cell's options (visibility, value, ...) at once. The Options property is equivalent with the GetOptions() and SetOptions() methods. The Pivot.Cell(item, column) method accesses a cell by the specified item and column, and returns an object of Cell type, which represents the cell.

The following sample shows how to set the cell's image to its original size, aliged to the right:

 oPivot.Cell(0).Options = {image: "al", imageSize: null, imageAlign: 1}, sets the cell's image to its original size, aliged to the right

where oPivot is an object of Pivot type

The Pad property gets or sets the cell's padding or the space between cell's content and its borders, as explained:

• {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 Column.Pad property takes priority over the control's Pad property, and the Cell.Pad property takes priority over the Column.Pad property. When the Cell.Pad property is null, the padding falls back to the Column.Pad property, and if the Column.Pad property is also null, the control's Pad property is used. In short, the padding priority is: Cell -> Column -> Control. The Pad property is equivalent with the GetPad()/SetPad(value) methods.

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 property changes the shape for the cell itself, as explained:

• {null}, no custom-shape is applied on the object (default-shape may be applied instead)
• 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 Shapes/GetShapes()/SetShapes(value) {any}, defines the shapes to apply when the mouse is over different parts of the control. The Shape property is equivalent with the GetShape()/SetShape(value) methods. The Column.CellShape property gets or sets the shape to apply on the column's body/data/cells. The Column.Shape property changes the shape for the column itself (column's header). The Item.Shape property defines the shape for the item itself.

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 property gets or sets the cell's state. If the Cell.HasCheck property is null, the visibility of the cell's check box or radio button is determined by the Column.CellHasCheck property. The State property is equivalent with the GetState()/SetState(value) methods. The onchange("check-cell") event notifies that a cell has been checked or unchecked through user interaction only (not programmatically). The ToggleCheck() method toggles the cell's state from checked to unchecked, and reverse.

0 {number}, the cell is unchecked
1 {number}, the cell is checked

The ToolTip property gets or sets the cell's predefined tooltip. The Value property gets or sets the cell's value. The Image property gets or sets the cell's individual image. The ToolTip property is equivalent with the GetToolTip()/SetToolTip(value) methods. The ToolTip property supports ex-HTML tags such as <img> to display images within the 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 property gets or sets the cell's value. The Value property supports ex-HTML tags. The Column.Format property of the column defines how the cell's value is displayed. The Caption property returns the cell's caption including any column's format. The Image property gets or sets the cell's individual image. The ToolTip property gets or sets the cell's predefined tooltip. The Value property is equivalent with the GetValue()/SetValue(value) methods. The onchange("change-cell") event occurs when the cell's value has been changed through the UI. Editing the cell's content in the UI requires the "edit" action to be enabled in the AllowActions property.

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 Edit() method edits the current cell. The onchange("change-cell") event occurs when the cell's value has been changed through the UI. The Value property gets or sets the cell's value. The Edit() method can be used to show the cell's editor and change the cell's value through the UI. The Edit() method accepts an object of EditOptions type that holds options to show the cell's editor. The Edit method works even if the control's AllowActions property does not include the "edit" action.

The following samples edits the cell being clicked:

oPivot.on("click", function(oEvent)
{
  oEvent.cell?.Edit(
  {
    selectAll: true
  })
})

The following sample validates the cell's value to be less than 10:

oPivot.on("click", function(oEvent)
{
  oEvent.cell?.Edit(
  {
    selectAll: true,
    validate: function(value)
    {
      return value > 10;
    },
  })
})      

The following sample validates any value, but always ensures that's not greater than 10:

oPivot.on("click", function(oEvent)
{
  oEvent.cell?.Edit(
  {
    selectAll: true,
    validate: function(value)
    {
      return this.SetValue(Math.min(10, value)) || true;
    },
  })
})

The Evaluate() method evaluates the formula and returns the result. The formula can be a simple value, or a complex expression that includes keywords and operators as explained in the Format property description. The formula is evaluated based on the current cell's context, which allows for dynamic formatting and calculations.

"value/2 format ``", displays half of the value using current regional format
 "1 index ``", gets the index (1-based) of the item

The ToggleCheck() method toggles the cell's state from checked to unchecked, and reverse. The State property gets or sets the cell's state. If the Cell.HasCheck property is null, the visibility of the cell's check box or radio button is determined by the Column.CellHasCheck property. The onchange("check-cell") event notifies that a cell has been checked or unchecked through user interaction only (not programmatically).

oPivot.Cell(0,0).ToggleCheck(); // toggles the state of the first cell in the first item