Gantt summary tasks

TreeGrid documentation

Main bar as summary of child Main bars

Summary tasks are group of tasks and their start, end and duration is summary of its children. Summary bar can be continuous or discrete, see ganttparts and sumparts.
Define the summary task as default row <D> tag with attributes set for the summary task and assign this default by Def attribute, base summary definition can be:

<D Name="Summary" Calculated="1" StartFormula="ganttstart()" EndFormula="ganttend()" DurationFormula="ganttduration()" PartsFormula="ganttparts()" CompleteFormula="ganttpercent()" />

where Start, End, Duration, Parts and Complete are names of the five Gantt source columns. If some of the columns is not defined, the Formula should be omitted. Summary is custom name of this default row.

For example:
<Grid>
 <Cfg MainCol="S"/>
 <Cols> <C Name="S" Type="Date"/> <C Name="E" Type="Date"/> <C Name="D" Type="Int"/> <C Name="P" Type="Date" Range="1"/> <C Name="C" Type="Float"/> </Cols>
 <RightCols> <C Name="G" Type="Gantt" GanttStart="S" GanttEnd="E" GanttDuration="D" GanttParts="P" GanttComplete="C"/> </RightCols>
 <Def> <D Name="Sum" Calculated="1" SFormula="ganttstart()" EFormula="ganttend()" DFormula="ganttduration()" PFormula="ganttparts()" CFormula="ganttpercent()" /> </Def>
 <Body> <B> <I Def="Sum"> <I S="1/1/2000" E="1/10/2000" C="100"/> <I S="1/11/2000" D="5" C="30"/> <I P="1/16/2000~1/18/2000;1/20/2000~1/25/2000" C="0"/> </I> </B> </Body>
</Grid>
You can set different class for the summary bars by GanttClass attribute, for example <D ... xxxGanttClass="Group" xxxGanttIcons="1"/>, the Group is CSS class designed for the summary tasks, xxx is actual Gantt column name in the grid. The GanttIcons show the side icons designed for summary tasks.

The summary tasks are usually expected to be not editable and not movable, for this behavior set <D ... xxxGanttEdit="" CanEdit="0"/>
chg 6.3 upd 10.0 formula float

ganttpercent

(string ganttcol, string weightcol, int round, int plan = null, int type = 0)
Calculates summary percent of all child rows for its date ranges
ganttcol - gantt column, if it is null, uses the first Gantt column in grid
weightcol - column with exact weight factors for the tasks, if not set, the weight is computed from the task duration.
round - (new 6.3) to how many decimal places will be the result rounded, by default it is not rounded at all
plan - (new 10.0) main bar plan, 0 is the first plan (GanttStart), 1 the second plan (GanttStart1) and so on. If plan is null, it is calculated from the cell where the formula is used, if it is not possible it is used as 0.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
Example: <I Calculated='1' CalcOrder="Complete" CompleteFormula="ganttpercent()"/>
Since 7.0 it can be used also to calculate percentage of summary of Run tasks with GanttRunComplete set. It calculates Run only if child row does not define GanttComplete.
new 7.0 chg 13.1 formula int

ganttstart

(string ganttcol, int plan = null, int type = 0, bool milestones = 0)
Calculates summary (minimal) start of main bars in all child rows.
ganttcol - gantt column, if it is null, uses the first Gantt column in grid.
plan - (new 10.0) main bar plan, 0 is the first plan (GanttStart), 1 the second plan (GanttStart1) and so on. If plan is null, it is calculated from the cell where the formula is used, if it is not possible it is used as 0.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
milestones - new 13.1 if the end milestones will be ignored. The default behavior before 13.1 was 1
new 7.0 chg 13.1 formula int

ganttend

(string ganttcol, int plan = null, int type = 0, bool milestones = 0)
Calculates summary (maximal) start of main bars in all child rows.
ganttcol - gantt column, if it is null, uses the first Gantt column in grid.
plan - (new 10.0) main bar plan, 0 is the first plan (GanttStart), 1 the second plan (GanttStart1) and so on. If plan is null, it is calculated from the cell where the formula is used, if it is not possible it is used as 0.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
milestones - new 13.1 if the start milestones will be ignored. The default behavior before 13.1 was 1
chg 13.1 formula float

ganttduration

