Item class (Pivot)

Item(oItems, oItems)

new Item(oItems, oItems)

The Item object holds the cells and options of the item within the control. The Pivot.Item(id) method returns the item based on its index or identifier/key. The Item.Cell(id) method gets the item's cell giving the column's index, identifier/key/caption or reference.

Every option of the ItemOptions type has associated a property of the Item object. For instance, the option:

cursor {string}, defines the mouse-cursor for individual item
is associated with the property:
Cursor {string}, defines the mouse-cursor for individual item
which means that the following statements are equivalent:
oItem.Options = {cursor: "pointer"}
oItem.SetOptions({cursor: "pointer"})
oItem.Cursor = "pointer"
oItem.SetCursor("pointer")
where oItem is an object of Item type
Parameters:
Name Type Description
oItems Items Indicates an object of Items type that's the owner collection of this item.
oItems ItemOptions Specifies the options to apply on the item.

Members

AllowSizing :boolean

The AllowSizing property makes an item resizable or fixed, as explained:
  • null {null}, the control's itemAllowSizing field specifies whether the item is resizable or fixed
  • false {boolean}, the item is fixed
  • true {boolean}, the item is resizable, so user can resize the item by drag (if "item-resize" action is allowed)

The onchange("resize-item") event is raised only when the item height is changed by dragging. The "item-resize" action allows the user to change the height of an item by dragging it. The AllowSizing property is equivalent with GetAllowSizing()/SetAllowSizing(value) methods.

Type:
  • boolean
Example
null {null}, the control's itemAllowSizing field specifies whether the item is resizable or fixed
false {boolean}, the item is fixed
true {boolean}, the item is resizable, so user can resize the item by drag (if "item-resize" action is allowed)
AllowSizing

(readonly) ChildCount :number

The ChildCount property returns the number of child items of the item. The ChildCount property is equivalent with the GetChildCount() method. The ChildCount property returns the number of child items or 0 if the item has no children. The Item.Add metod adds a child item to the item, while the Item.Remove method removes a child item from the item. The Child() method gets the child item at the specified index within the item's children collection.
Type:
  • number
Since:
  • 5.1
Example
The following code snippet:

   for ( var i = 0; i < oItem.ChildCount; i++ )
     console.log( oItem.Child(i) );

 enumerates all child-items of oItem
ChildCount

Cursor :string

The Cursor property gets or sets the mouse cursor for the item itself. The Cursors/GetCursors()/SetCursors(value) {string}, defines the mouse cursor to display when pointing over different parts of the control. The GetCursor() method returns the mouse-cursor for the item itself. The SetCursor() method changes the mouse cursor for the item itself.
Type:
  • string
Example
"pointer" {string}, The cursor is a pointer that indicates a link (typically an image of a pointing hand)
Cursor

Divider :any

The Divider property gets or sets the index or identifier/key/caption or reference of the cell that's single displayed by the item. A divider-item displays a single cell only, while a multiple-columns item displays all cells. The GetDivider() method gets the index or identifier/key/caption or reference of the cell that's single displayed by the item. The SetDivider() method sets the index or identifier/key/caption or reference of the cell that's single displayed by the item.
Type:
  • any
Example
null {null}, multiple-columns item (no divider-item)
0 {number}, divider-item that always displays the cell with the index 0
"xxx" {string}, divider-item that always displays the cell on the column "xxx" (key or plain-caption)
Divider

Enabled :boolean

The Enabled property enables or disables the item. A disabled item cannot be selected or edited. A disabled item is displayed in gray, depending on the current theme of the control. The Shapes property may define a different appearance for disabled items. The Selectable property specifies whether the item is selectable. The Enabled property is equivalent with GetEnabled()/SetEnabled(value) methods.
Type:
  • boolean
Example
false {boolean}, disables the item
true {boolean}, enables the item
Enabled

Expanded :boolean

The Expanded property expands or collapses the item. The GetExpanded() method specifies whether the item is expanded or collapsed. The SetExpanded() method expands or collapses the item. The onchange("expand-item") event is raised when the item is expanded or collapsed (only by user interaction, not by API calls). The ExpandAll() method expands or collapses all items based on the giving parameter (true to expand, false to collapse). The ToggleExpand() method toggles the item's expand state. For instance, if the item is expanded, the ToggleExpand() method collapses the item. The Expanded property is equivalent with GetExpanded()/SetExpanded(value) methods.
Type:
  • boolean
