Items.GroupBars Method (ExG2antt)

The GroupBars method groups two bars. In other words, you can associate a starting/ending point of one bar with any other starting/ending point of the bar. For instance, if you want to move both together you need to group the starting point of bar A with starting point of bar B, and ending point of the bar A with ending point of the bar B. Use the GroupBars method to handle or control the distance between 2 bars. For instance, if two bars or more bars are grouped, when a bar in the group is resize or moved, the other bars in the group are resized or moved accordingly. In the same manner, all other groups that are related with one of the group being resized or moved, are changed as well. You can group bars from different items. The GroupBars method may preserve the length of the bars, restrict the interval between bars, and so on when a change occurs in the group. Use the Link(exLinkGroupBars) to group two linked bars. For instance, the .Link(LinkKey, exLinkGroupBars) = GroupBarsOptionsEnum.exPreserveBarLength + GroupBarsOptionsEnum.exFlexibleInterval + GroupBarsOptionsEnum.exIgnoreOriginalInterval is equivalent with .GroupBars .Link(LinkKey, exLinkStartItem), .Link(LinkKey, exLinkStartBar), False, .Link(LinkKey, exLinkEndItem), .Link(LinkKey, exLinkEndBar), True, GroupBarsOptionsEnum.exPreserveBarLength + GroupBarsOptionsEnum.exFlexibleInterval + GroupBarsOptionsEnum.exIgnoreOriginalInterval.

The length of the bar and interval between two bars are defined as follows:

The length of the bar is the same as its duration, in other words it is the difference between ending date of the bar and starting date of the bar.
The interval between bars is the same as the distance between the starting and ending points of the grouping bars. For instance, if you have linked the end of the bar A with the start of the bar B, the interval is defined as difference between the starting date of the bar B and ending date of the bar A. In other sample, you may have linked the start of the bar A with start of the bar B, in this case the interval is defined as being the difference between the start of the bar A and starting date of the bar B, nothing else.

If using the NonworkingDays property, the ItemBar(exBarKeepWorkingCount) property indicates whether the working units of the bar is keep constant while moving/grouping. If the GroupBarsOptions parameter includes the exLimitIntervalTreatAsWorking the interval between bars is indicating the working days between days.

Samples:

GroupBars(h1,"",False, h2, "", True, 7,"2") ' exPreserveBarLength + exIgnoreOriginalInterval, the distance between 2 bars is exactly 2 days.
GroupBars(h1,"",False, h2, "", True, 95,"2") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitInterval + exLimitIntervalTreatAsWorking, the distance between 2 bars is exactly 2 working days.
GroupBars(h1,"",False, h2, "", True, 15,"2") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitIntervalMin, the distance between 2 bars can be 2 days or more.
GroupBars(h1,"",False, h2, "", True, 79,"2") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitIntervalMin + exLimitIntervalTreatAsWorking, the distance between 2 bars can be 2 working days or more.
GroupBars(h1,"",False, h2, "", True, 31,"0;0;2") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitInterval, the distance between 2 bars can be 2 days or less.
GroupBars(h1,"",False, h2, "", True, 95,"0;0;2") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitInterval + exLimitIntervalTreatAsWorking, the distance between 2 bars can be 2 working days or less.
GroupBars(h1,"",False, h2, "", True, 31,"0;1;7") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitInterval, the distance between 2 bars can be between 1 and 7 days.
GroupBars(h1,"",False, h2, "", True, 95,"0;1;5") ' exPreserveBarLength + exIgnoreOriginalInterval + exLimitInterval + exLimitIntervalTreatAsWorking, the distance between 2 bars can be between 1 and 7 working days.

Use the AddLink method to add or draw a link between two bars. Use the DefineSummaryBars method to define bars in a summary bar, so it gets updated as soon as the child bars are moved or resized. Use the UngroupBars method to ungroup two bars or all bars. The Items.ItemBar(exBarsGroup) property retrieves a collection of item,key that defines the bars begin grouped with specified bar.