(string ganttcol, int plan = null, int type = 0, bool milestones = 0)
Calculates summary duration of main bars in all child rows. It simply returns ganttend() - ganttstart() in GanttDataUnits.
ganttcol - gantt column, if it is null, uses the first Gantt column in grid
plan - (new 10.0) main bar plan, 0 is the first plan (GanttStart), 1 the second plan (GanttStart1) and so on. If plan is null, it is calculated from the cell where the formula is used, if it is not possible it is used as 0.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
milestones - new 13.1 if the start / end milestones will be ignored when calculating the bounds. The default behavior before 13.1 was 1
new 10.0 chg 13.1 formula float

ganttparts

(string ganttcol, int plan = null, int type = 0, bool milestones = 0)
Calculated summary GanttParts of main bars in all child rows. It simply returns ganttstart() +"~"+ ganttendt().
ganttcol - gantt column, if it is null, uses the first Gantt column in grid
plan - main bar plan, 0 is the first plan (GanttStart), 1 the second plan (GanttStart1) and so on. If plan is null, it is calculated from the cell where the formula is used, if it is not possible it is used as 0.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
milestones - new 13.1 if the start / end milestones will be ignored when calculating the bounds. The default behavior before 13.1 was 1
Use it to calculate value of GanttParts for continuous summary tasks. For discrete summary tasks use sumparts.
new 10.0 formula string

sumparts

(string col = null, string condition = null, int type = 0, string server = null)
Sums all dates in column with Range=1 Type="Date". It just creates new range from all intervals and updates it to not contain duplicate value cross intervals.
The only difference to sumrange is that sumparts is affected by GanttLastUnit.
For its parameters see sum function.
There is no plan parameter, the function just sums values in the col.
Use it to calculate value of GanttParts for discrete summary tasks. For continuous summary tasks use ganttparts.
new 11.0 formula string

sumavailability

(string col = null, string condition = null, int type = 0, string server = null)
Sums all availability dates in column. It just creates new range from all intervals and updates it to not contain duplicate value cross intervals.
It is similar to sumparts and sumrange, but it never shrinks the resulted range.
deleted 6.3 formula int

ganttpercentduration

(string durationcol, string percentcol='', int round=0)
Replaced by ganttpercent.

Main bar as summary of child Run bars

Main bar can be used also to show summary for its child Run bars. It can show only continuous summary.
Use such formulas to show the summary:
<I Calculated="1" GGanttStartFormula="ganttrunminstart('G')" GGanttEndFormula="ganttrunmaxend('G')" GGanttDurationFormula="ganttrunsumduration('G')" GGanttCompleteFormula="ganttpercent('G')"/>
new 6.2 upd 10.0 formula int

ganttrunminstart

(string ganttcol, int type = 0)
Calculates minimal start date (in milliseconds) of all child Runs.
Used to get Run range of child Runs and show it as Main Bar.
ganttcol - column showing the Gantt chart, it should contain the Run bars.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
new 6.1 upd 10.0 formula int

ganttrunmaxend

(string ganttcol, int type = 0)
Calculates maximal end date (in milliseconds) of all child Runs.
Used to get Run range of child Runs and show it as Main Bar.
ganttcol - column showing the Gantt chart, it should contain the Run bars.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
new 10.0 formula int

ganttrunsumduration

(string ganttcol, int type = 0)
Calculates summary duration (in GanttDataUnits) of all child Runs. Simply returns ganttrunmaxend()-ganttrunminstart in workdays and GanttDataUnits.
Used to get Run range of child Runs and show it as Main Bar.
ganttcol - column showing the Gantt chart, it should contain the Run bars.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
chg 6.3 upd 10.0 formula float

ganttpercent

(string ganttcol, string weightcol, int round, int plan = null)
Calculates summary percent of all child rows for its date ranges.
ganttcol - gantt column, if it is null, uses the first Gantt column in grid.
weightcol - column with exact weight factors for the tasks, if not set, the weight is computed from the task duration.
round - (new 6.3) to how many decimal places will be the result rounded, by default it is not rounded at all
plan - (new 10.0) main bar plan, 0 is the first plan (GanttStart), 1 the second plan (GanttStart1) and so on. If plan is null, it is calculated from the cell where the formula is used, if it is not possible it is used as 0.
type - (new 10.0) specifies rows to calculate, see sum type parameter.
Example: <I Calculated='1' CalcOrder="Complete" CompleteFormula="ganttpercent()"/>
Since 7.0 it can be used also to calculate percentage of summary of Run tasks with GanttRunComplete set. It calculates Run only if child row does not define GanttComplete.