Example
false {boolean}, the item is collapsed
true {boolean}, the item is expanded (item's children are shown)
Expanded

(readonly) GroupItem :number

The GroupItem property indicates a group item if positive or zero (specifies the index of the column that has been grouped). It is equivalent with the GetGroupItem() method. The GroupItem property is an integer value that specifies the index of the column that has been grouped. A regular item returns -1 by GroupItem property. The onaddgroupitem and onremoveitem events are raised when an item is added or removed as a group-item, respectively.
Type:
  • number
Example
The following statements are equivalents:

 oItem.GetGroupItem(), indicates a group item if positive or zero
 oItem.GroupItem, indicates a group item if positive or zero

where oItem is an object of Item type
GroupItem

Height :array

The Height property defines the item's individual height. The GetHeight() method returns the item's individual height (if defined). The SetHeight() method changes the item's individual height. The control's defaultItemHeight field defines the default height for all items that have no individual height defined. The onchange("resize-item") event is raised only when the item height is changed by dragging. The AllowSizing property allows the user to change the height of items by dragging. The "item-resize" action allows the user to change the height of an item by dragging it. The Height property is equivalent with GetHeight()/SetHeight(value) methods.
Type:
  • array
Example
null {null}, indicates that the item's height is defined by the control's defaultItemHeight field (22)
18 {number}, specifies the item's height to 18
Height

(readonly) Index :number

The Index property retrieves the item's index (0-based). The Index property is read-only. The Index property is equivalent with GetIndex() method. The Position property is equivalent with GetPosition()/SetPosition(value) methods. The Position property gets or sets the item's position (0-based).
Type:
  • number
Example
The following statements are equivalents:

 oItem.GetIndex(), retrieves the item's index
 oItem.Index, retrieves the item's index

where oItem is an object of Item type
Index

Key :string

The Key property assigns a new key to the item. The Key property is equivalent with GetKey()/SetKey(value) methods. The Key property specifies the item's key (the Items.Item(key) requests an item by its index, identifier/key or reference). The key is used to identify the item and to request it by its key using the Items.Item(key) method. If the item's key is missing or empty its index is used instead.
Type:
  • string
Example
"logo" {string}, defines the item with the giving key (logo). You can use the Root.Item("logo") method to request the item giving its key.
Key

Lock :Pivot.LockItemEnum

The Lock property locks or unlocks the item, placing it at the top, bottom, or making it scrollable, as explained:
  • exontrol.Pivot.LockItemEnum.exLockTop {Pivot.LockItemEnum} or -1 {number}, locks the item at the top
  • exontrol.Pivot.LockItemEnum.exUnlock {Pivot.LockItemEnum} or 0 {number}, unlocks the item, making it scrollable
  • exontrol.Pivot.LockItemEnum.exLockBottom {Pivot.LockItemEnum} or +1 {number}, locks the item at the bottom
The GetLockedItemsCount(alignment)/SetLockedItemsCount(alignment, value), specifies the number of items fixed on the top or bottom side of the control. The Lock property is equivalent with GetLock()/SetLock(value) methods.
Type:
Since:
  • 4.6
Example
"top" {string} or -1 {number}, locks the item at the top
"unlock" {string} or 0 {number}, unlocks the item, making it scrollable
Lock

(readonly) Locked :number

The Locked property determines whether the items is locked and in which section of the control it is placed - either locked at the top, scrollable, or locked at the bottom, as explained below:
  • -1 {number}, indicates that item is part of locked-items (top)
  • 0/null/undefined {number}, indicates that item is part of scrollable items (unlocked)
  • +1 {number}, indicates that item is part of locked-items (bottom)

The Lock property locks or unlocks the item, placing it at the top, bottom, or making it scrollable. The onclick event may not be fired if the Locked property is true

Type:
  • number
Since:
  • 4.6
Example
The following statements are equivalents:

   if (oItem.Locked) { ... }  // checks whether the item is locked (either at top or bottom of the control)

 where oItem is an object of Item type
Locked

Options :ItemOptions

The Options property defines the item's options (visibility, caption, ...) at once. This method allows you to update multiple settings of an item in a single call, providing a convenient way to modify the item's appearance and behavior on the control. You can pass an object of ItemOptions type with the desired properties to change, and the method will apply those changes to the event accordingly.

Each option of the ItemOptions type has associated a property of the Item object. For instance, the option:

cursor {string}, defines the mouse-cursor for individual item
is associated with the property:
Cursor {string}, defines the mouse-cursor for individual item
which means that the following statements are equivalent:
oItem.Options = {cursor: "pointer"}
oItem.SetOptions({cursor: "pointer"})
oItem.Cursor = "pointer"
oItem.SetCursor("pointer")
where oItem is an object of Item type.

It is important to note that changing a field of the ItemOptions object does not automatically update the control. For example, oItem.Options.cursor = "pointer" does not apply the change. Instead, you must assign the Options property again, such as oItem.Options = {cursor: "pointer"}, so the control updates and applies the new value.

Type:
Example
The following statements are equivalents:

 oPivot.Item(0).Options = {shape: "red", height: 32}, changes the item's height and background
 oPivot.Item(0).SetOptions({shape: "red", height: 32}), changes the item's height and background

where oPivot is an object of Pivot type
Options

Parent :null|Item

The Parent property gets or sets the item's parent as explained below.
  • {number}, indicates a numeric value that defines the index of the parent's item
  • {string}, specifies a string expression that defines the identifier/key of the parent's item
  • {Item}, specifies the object reference to the parent's item

The Parent property is equivalent with the GetParent() and SetParent() methods. The GetParent() method returns the item's parent as an object of Item type. The SetParent() method sets the item's parent. The Position property gets or sets the item's position (0-based). The onchange("drag-item") event occurs once the user moves the item by drag an drop. The user can move an item to a new position within the control by drag and drop when the "item-drag" action is enabled in the AllowActions property.

Type:
Example
0 {number}, indicates that the item with the index 0 is the parent of the current item
"key" {string}, specifies that the parent of the current item is the item with the giving key
Parent

Position :number

The Position property gets or sets the item's position. The Position property is equivalent with GetPosition()/SetPosition(value) methods. The Index property is equivalent with GetIndex() method. The Index property retrieves the item's index (0-based). The position for each item can change once the user sorts a column or repositions them using drag-and-drop operation. The onchange("drag-item") event occurs once the user moves the item by drag an drop. The user can move an item to a new position within the control by drag and drop when the "item-drag" action is enabled in the AllowActions property.
Type:
  • number
Example
The following statements are equivalents:

 oItem.GetPosition(), retrieves the item's position
 oItem.Position, retrieves the item's position

where oItem is an object of Item type
Position

Selectable :boolean

The Selectable property defines whether the item is selectable. An unselectable item cannot be selected by user interaction. The Selectable property is equivalent with GetSelectable()/SetSelectable(value) methods. The GetSelectable() method specifies whether the item is selectable. The SetSelectable() method defines whether the item is selectable.
Type:
  • boolean
Example
false {boolean}, the item is unselectable
true {boolean}, the item is selectable
Selectable

Selected :boolean

The Selected property defines whether the item is selected. The Selection property of the control holds the collection of selected items. The Selectable/GetSelectable()/SetSelectable(value) {boolean}, specifies whether the item is selectable. The Selected property is equivalent with GetSelected() and SetSelected() methods. The onselchange event is raised when the selection is changed. The SingleSel property gets or sets the control's selection to single, multiple or toggle.
Type:
  • boolean
Example
false {boolean}, the item is unselected
true {boolean}, the item is selected
Selected

Shape :any

The Shape property defines the shape for the item itself as one of the following:
  • 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 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. The Column.Shape property defines the shape to apply on the column's header. The Shapes property defines the shapes for each part of the control can display.

Type:
  • any
Example
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)
Shape

