Items class (Gantt)

Items(oTree)

new Items(oTree)

The Items object holds a collection of Item type (item of the control). The Items type defines additional properties and methods of the Items(extree) type. The Items property returns the control's items collection. 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 Tree.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
oTree Tree Indicates an object of Tree 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:

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

where oGantt is an object of Gantt type
Count

DefSchedulePDM :DefSchedulePDM

The DefSchedulePDM property gets or sets the options for the SchedulePDM() method. The Items.SchedulePDM() method arranges the activities in the plan according to their links, relationships, or dependencies. The AddBar method of the Item type adds a bar to the current item and returns an ItemBar object. The Bars property defines the bars of the current item as an exontrol.Gantt.ItemBars object. The Links.Add() method creates a link between two bars and returns a Link object that represents the newly created link. The options for the SchedulePDM() method are defined as an object of DefSchedulePDM type, which can include various fields such as scheduleType, scheduleDate, etc., to control the behavior of the scheduling process.
Type:
Example
{scheduleType: 1, scheduleDate: "#1/1/2021#" } {object}, defines the options for SchedulePDM() method so it alwasys starts at #1/1/2021#
DefSchedulePDM

(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:

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

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

(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 ( oGantt.Items.HasChildren ) { ... }, checks whether the control contains any child-item (list or tree)

where oGantt is an object of Gantt type
HasChildren

(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:

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

where oGantt is an object of Gantt type
LeafCount

(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 )
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 FitCount/GetFitCount() method gets the number of items that fit within the control's client-area. The MatchCount property is equivalent to the GetMatchCount() method.
Type:
  • number
Example
The following statements are equivalents:

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

where oGantt is an object of Gantt type
MatchCount

(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)
The Count property returns the number of items within the collection. 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 VisibleCount property is equivalent to the GetVisibleCount() method.
Type:
  • number
Example
The following statements are equivalents:

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

where oGantt is an object of Gantt type
VisibleCount

Methods

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
oGantt.Items.Add("caption"), adds a new item, and sets the caption for the first cell.
oGantt.Items.Add({value: "caption"}), adds a new item, and sets the caption for the first cell.
oGantt.Items.Add({value: "caption", shape: "lime"}), adds a new item of lime color and sets the caption for the first cell.
oGantt.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)
oGantt.Items.Add(["Cell 1","Cell 2"]), adds a new item, and sets the caption for the first and second cell.
oGantt.Items.Add({value: ["Cell 1","Cell 2"]}), adds a new item, and sets the caption for the first and second cell.
oGantt.EnsureVisibleClient(oGantt.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. 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 Gantt.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
oGantt.Items.Clear(), 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. 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:
  • 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 = oGantt.Items.FitCount; i &lt; l; i++)
     console.log(i, oGantt.Items.FitItem(i));

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

GroupBars(itemBarA, startAopt, itemBarBopt, startBopt, groupBarsOptionsopt, optionsopt)

The GroupBars() method groups two bars, allowing you to associate a starting or ending point of one bar with any starting or ending point of another bar. For example, to move both bars together, you need to group the starting point of bar A with the starting point of bar B, and the ending point of bar A with the ending point of bar B. Use the GroupBars method to manage or control the distance between two bars. When bars are grouped, resizing or moving one bar in the group will resize or move the other bars in the group accordingly. Similarly, all related groups will also be adjusted when one group is resized or moved. You can group bars from different items. The GroupBars method can preserve the length of the bars, restrict the interval between bars, and perform other adjustments when changes occur in the group. The length of the bar and the interval between two bars are defined as follows:
  • length, the length of the bar is equivalent to its duration, which is the difference between the bar's ending date and its starting date
  • interval, The interval is the distance between the starting and ending points of the grouped bars. For example:
    • If the end of bar A is linked with the start of bar B, the interval is the difference between the starting date of bar B and the ending date of bar A
    • If the start of bar A is linked with the start of bar B, the interval is the difference between the starting date of bar A and the starting date of bar B
You can use the UngroupBars method to ungroup two or more item-bars. The GroupBars() method must provide 1, 4, or more arguments; otherwise, it has no effect. If the GroupBars() method provides a single argument, it can be an array of [ItemBar] type that holds all item-bars to group together.
Parameters:
Name Type Attributes Description
itemBarA ItemBar | Array.<ItemBar> Indicates the item-bar to group with itemBarB, or a collection of ItemBar objects to group together (links the starts and ends of the bars so they move together as a block).
startA boolean <optional>
 Indicates whether the start(true) or end(false) margin of the item bar, are grouped with other bars.
itemBarB ItemBar <optional>
 Indicates the item-bar to group to.
startB boolean <optional>
 Indicates whether the start(true) or end(false) margin of the item bar, are grouped with other bars.
groupBarsOptions GroupBarsOptionsEnum <optional>
 Specifies one or more GroupBarsOptionsEnum values that determine how the bars are grouped. If the GroupBarsOptions is exGroupBarsNone the bars are ungrouped. For example, the exPreserveBarLength + exFlexibleInterval specifies that the bars preserves their lengths, and the bar B can be moved anywhere to the right of the bar A.
options string <optional>
 Specifies a string of numbers separated by semicolons that define the spacing between bars:
  • Fixed interval, the default distance between bars
  • Maximum increase, how much the interval can grow
  • Minimum decrease, how much the interval can shrink

For example, "2;4" sets a fixed interval of 2 days, with a maximum of 6 days (2 + 4)

Apply these limits by setting the GroupBarsOptions parameter to exLimitIntervalMin, exLimitIntervalMax, exLimitInterval, or exFlexibleInterval flags.
Since:
  • 3.3
Example
In the following samples, A and B represent two item-bars, such as oGantt.ItemBar(0), oGantt.ItemBar(1), etc.

 GroupBars(oGantt.Chart.Selection), groups the all selected item-bars (links the starts and ends of the bars so they move and resize together as a block) (block)
 GroupBars([A, B]), groups the end of item-bar A with the end of item-bar B, and the start of item-bar A with the start of item-bar B (Links the starts and ends of the bars so they move and resize together as a block) (block)
   equivalent of:
     GroupBars(A, false, B, false);
     GroupBars(A, true, B, true);
 GroupBars(A, false, B, true, exontrol.Gantt.GroupBarsOptionsEnum.exPreserveBarLength | exontrol.Gantt.GroupBarsOptionsEnum.exIgnoreOriginalInterval, "2"), preserves both bars' lengths, ignores original interval, sets exact distance of 2 days between bars (fixed)
 GroupBars(A, false, B, true, exontrol.Gantt.GroupBarsOptionsEnum.exPreserveBarLength | exontrol.Gantt.GroupBarsOptionsEnum.exIgnoreOriginalInterval | exontrol.Gantt.GroupBarsOptionsEnum.exLimitIntervalMin, "2"), preserves both bars' lengths, ignores original interval, bars must be at least 2 days apart (minimum interval)
 GroupBars(A, false, B, true, exontrol.Gantt.GroupBarsOptionsEnum.exPreserveBarLength | exontrol.Gantt.GroupBarsOptionsEnum.exIgnoreOriginalInterval | exontrol.Gantt.GroupBarsOptionsEnum.exLimitInterval, "0;2"), preserves both bars' lengths, ignores original interval, bars can be at most 2 days apart (maximum interval) 
 GroupBars(A, false, B, true, exontrol.Gantt.GroupBarsOptionsEnum.exPreserveBarLength | exontrol.Gantt.GroupBarsOptionsEnum.exIgnoreOriginalInterval | exontrol.Gantt.GroupBarsOptionsEnum.exLimitInterval, "1;6"), preserves both bars' lengths, ignores original interval, bars must be between 1 and 7 days apart (interval)
GroupBars

Item(id) → {null|Item}

The Item() method gets the item giving its index, identifier/key or reference. The Gantt.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:
  • 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
Example
oGantt.Items.Item(0) {Item}, gets the first item of the control
oGantt.Items.Item("itemId") {Item}, gets the item with "itemId" as an identifier/key
Item

Remove(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:
  • 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
Example
oGantt.Items.Remove(0), removes the first item of the control
Remove

RemoveRange(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
oGantt.Items.RemoveRange([0,1,2]), removes the first three items of the control
RemoveRange

SchedulePDM(item, key) → {number}

The SchedulePDM() method arranges the activities on the plan based on the links / relationships / dependencies. The method accepts as parameters the item and the key of the bar to start the scheduling from. The item parameter can be specified in various forms, such as null, number, string, object reference of the item or the bar. The key parameter is used to identify the bar to start from when the item hosts multiple bars, while it is optional if the item hosts a single bar. The SchedulePDM() method returns 0 if successful, a negative number if any error occurs, or a positive number as warnings. The SchedulePDM() method can return various warnings and errors based on different scenarios during the scheduling process. The DefSchedulePDM property defines the options for the SchedulePDM() method, as an object of DefSchedulePDM type. The AddBar method of the Item type adds a bar to the current item and returns an ItemBar object. The Bars property defines the bars of the current item as an exontrol.Gantt.ItemBars object. The Links.Add() method creates a link between two bars and returns a Link object that represents the newly created link.
Parameters:
Name Type Description
item any The item parameter could be any of the following:
  • item {null} or {undefined}, the key parameter indicates the unique key of the bar where SchedulePDM begins
  • item {number}, indicates a numeric value that defines the index of the item the SchedulePDM begins from
  • item {string}, specifies a string expression that defines the identifier/key of the item the SchedulePDM begins from
  • item {exontrol.Tree.Item}, specifies the object reference of the item where SchedulePDM begins
  • item {ItemBar}, specifies the bar where SchedulePDM begins (key parameter is ignored)
key any Specifies the key of the bar the SchedulePDM begins from (not required if item points to an object of ItemBar type), as one of the following:
  • key {null} or {undefined}, specifies the first item-bar within the item (defaults to 0)
  • key {number}, indicates a numeric value that defines the index of the bar to request
  • key {string}, specifies a string expression that defines the key of the bar to request
Returns:
Returns 0 if successful, negative number if any error, or positive as warnings. The SchedulePDM() method can return any of the following:
  • 0 {number}, success
  • 1 {number}, (warning) no bar provided to SchedulePDM method
  • 2 {number}, (warning) single bar in SchedulePDM call
  • 3 {number}, (warning) SchedulePDM method is called during the BarResize event (possible a recursive call/stack overflow)
  • 4 {number}, (warning) no links between scheduled bars
  • -1 {number}, (error) possible cycling
  • -2 {number}, (error) can not move the base bar
  • -3 {number}, (error) scheduling the A and B bars fails
  • -4 {number}, (error) no IN bars
  • -5 {number}, (error) base bar is not initialized
  • -6 {number}, (error) source bar is not initialized (possible cycling)
  • -7 {number}, (error) target bar is not initialized (possible cycling)
  • -8 {number}, (error) no TRANSLATION bar
  • -9 {number}, (error) bar linked to itself. For instance, a bar linked to its summary bar
Type
number
Example
oGantt.Items.SchedulePDM(), schedules the plan starting from the first bar of the first item of the chart
 oGantt.Items.SchedulePDM(1, "T"), schedules the plan starting from the "T" bar of the second item of the chart
SchedulePDM

UngroupBars(itemBarAopt, itemBarBopt)

The UngroupBars() method ungroups two or more item-bars. Use this method to ungroup bars that were previously grouped using the GroupBars method. If the itemBarA and itemBarB parameters are not specified or are missing, the UngroupBars() method will ungroup all item bars in the control. If only itemBarA is specified, the method will ungroup all item bars related to itemBarA. Similarly, if only itemBarB is specified, it will ungroup all item bars related to itemBarB.
Parameters:
Name Type Attributes Description
itemBarA ItemBar | Array.<ItemBar> <optional>
 Specifies the first or multiple item-bars to ungroup.
itemBarB ItemBar <optional>
 Specifies the second item-bar to ungroup by.
Since:
  • 3.3
Example
UngroupBars(), ungroups all item-bars of the control
 UngroupBars(oGantt.Chart.Selection), ungroups all selected item-bars
UngroupBars

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.). 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:
  • 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
oGantt.Items.VisibleItem(0) {Item}, gets the first visible-item within the control
 oGantt.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 = oGantt.Items.VisibleCount &lt; 0 ? -(oGantt.Items.VisibleCount + 1) : oGantt.Items.VisibleCount; i &lt; l; i++ )
     console.log( oGantt.Items.VisibleItem(i) );

 where oGantt is an object of Gantt type
VisibleItem