Editable Main bar as summary of child Main or Run bars

It is possible to have also editable summary tasks, including date constraints and dependencies.
All the dependencies and constraints attached to summary tasks are automatically assigned to all child tasks.

How to set the editable summary task:
1) Define main bar as summary of main bars or run bars by Formulas described above.
2) Set the summary task editable, define <D xxxGanttEdit='all' startCanEdit='1' /> where the start is name of the Gantt source column, the xxx is name of the Gantt column itself.
3) To correctly calculate dependencies and date constraints set <D xxxGanttSummaryX='Y'/>, see its description below.
new 6.7 chg 10.0 <cell> int

GanttSummaryX

[""]
Set it to main bar plan number in children for editable summary task. Set it to 0 for the first plan. Set it to '-' (minus) for Run bars. Set it to empty string to no summary.
The X is main bar plan in this parent, for the first main plan is empty (GanttSummary, GanttSummary1, GanttSummary2, ...). See GanttCount.
For example:GanttSummary = '0'means the main bar plan 0 in this parent row is marked as editable summary for the same plan 0 in child rows.
GanttSummary1 = '-'means the main bar plan 1 in this parent row is marked as editable summary for the run bars in child rows.
GanttSummary3 = '2'means the main bar plan 3 in this parent row is marked as editable summary for main bar plan 2 in child rows.

It will cause:
- all dependencies attached to the summary task will be assigned also to all its children (as hidden dependencies).
- dependencies between the summary and its children will be marked or restricted as circular.
- the MinStart and MaxEnd date constraints assigned to summary tasks will be used also for all its children if they are more restrictive than the child task constraints, if any.
- if the tasks is moved by mouse dragging or editing its start date, it moves also all its children. The task cannot be moved, if it would lead to violate any child's constraints.
- the task cannot be created, resized or deleted and its GanttComplete value cannot be changed by a user. Except the GanttSummaryType is set to 1.

Since 10.0 the value is 0 for the first main plan!

The method implemented causes not good behavior for dependencies incoming to the finish of the summary task and dependencies outgoing from start of the summary task.
Also zero float/span or GanttIncorrectDependencies='2' is not supported for dependencies in summary tasks.
new 10.0 <C> <cell> int

GanttSummaryTypeX

[0]
For 0 it restricts creating, resizing and deleting the summary task. The task is expected to be calculated from its children by formulas.
For 1 it permits these actions. The task should not be calculated from its children by formulas.
Before 10.0 it was set as GanttSummary='2'.

Editable Run bar as summary of child Main bars

It is possible to group child main bars to one parent Run bar, containing all the main bars at one row.
The Run can be editable, so all the changes done in the Run is mirrored to the source main bars.
It is possible to collapse the Run and let a user to manipulate only by the Run bars instead of the main bars.
It can be used to group main bars according to various attributes to the Run.