ShowExpand :boolean|number

The ShowExpand property specifies whether the item's expand/collapse glyphs is visible or hidden. The ShowExpand property is equivalent with GetShowExpand() and SetShowExpand() methods. The ShowExpand property can be one of the following values:
  • false {boolean}, the item hides its expand/collapse glyphs (no indentation is applied)
  • true {boolean}, the item shows its expand/collapse glyphs (indentation is applied)
  • -1 {number}, the item shows no expand/collapse glyphs, instead indentation is applied
By default, the ShowExpand property is null, which indicates that the expand/collapse glyphs are shown for items that have children, otherwise the expand/collapse glyphs are hidden.
Type:
  • boolean | number
Example
false {boolean}, the item hides its expand/collapse glyphs (no indentation is applied)
true {boolean}, the item shows its expand/collapse glyphs (indentation is applied)
-1 {number}, the item shows no expand/collapse glyphs, instead indentation is applied
ShowExpand

Sortable :boolean

The Sortable property defines whether the item is sortable. A sortable item can change its position after sorting, while an unsortable item keeps its position after sorting. The Position property specifies the item's position within the collection of items.
Type:
  • boolean
Example
false {boolean}, the item is unsortable (an unsortable item keeps its position after user performs a sort operation)
true {boolean}, the item is sortable
Sortable

Value :null|any|Array.<any>

The Value property gets or the value for each cell of the item. The SetValue() method changes the value for each cell of the item. The GetValue() method returns the values for each cell of the item, as an array of [any] type. The Value property is equivalent with GetValue() and SetValue() methods. 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 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.
Type:
  • null | any | Array.<any>
Since:
  • 1.1
