new Items(oPivot)
The Items object holds a collection of Item type (item of the control). The item is the core of the control, as it represents the data and the hierarchy of the control. The item provides a large set of methods and properties to manipulate its content, appearance and behavior. The items collection provides methods to add, remove, clear, get and count items within the control. Use the Pivot.Items method to access the control's items collection. The Add, Remove, Clear, Item and Count methods of the items collection are the most commonly used methods to manipulate the control's content. The items collection provides also other methods to get the visible-items, the items that match the filter, the leaf-items, etc. The items collection is also used by the control to maintain the list of items within the control, so any change into this collection affects directly to the control's content and layout. The Item.Add method adds a new item as a child of the current item, while the Items.Add method adds a new item as a root-item (item with no parent-item). The HasChildren method checks whether the control contains any child-item (list or tree).
Parameters:
| Name | Type | Description |
|---|---|---|
oPivot |
Pivot | Indicates an object of Pivot type that owns the collection. |
Members
(readonly) Count :number
The Count property returns the number of items within the collection. The VisibleCount/GetVisibleCount() {number}, returns the number of visible-items. The LeafCount/GetLeafCount() {number}, counts the leaf-items (a leaf item is an item with no child items). The MatchCount/GetMatchCount() {number}, returns the number of items that match the filter. The FitCount/GetFitCount() method gets the number of items that fit within the control's client-area. The Count property is equivalent to the GetCount() method.
Type:
- number
Example
The following statements are equivalents:
oPivot.Items.GetCount(), counts the items within the control
oPivot.Items.Count, counts the items within the control
where oPivot is an object of Pivot type(readonly) FitCount :number
The FitCount property gets the number of items that fit within the control's client-area. An item that fits within the control's client-area is a visible-item that is fully or partially visible within the control's client-area. The Count property returns the number of items within the collection. The VisibleCount/GetVisibleCount() {number}, returns the number of visible-items. The LeafCount/GetLeafCount() {number}, counts the leaf-items (a leaf item is an item with no child items). The MatchCount/GetMatchCount() {number}, returns the number of items that match the filter. The FitCount property is equivalent to the GetFitCount() method.
Type:
- number
- Since:
- 5.1
Example
The following statements are equivalents:
oPivot.Items.GetFitCount(), counts the items that fit within the control's default view area
oPivot.Items.FitCount, counts the items that fit within the control's default view area
oPivot.Items.GetFitCount(), gets the number of items that fit within the control's client-area
where oPivot is an object of Pivot type(readonly) HasChildren :boolean
The HasChildren property checks whether the control contains any child-item (list or tree). The property enumerates the items within the control until it finds an item with child-item ( list or tree ), then it returns true; otherwise, if no item with child-item is found, it returns false. The GetHasChildren() method checks whether the control contains any child-item (list or tree). The HasChildren property is equivalent to the GetHasChildren() method. The Item.Add method automatically adds a child-item to the control, so after adding an item using the Item.Add method, the HasChildren property returns true.
Type:
- boolean
Example
if ( oPivot.Items.HasChildren ) { ... }, checks whether the control contains any child-item (list or tree)
where oPivot is an object of Pivot type(readonly) LeafCount :number
The LeafCount property counts the leaf-items. A leaf item is an item with no child items. The Count property returns the number of items within the collection. The VisibleCount/GetVisibleCount() {number}, returns the number of visible-items. The MatchCount/GetMatchCount() {number}, returns the number of items that match the filter. The FitCount/GetFitCount() method gets the number of items that fit within the control's client-area. The LeafCount property is equivalent to the GetLeafCount() method.
Type:
- number
Example
The following statements are equivalents:
oPivot.Items.GetLeafCount(), counts the leaf-items
oPivot.Items.LeafCount, counts the leaf-items
where oPivot is an object of Pivot type(readonly) MatchCount :number
The MatchCount property returns the number of items that match the filter as explained below:
- 0, the control displays/contains no items, and no filter is applied to any column
- -1, the control displays no items, and there is a filter applied ( no match found )
- positive number, indicates the number of items within the control (Count property)
- negative number, the absolute value minus 1, indicates the number of items that matches the current filter ( match found )
Type:
- number
Example
The following statements are equivalents:
oPivot.Items.GetMatchCount(), counts the items that match the filter
oPivot.Items.MatchCount, counts the items that match the filter
where oPivot is an object of Pivot type(readonly) VisibleCount :number
The VisibleCount property returns the number of visible-items, as explained below:
- 0, the control displays/contains no items, and no filter is applied to any column
- -1, the control displays no items, and there is a filter applied ( no match found )
- positive number, indicates the number of visible items, and the control has no filter applied to any column
- negative number, the absolute value minus 1, indicates the number of visible items, and there is a filter applied (match found)
Type:
- number
Example
The following statements are equivalents:
oPivot.Items.GetVisibleCount(), counts the visible items within the control
oPivot.Items.VisibleCount, counts the visible items within the control
where oPivot is an object of Pivot typeMethods
Add(oItemOptsopt) → {Item|number}
The Add() method creates and adds a new item into the control. Use the Item.Add() method to a new child-item into the control. The Add() method accepts either a value or an object of options to create the new item. If the oItemOpts parameter is a value, it is assigned to the first cell of the new item; otherwise, if oItemOpts is an object, the value field of this object is assigned to the first cell of the new item, and other options are applied to the new item as well (for instance, the height option defines the height of the new item). The Add() method returns the newly created item as an object of Item type. The onadditem event is raised once the new item is created and added into the control, so you can use this event to perform any additional operation on the newly created item.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
oItemOpts |
string | object |
<optional> |
Specifies the options to create the new item as an object of ItemOptions type. The value field of the oItemOpts parameter can be of the CellOptions type to define the options (including the value) to apply to the cell (@since 3.2). |
Returns:
Returns the newly created item, as an object of Item type
- Type
- Item | number
Example
oPivot.Items.Add("caption"), adds a new item, and sets the caption for the first cell.
oPivot.Items.Add({value: "caption"}), adds a new item, and sets the caption for the first cell.
oPivot.Items.Add({value: "caption", shape: "lime"}), adds a new item of lime color and sets the caption for the first cell.
oPivot.Items.Add({value: {value: "caption", shape: {tfi: "bold cursive 20"}}, height: 44}), adds a new item of 44px tall, sets the caption and font-attributes for the first cell (@since 3.2)
oPivot.Items.Add(["Cell 1","Cell 2"]), adds a new item, and sets the caption for the first and second cell.
oPivot.Items.Add({value: ["Cell 1","Cell 2"]}), adds a new item, and sets the caption for the first and second cell.
oPivot.EnsureVisibleClient(oPivot.Items.Add("caption")), adds a new item, sets the caption for the first cell, and scrolls the control to ensure that the newly item fits the control's client areaClear()
The Clear() method removes all items of the control and inits the control's scroll-bars. The onremoveitem event is raised for each item being removed. The onremoveitem event is raised once after all items are removed. 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 Pivot.Clear() method clears the control's data (columns, items and filter). The ClearFilter() method is called within the Clear() method to remove the control's filter as well. The Columns.Clear method is used to clear all the columns and items of the control.
Example
oPivot.Items.Clear(), removes all items of the control and inits the control's scroll-barsFitItem(position) → {Item}
The FitItem() method gets the item that fits the view at the specified position. An item fits the control's view if it is visible, either fully or partially. The FitCount property gets the number of items that fit within the control's client-area. The VisibleItem() method gets the visible-item at specified position (for instance, a child of a collapsed item is not visible, an item that does not match the filter is not visible, etc.). The FitItem() method is similar to the VisibleItem() method, but it returns only the items that fit within the control's client-area. For instance, if the control displays 100 visible-items but only 10 items fit within the control's client-area, then the FitItem() method returns only these 10 items while the VisibleItem() method returns all 100 visible-items. The onscroll event is raised when the control is scrolled, so you can use this event to get the items that fit within the control's client-area after each scroll operation. For instance, the FitItem(0) returns the first item that fits within the control's client-area, while the FitItem(-1) returns the last item that fits within the control's client-area.
Parameters:
| Name | Type | Description |
|---|---|---|
position |
number | Specifies the position of the item to get (0-based index). The position can be negative to indicate the position from the end of the items that fit within the control's client-area as follows:
|
- Since:
- 5.1
Returns:
Returns the item that fits at specified position, as an object of Item type
- Type
- Item
Example
The following code snippet enumerates all items that fit within the control's client-area:
for (var i = 0, l = oPivot.Items.FitCount; i < l; i++)
console.log(i, oPivot.Items.FitItem(i));
oPivot.Items.FitItem(0), gets the first item that fits within the control's client-area
oPivot.Items.FitItem(-1), gets the last item that fits within the control's client-area
where oPivot is an object of Pivot typeItem(id) → {null|Item}
The Item() method gets the item giving its index, identifier/key or reference. The Pivot.Item(id) method returns the item based on its index or identifier/key (equivalent of this method). The feI and feIU methods (short for forEachItem, forEachItemUntil) enumerates the items of the control.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
any | The id parameter could be any of the following:
|
Returns:
Returns null if the item is not found, or an object of Item type, if the items collection contains the giving id.
- Type
- null | Item
Example
oPivot.Items.Item(0) {Item}, gets the first item of the control
oPivot.Items.Item("itemId") {Item}, gets the item with "itemId" as an identifier/keyRemove(id)
The Remove() method removes an item from the collection. The RemoveRange() method removes multiple-items at once. The Clear() method removes all items of the control and inits the control's scroll-bars. The onremoveitem event is raised for each item being removed, and the onremoveitem event is raised once after all items are removed. 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.
Parameters:
| Name | Type | Description |
|---|---|---|
id |
any | The id parameter could be any of the following:
|
Example
oPivot.Items.Remove(0), removes the first item of the controlRemoveRange(range) → {number}
The RemoveRange() method removes multiple-items at once. The Remove() method removes an item from the collection. The Clear() method removes all items of the control and inits the control's scroll-bars. The onremoveitem event is raised for each item being removed, and the onremoveitem event is raised once after all items are removed. 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.
Parameters:
| Name | Type | Description |
|---|---|---|
range |
any | Indicates an item, an array [{Item}], or an exontrol.Arr([{Item}]). |
Returns:
Returns the number of items being deleted
- Type
- number
Example
oPivot.Items.RemoveRange([0,1,2]), removes the first three items of the controlVisibleItem(position) → {Item}
The VisibleItem() method gets the visible-item at specified position (for instance, a child of a collapsed item is not visible, an item that does not match the filter is not visible, etc.). The VisibleCount/GetVisibleCount() method returns the number of visible-items. The MatchCount/GetMatchCount() method returns the number of items that match the filter. The LeafCount/GetLeafCount() method counts the leaf-items (a leaf item is an item with no child items). The FitCount/GetFitCount() method gets the number of items that fit within the control's client-area. The VisibleItem() method is used to get the visible-items based on their position within the visible-items list, so for instance, a child of a collapsed item is not visible, an item that does not match the filter is not visible, etc.
Parameters:
| Name | Type | Description |
|---|---|---|
position |
number | Specifies the position of the visible-item to get (0-based index). The position can be negative to indicate the position from the end of the visible-items list as follows:
|
- Since:
- 5.1
Returns:
Returns the visible-item at specified position, as an object of Item type
- Type
- Item
Example
oPivot.Items.VisibleItem(0) {Item}, gets the first visible-item within the control
oPivot.Items.VisibleItem(-1) {Item}, gets the last visible-item within the control
The following code snippet enumerates all visible-items within the control:
for ( var i = 0, l = oPivot.Items.VisibleCount < 0 ? -(oPivot.Items.VisibleCount + 1) : oPivot.Items.VisibleCount; i < l; i++ )
console.log( oPivot.Items.VisibleItem(i) );
where oPivot is an object of Pivot type