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.

For instance:

GroupBars(h1, "", True, h2, "", True); GroupBars(h1, "", False, h2, "", False), links the starts and ends of the bars so they move together as a block (block)
GroupBars h1, "", False, h2, "", True, GroupBarsOptionsEnum.exPreserveBarLength Or GroupBarsOptionsEnum.exIgnoreOriginalInterval, "2", preserves both bars' lengths, ignores original interval, sets exact distance of 2 days between bars (fixed)
GroupBars h1, "", False, h2, "", True, GroupBarsOptionsEnum.exPreserveBarLength Or GroupBarsOptionsEnum.exIgnoreOriginalInterval Or GroupBarsOptionsEnum.exLimitIntervalMin, "2", preserves both bars' lengths, ignores original interval, bars must be at least 2 days apart (minimum interval)
GroupBars h1, "", False, h2, "", True, GroupBarsOptionsEnum.exPreserveBarLength Or GroupBarsOptionsEnum.exIgnoreOriginalInterval Or GroupBarsOptionsEnum.exLimitInterval, "0;0;2", preserves both bars' lengths, ignores original interval, bars can be at most 2 days apart (maximum interval)
GroupBars h1, "", False, h2, "", True, GroupBarsOptionsEnum.exPreserveBarLength Or GroupBarsOptionsEnum.exIgnoreOriginalInterval Or GroupBarsOptionsEnum.exLimitInterval, "0;1;7", Preserves both bars' lengths, ignores original interval, bars must be between 1 and 7 days apart (interval)

If the GroupBarsOptions parameter includes the exLimitIntervalTreatAsWorking flag the options parameter are treated as working units.

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 defines 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. The Key parameter of the AddBar method defines the key of the bar being added.
		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	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 as Variant	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.