Set it up by:
Define new (hidden) column (name it e.g. "RUN"). Assign this column as GanttRun (e.g. <C ... GanttRun='RUN'/>
Set to the row xxxGanttRunSummary='X', where X is the main bar plan, e.g. '0'
Calculate the RUN from the children by RUNFormula='ganttrunsum()'

Optionally:
Define other Run columns like GanttRunStart, GanttRunEnd, GanttRunDuration, GanttRunComplete
And calculate them by formulas: ganttrunstart, ganttrunend, ganttrunduration, ganttpercent()
Define right CalcOrder for the rows to be first calculated the Run by ganttrunsum

Behavior:
The Run will reflect every change - moving, resizing, deleting and creating the main bar. Also deleting row and creating new child.
The moving and resizing source main bar ignores other boxes, it behaves always like if the run has set GanttRunAdjust='Error'.
The children will reflect the Run changes - moving and resizing the Run box.
Creating new Run box will create new child with the same main bar. It is called OnRowAdded API event, but not OnRowAdd.
Deleting Run box will delete appropriate row. It is called OnRowDelete API event.
Moving Run box to another row will move the appropriate child row to this parent. It is called OnRowMove API event.
The Run boxes have the same ids as the child rows.
new 9.1 upd 10.0 formula string

ganttrunsum

(string ganttcol = "", string condition = "", int type = "", int plan = 0)
Sums all child main bars and returns result Run with all the bars. The Run bars have set their ids as the main bar row ids.
If set GanttRunSumarry it permits changing the summary boxes and do the changes in children.
ganttcol = gantt column, can be empty for the first Gantt column in grid
(Since 9.3) The type and condition specify which rows to iterate, for more information see the sum function.
(Since 10.0) The plan is main bar plan to calculate summary for (if not set Start,End,Duration by GanttSummaryCols). 0 means the first main bar plan.
The GanttParts must not be defined for used main bar plan!
new 10.0 formula string

ganttrundescendants

(string ganttcol = "", string condition = "", int type = "", int plan = 0)
Sums all dependencies from child main bars, use for GanttDescendants.
If set GanttRunSumarryDependencies it permits changing the summary dependencies and do the changes in children.
ganttcol = gantt column, can be empty for the first Gantt column in grid
The type and condition specify which rows to iterate, for more information see the sum function.
The function sums always all the child dependencies, but if set the plan, only dependencies for this plan are converted to the run boxes. 0 means the first main bar plan.
There must be set "box" in GanttTask.
To use box scheduling, remove the source main bar plan from GanttTask.
new 10.0 formula string

ganttrunancestors

(string ganttcol = "", string condition = "", int type = "", int plan = 0)
Sums all dependencies from child main bars, use for GanttAncestors.
If set GanttRunSumarryDependencies it permits changing the summary dependencies and do the changes in children.
ganttcol = gantt column, can be empty for the first Gantt column in grid
The type and condition specify which rows to iterate, for more information see the sum function.
The function sums always all the child dependencies, but if set the plan, only dependencies for this plan are converted to the run boxes. 0 means the first main bar plan.
There must be set "box" in GanttTask.
To use box scheduling, remove the source main bar plan from GanttTask.
new 10.0 <cell> int

GanttRunSummary

[""]
Links the main bars with the summary Run bars calculated by ganttrunsum. Mirrors the changes between them.
Set it to main bar plan number in children. Set to the same plan number the ganttrunsum was called.
Set it to 0 for the first main bar plan. Set it to empty string to no link.
new 10.0 <cell> int

GanttRunSummaryDependencies

[""]
Links the main bar dependencies with the summary Run bar dependencies calculated by ganttrundescendants and / or ganttrunancestors. Mirrors the changes between them.
Set it to main bar plan number in children. Set to the same plan number the ganttrundescendants and / or ganttrunancestors were called.
Set it to 0 for the first main bar plan. Set it to empty string to no link.
new 9.1 deleted 10.0 <cell> int

GanttSummary = "2"

For Editable Run summary it is renamed to GanttRunSummary. The value changed from 2 to main bar plan.
new 9.3 <cell> string[ ]

GanttSummaryCols

Note, there is no Run keyword in the attribute name, due backward compatibility
Comma separated list of linked columns in child rows to Run attributes, when created the run summary by ganttrunsum formula.
In this order: "Start,End,Duration,Type,Text,Class,Tip,Id,Group,State,Top,Height,Manual,Complete,Resources,HtmlLeft,HtmlRight". The order the same as in GanttRun attribute.
If not set, the Start is set to GanttStart column, End to GanttEnd column and Duration to GanttDuration column, of given plan in ganttrunsum.
If not set State, the Disabled state is read from GanttDisabled and Selected state from row.Selected. Note, next selecting the child row does not update the run selected state automatically.
The GanttParts must not be defined for used main bar plan!
The Id is now always set to row id attribute and cannot be changed.
For example GanttSummaryCols=",,,B,,C" means that the Run Type attribute will be read from child rows from 'B' column and Class attribute from 'C' column.
new 9.3 <cell> string[ ]

GanttSummarySeparators

Note, there is no Run keyword in the attribute name, due backward compatibility.
Custom Run separators to be used instead of ";," by ganttrunsum formula. Use when some Text or Tip can contain the default separators (comma and semicolon).
new 9.3 <cell> string

GanttSummaryCDef

['']
Note, there is no Run keyword in the attribute name, due backward compatibility.
Name of default row assigned to new child rows created for new Run bars. If not set, standard CDef attribute value is used.
If set, ganttrunsum iterates only rows with this default row name.
new 10.0 <C> string

GanttRunSummaryIdPrefix

["" / "R"]
A string added to run box id before the child row id when creating run boxes from child main bars.
By default is "R" if GanttTask contains "Box" and also some main flag. Otherwise it is empty.
Use it especially if you have number id rows and you want to use also dependencies in the summary run boxes by ganttrundescendants / ganttrunancestors.