Example
null {null}, resets the caption for all cells of the item
"caption" {string}, defines the plain-caption for all cells of the item
["&lt;img&gt;al&lt;/img&gt;Alexa","&lt;img&gt;dtop&lt;/img&gt;Darius"] {string[]}, specifies the captions for the first two-cells (includes images too, The image can be added using the exontrol.HTMLPicture.Add method)
Value

Visible :boolean

The Visible property shows or hides the item. The Visible property is equivalent with GetVisible()/SetVisible(value) methods. The Height property gets or sets the item's height. By default, the item is visible. A hidden item is not displayed within the control, and it does not take part in layout and interaction (selection, hover, etc.). The child-items of a hidden item are also hidden regardless of their own Visible property value. The Visible property is used when you need to hide an item temporarily, without removing it from the control. If you need to remove an item from the control, use the Remove() method instead.
Type:
  • boolean
Example
false {boolean}, hides the item
true {boolean}, shows the item
Visible

Methods

Add(oOptionsopt) → {Item}

The Add() method creates and adds a new child-item into the control. The Add() method accepts an object of ItemOptions type as parameter, to define the new item. The Add() method returns the newly created item as an object of Item type. The onadditem event is raised when a new item is added into the control. The Items.Add() method creates and adds a new root-item into the control.
Parameters:
Name Type Attributes Description
oOptions object <optional>
 Specifies the options to create the new item as an object of ItemOptions type.
Returns:
Returns the newly created item, as an object of Item type
Type
Item
Example
oPivot.Item(0).Add("caption"), adds a new child-item of the first item, and sets the caption for the first cell.
oPivot.Item(0).Add({value: "caption"}), adds a new child-item of the first item, and sets the caption for the first cell.
oPivot.Item(0).Add(["Cell 1","Cell 2"]), adds a new child-item of the first item, and sets the caption for the first and second cell.
oPivot.Item(0).Add({value: ["Cell 1","Cell 2"]}), adds a new child-item of the first item, and sets the caption for the first and second cell.
Add

Cell(column) → {Cell}

The Cell() method gets the item's cell giving the column's index, identifier/key/caption or reference. The Cell() method is equivalent with the Pivot.Cell(item,column) method of control. The Cell.Value property gets or the value for each cell of the item. The Cell.Caption property gets the caption for each cell of the item. The Cell.Shape property gets or sets the shape for each cell of the item. The Cell.Cursor property gets or sets the mouse cursor for each cell of the item. The Cell() method returns null if the column is not found, or an object of Cell type that specifies the requested cell.
Parameters:
Name Type Description
column any The id parameter could be any of the following:
  • column {number}, indicates a numeric value that defines the index of the column to request
  • column {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • column {Column}, specifies the object reference to the column to request for
Returns:
Returns null if the column is not found, or an object of Cell type that specifies the requested cell
Type
Cell

Child(index) → {Item}

The Child() method gets the child item at the specified index within the item's children collection. The Item.Add metod adds a child item to the item, while the Item.Remove method removes a child item from the item. The Child and ChildCount members allow you to enumerate the child items of the item. The Child() method supports negative indexes as well, where -1 indicates the last added child item, -2 the second last, and so on. If the specified index is out of bounds, the Child() method returns null.
Parameters:
Name Type Description
index number Specifies the zero-based index of the child item to retrieve (supports negative indexes as well, where -1 indicates the last added child item, -2 the second last, and so on).
Since:
  • 5.1
Returns:
Returns the child item at the specified index, or null if the index is out of bounds.
Type
Item
Example
The following code snippet:

   for ( var i = 0; i &lt; oItem.GetChildCount(); i++ )
     console.log( oItem.Child(i) );

 enumerates all child-items of oItem
Child

Remove()

The Remove() method removes the item itself from the items collection. The Remove() method is equivalent with Items.Remove(oItem) method, where oItem is the item to remove. The Remove() method accepts the same parameters as the Item() method to locate the item to remove. The RemoveSelection method removes all selected items at once. The onremoveitem event is raised for each item being removed, and the onremoveitem event is raised once after all items are removed.

ToggleExpand()

The ToggleExpand() method toggles the item's expand state. For instance, if the item is expanded, the ToggleExpand() method collapses the item. The Expanded property expands or collapses the item. The onchange("expand-item") event is raised when the item is expanded or collapsed (only by user interaction, not by API calls). The ExpandAll() method expands or collapses all items based on the giving parameter (true to expand, false to collapse).
Example
oPivot.Item(0).ToggleExpand(), toggles the expand state of the first item. If the first item is expanded, it will be collapsed, and if it is collapsed, it will be expanded.
ToggleExpand