The following screen shots show the changes in a group of 3 bars ( 1, 2 and 3 ), when the bar 2 ( the arrow ) is moved from Sep 26 to Sep 29, using different options for GroupBarsOptions and Options parameters. Click on the picture and view the XML file that was used to generate the picture. The Groups section stores the groups of bars. You can use the LoadXML method to load the chart from these XML files. The XML file does not load EBN files!

The following screen shot shows the chart before performing any change.

The following screen shot shows the chart after moving the bar 2, when the GroupBarsOptions and Options parameters are missing ( by default ). You can notice that the bar 1 and 3 are resized.

The following screen shot shows the chart after moving the bar 2, when the GroupBarsOptions parameter is exPreserveBarLength. You can notice that all bars are moved to preserve their lengths.

The following screen shot shows the chart after moving the bar 2, when the GroupBarsOptions parameter is exPreserveBarLength + exFlexibleInterval. All bars in the group preserves their lengths, and the bar 2 can be moved anywhere to the right of the bar 1

The following screen shot shows the chart after moving the bar 2, when the GroupBarsOptions parameter is exPreserveBarLength + exIgnoreOriginalInterval + exLimitInterval, and the Options parameter is "0;1", which means the interval between two bars may be between 0 and 1, with a starting fixed interval being 0.

By default, when grouping, the distance between the margin of the bars being grouped is kept constant. For instance, if we group the end of the bar a with the start of the bar B, the distance between end of the bar a and the start of the bar B is the same when moving or resizing any of the bars A or B.

Let's stay that we have the following chart:

with the keys:

By default ( no bars are grouped ), if we move the bar 2, from Oct 19, to Oct 21 , we get the following ( the bar 1, 3, and M are not moved or resized ):

If we group the bars as follows:

the end of the bar 2 with the start of the bar 1
the start of the bar 2 with the start of the bar 1
the end of the bar 3 with the end of the bar 1
the start of the bar 3 with the end of the bar 1
the start of the bar M with the start of the bar 2
the end of the bar M with the start of the bar 2

, and we move the bar 2, from Oct 19, to Oct 24 we get the following:

we notice that the bar 2 and M are moved, and bar 1 is resized.

		Type	Description
		ItemA as HITEM	A long expression that indicates the handle of the item that contains the bar to group to.
		KeyA as Variant	A long or string expression that specifies the key of the bar to group to. The Key parameter of the AddBar method specifies the key of the bar being added.
		StartA as Boolean	A boolean expression that specifies whether the start or the end of the bar is grouped with other bar. True specifies that the start of the bar is grouped with other bar. False indicates that the end of the bar is grouped with other bar.
		ItemB as HITEM	A long expression that indicates the handle of the item that contains the bar being grouped with.
		KeyB as Variant	A long or string expression that specifies the key of the bar being grouped with.
		StartB as Boolean	A boolean expression that specifies whether the start or the end of the bar is grouped with other bar. True specifies that the start of the bar is grouped with other bar. False indicates that the end of the bar is grouped with other bar.
		GroupBarsOptions as Variant	( exGroupBarsOptionNone, by default or if missing ) A GroupBarsOptionsEnum expression or a combination that specifies the way the bars gets grouped together. For instance, 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. If the GroupBarsOptions is exGroupBarsNone the bars are ungrouped.
		Options as Variant	( empty, by default or if missing ) A String expression that specifies a list of double values, separated by ; character, that specifies in this order: fixed interval ; maximum value when interval is increased, minimum value when the interval between bars is decreased. For instance, "2;4" value specifies that the interval between two bars should be 2 days and the interval can't be greater than 6 ( 2 + 4 ). Use the exLimitIntervalMin, exLimitIntervalMax, exLimitInterval or exFlexibleInterval for the GroupBarsOptions parameter when specifying the range of values that the interval between bars should be.