Items class (Tree)

Items(oTree)

new Items(oTree)

The Items object holds a collection of Item type (item of the control). Use the Items/GetItems() method to access the control's items collection.
Parameters:
Name Type Description
oTree Tree Indicates an object of Tree type that owns the collection
Items

Methods

Add(oItemOptsopt) → {Item}

The Add() method creates and adds a new item into the control. Use the Add() method of the Item object to a new child-item into the control.
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
Example
oTree.Items.Add("caption"), adds a new item, and sets the caption for the first cell.
 oTree.Items.Add({value: "caption"}), adds a new item, and sets the caption for the first cell.
 oTree.Items.Add({value: "caption", shape: "lime"}), adds a new item of lime color and sets the caption for the first cell.
 oTree.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)
 oTree.Items.Add(["Cell 1","Cell 2"]), adds a new item, and sets the caption for the first and second cell.
 oTree.Items.Add({value: ["Cell 1","Cell 2"]}), adds a new item, and sets the caption for the first and second cell.
 oTree.EnsureVisibleClient(oTree.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 area
Add

Clear()

The Clear() method removes all items of the control and inits the control's scroll-bars
Clear

FitItem(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.
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:
  • 0 indicates the first item that fits within the control's client-area
  • 1 indicates the second item that fits within the control's client-area
  • 2 indicates the third item that fits within the control's client-area
  • ...
  • -2 indicates the penultimate item that fits within the control's client-area
  • -1 indicates the last item that fits within the control's client-area
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 = oTree.Items.FitCount; i < l; i++)
     console.log(i, oTree.Items.FitItem(i));

 oTree.Items.FitItem(0), gets the first item that fits within the control's client-area
 oTree.Items.FitItem(-1), gets the last item that fits within the control's client-area
 
where oTree is an object of Tree type
FitItem

GetCount() → {number}

The GetCount() method returns the number of items within the collection
Returns:
Returns the number of items within the collection
Type
number
Example
The following statements are equivalents:

 oTree.Items.GetCount(), counts the items within the control
 oTree.Items.Count, counts the items within the control

where oTree is an object of Tree type
GetCount

GetFitCount() → {number}

The GetFitCount() method 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.
Since:
  • 5.1
Returns:
Returns the number of items that fit within the control's client-area
Type
number
Example
The following statements are equivalents:

 oTree.Items.GetFitCount(), counts the items that fit within the control's default view area
 oTree.Items.FitCount, counts the items that fit within the control's default view area

 oTree.Items.GetFitCount(), gets the number of items that fit within the control's client-area
 
where oTree is an object of Tree type
GetFitCount

GetLeafCount() → {number}

The GetLeafCount() method counts the leaf-items. A leaf item is an item with no child items.
Returns:
Returns the count of leaf-items.
Type
number
Example
The following statements are equivalents:

 oTree.Items.GetLeafCount(), counts the leaf-items
 oTree.Items.LeafCount, counts the leaf-items

where oTree is an object of Tree type
GetLeafCount

GetMatchCount() → {number}

The GetMatchCount() method returns the number of items that match the filter
Returns:
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:

 oTree.Items.GetMatchCount(), counts the items that match the filter
 oTree.Items.MatchCount, counts the items that match the filter

where oTree is an object of Tree type
GetMatchCount

GetVisibleCount() → {number}

The GetVisibleCount() method returns the number of visible-items (not always returns a positive number, see below)
Returns:
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:

 oTree.Items.GetVisibleCount(), counts the visible items within the control
 oTree.Items.VisibleCount, counts the visible items within the control

where oTree is an object of Tree type
GetVisibleCount

Item(id) → {null|Item}

The Item() method gets the item giving its index, identifier/key or reference. The Item(id) method returns the item based on its index or identifier/key (equivalent of this method)
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the item to request. If the index is negative, the item is counted from the end of the collection (for instance, -1 indicates the last item, @since 5.1)
  • id {string}, specifies a string expression that defines the identifier/key of the item to request
  • id {Item}, specifies the object reference to the item to request for
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
Item

Remove(id)

The Remove() method removes an item from the collection.
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the item to request
  • id {string}, specifies a string expression that defines the identifier/key of the item to request
  • id {Item}, specifies the object reference to the item to request for
Remove

RemoveRange(range) → {number}

The RemoveRange() method removes multiple-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
RemoveRange

VisibleItem(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.)
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:
  • 0 indicates the first visible-item
  • 1 indicates the second visible-item
  • 2 indicates the third visible-item
  • ...
  • -2 indicates the penultimate visible-item
  • -1 indicates the last visible-item
Since:
  • 5.1
Returns:
Returns the visible-item at specified position, as an object of Item type
Type
Item
Example
oTree.Items.VisibleItem(0) {Item}, gets the first visible-item within the control
 oTree.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 = oTree.Items.VisibleCount < 0 ? -(oTree.Items.VisibleCount + 1) : oTree.Items.VisibleCount; i < l; i++ )
     console.log( oTree.Items.VisibleItem(i) );

 where oTree is an object of Tree type
VisibleItem