TreeGrid v6.3
Gantt display and zoom
The Gantt chart can be added to grid by defining column of type Gantt (<C Type=’Gantt’ ... />) and setting the other Gantt chart attributes.
The grid with Gantt column still supports all other functionality like normal grid (sorting, filtering, grouping, search, calculations, ...).
The Gantt chart is automatically created from the given values and is also automatically recalculated whenever some source value is changed.
The Gantt chart is also interactive, so a user can change the Gantt chart by mouse and it automatically updates the source data.
The Gantt chart sources are usually other columns where are stored the source data in cells. These cells can be also edited by a user and Gantt chart is automatically updated.
Predefined settings for Gantt column is in default column <D Name=’Gantt’/>, defined in Defaults.xml
Gantt column Header
One or more lines in header displaying dates
In header you can show one or more lines with dates that are displayed in the chart.
You can specify how the dates will be repeated and the format for the dates.
Up to 5 different header lines can be defined
<C> string GanttHeader1, ..., GanttHeader5 chg 6.3;upd 7.0.
Header time/number and format in the first header line: “repeater#format#shift”.
The possible values of repeater are the same as GanttUnits, e.g. “w”, “d”, “h” or “1”, “0.5”, “2”, ...
The format is standard TreeGrid date / time format string for date repeaters, or standard TreeGrid number format string for number repeaters.
The shift (new 6.4) is optional and moves the header by the shift repeater units left, it can be floating point number. It is usually 0.5 to center the label above the position.
The number repeaters and formats are supported since 6.4.
Since 7.0 when shift is not set and repeater is number, the negative numbers are shifted for one unit, so zero is printed twice. Set shift to 0 if you don’t want this behavior.
<C> string GanttFormat1 deleted 6.3 .
Moved to GanttHeader.
Date / time format to format items in the first header line, the same as standard TreeGrid date / time format.
<C> bool GanttHeaderRound1, ..., GanttHeaderRound5 new 6.3.
If rounds header date to workdays / work hours, defined by GanttExclude. Only for GanttHideExclude=1.
<C> string GanttHeaderId1, ..., GanttHeaderId5 new 7.0.
id of the header row where the header line will be displayed. If not set, the header line will be displayed in main header.
One header row can show more Gantt header lines.
<C> int GanttHeaderHeight1, ..., GanttHeaderHeight5 new 7.0.
Height in pixels of the header line. Useful when used some special formatting in header or displaying it in more lines.
<C> int GanttHeaderTrim renamed 6.0 .
0 – The incomplete header items are shown, 1 – the incomplete header items are replaced by ‘...’
The trimming ‘...’ is set by <Lang><Format Cont=’...’ ContLeft=’... ‘ ContRight=’ ...’/></Lang> attributes.
API event string OnGetGanttHeader (TGrid grid, string val, int date, int nextdate, string units, int width, int partial, string col) new 7.0 .
Called for every date in every Gantt header line to get the caption displayed.
Return the new value or val to not change the original caption.
date is the first date in the range. nextdate is the first date after the range, units is the range unit width like GanttUnits, width is width of the space for the caption in pixels
partial is 0 for full range, 1 for range trimmed from left, 2 for range trimmed from right, 3 for range trimmed from both sides. The date and nextdate are the trimmed dates in these cases.
Marks workdays, weekends or any other dates – for all rows the same
Defined by GanttBackground (date ranges with repeater).
You can color any dates or date range that are periodically repeated as workdays, weekends, working hours and so on and also exact not repeated dates.
The background is the same for whole chart and cannot be set for individual rows
The background is just visual setting, to exclude some date from Gantt calculation, use GanttExclude instead.
<C> string GanttBackground chg 6.3; upd 7.0 .
Date ranges displayed as background, useful for marking some period repeatedly.
The format is: rep1#date1a~date1b#cls1;rep2#date2a~date2b#cls2;...
The repeater rep can be one of GanttUnits. If it is missing, the date is not repeated. The date is repeated also before it.
The seconds date in range can be missing to show single line.
(Since 7.0) The cls can be index of the GxGanttBack class to use to show the background, predefined backgrounds are 1-5. If missing, as index is used the item position, from 1.
(Since 7.0) It is possible to limit the repeating, when the date range is wider than the rep, the range is rounded to the rep range and repeated only between the dates.
For example ‘w#1/5/2008~12/29/2008’ marks all weekends, but only in year 2008.
(Since 7.0) It is possible to set the second date before the first one, it will be updated to correctly fill the repeat range.
For example ‘d#18:00~8:00’ marks all times from 18:00 to 8:00.
For example: GanttBackground = ‘d#1/5/2008~1/7/2008; M#1/1/2008’ colors weekends and separates months by line
<C> string GanttBackgroundRepeat deleted 6.3 .
Replaced by repeater in GanttBackground.
GanttBackground will be repeated by these units, can be empty to not repeat. Possible values are the same as GanttUnits.
If GanttBackground contains more date ranges, it should contain more units (one per range), comma separated.
Attributes to control unit size and rounding for whole Gantt chart column.
<C> float GanttWidth [18] Saved to cookies, to avoid it set <Cfg GanttLap=’1’/> upd 6.3 .
Width in pixels of one base unit set by GanttUnits.
It can be automatically increased for smooth zoom, see GanttSmotthZoom.
When Exclude dates are hidden, the GanttWidth is increased to have the same average unit width as with Exclude visible.
Since 6.3 it can be floating point number and not only integer.
<C> string GanttUnits [‘d’] upd 6.4 .
Base unit time, in these units is the Gantt chart shown, it can be date units:
‘ms’ – milliseconds, “ms10” – 10 milliseconds, “ms100” – 100 milliseconds,
‘s’ – seconds, ‘s2’ – 2 seconds, ’s5’ – 5 seconds, ’s10’ – 10 seconds, ’s15’ – 15 seconds, ’s30’ – 30 seconds,
‘m’ - minutes, ‘m2’ – 2 minutes, ’m5’ – 5 minutes, ’m10’ – 10 minutes, ’m15’ – quarters of hour, ’m30’ – halves of hour,
’h’ - hours, ’h2’ – 2 hours, ’h3’ – 3 hours, ’h6’ – quarters of day, ’h8’ – thirds of day, ’h12’ – halves of day,
’d’ - days, ’w’ – weeks (starting by Sunday), ’w1’ – weeks (starting by Monday, in Hirji starts by Saturday),
’M’ - months, ’M3’ – quarters of year, ’M6’ – halves of year, ’y’ – years
Since 6.4 it can be also any number for number units, “1”as base number units, but it can be for example “0.5”, “2”, “10”, “0.2”, ...
To these units are all the dates rounded for display (but not dependency errors and other computing).
To these units are also rounded all box resizing and moving changes (but not the resulted dates themselves)
For example date “1/1/2000 10:00” moved by 60 hours for units ‘d’ (days), the change will be rounded to 48 hours and the result will be “1/3/2000 10:00”.
Since 6.3 it is never used for Gantt calculations, only for display.
<C> string GanttNewStart new 7.0 .
The rounding start date for newly created tasks (Main, Flow) and rounding date of newly created objects (starting Milestone, starting constraints, Flag, Point).
To this date part will be the new date rounded within GanttUnits.
For example for GanttUnits=’d’ GanttNewStart=’1/1/2000 8:00’ all newly created tasks will start at 8:00.
Remember, for editing Date type cell you can set DefaultDate for the cell to predefine missing parts of the date.
<C> string GanttNewEnd new 7.0 .
The rounding end date for newly created tasks (Main, Flow) and rounding date of newly created objects (ending Milestone, ending constraints)
To this date part will be the new date rounded within GanttUnits.
For example for GanttUnits=’d’ GanttNewEnd=’1/1/2000 17:00’ all newly created tasks will end at 17:00.
Remember, for editing Date type cell you can set DefaultDate for the cell to predefine missing parts of the date.
<C> string GanttChartRound .
Gantt chart time rounding, to these units will be rounded the first and the last date for the whole chart, possible values are the same as GanttUnits.
<C> int GanttChartMinStart new 6.4 .
All dates before will never be displayed in the chart. It can be date string or integer.
If set GanttChartMinStart and GanttChartMaxStart to the same value, the chart will always start here, except width limits.
Replaced GanttMin
<C> int GanttChartMaxStart new 6.4 .
The chart will always start at least at this date or before. It can be date string or integer.
<C> int GanttChartMaxEnd new 6.4 .
All dates after will never be displayed in the chart. It can be date string or integer.
If set GanttChartMinEnd and GanttChartMaxEnd to the same value, the chart will always end here, except width limits.
Replaced GanttMax
<C> int GanttChartMinEnd new 6.4 .
The chart will always end at least at this date or after. It can be date string or integer.
<C> int GanttMin renamed 6.4 .
Replaced by GanttChartMinStart
<C> int GanttMax renamed 6.4 .
Replaced by GanttChartMaxEnd
<C> int GanttLeft [0] .
A count of empty base units that will be displayed before the whole Gantt chart
If set GanttChartMinStart, objects cannot be moved or resized before GanttChartMinStart+GanttLeft*GanttUnits
<C> int GanttRight [0] .
A count of empty base units that will be displayed after the whole Gantt chart
If set GanttChartMaxEnd, objects cannot be moved or resized after GanttChartMaxEnd-GanttRight*GanttUnits
<C> int MinWidth .
Minimal width of the column in pixels.
<C> int MaxWidth [10000] new 6.3 .
Maximal width of the column in pixels.
If the zoom level is too high and the Gantt chart reaches this limit, there is displayed only part of the chart and the rest can be displayed only by unzoom.
Maximal permitted width for Opera browser is 23000 pixels. Maximal width for IE is 178957 pixels, other browsers are not limited.
The maximal width can be extended if one unit of GanttChartRound x GanttWidth is wider than the MaxWidth.
<C> string GanttRound [‘m’] deleted 6.3 .
Used always GanttUnits.
Base unit time rounding, to these units will be all dates rounded, possible values are the same as GanttUnits.
It can be set also to empty string to not to round. In this case the same start and due dates will produce no bar at all.
<C> string GanttFlowRound deleted 6.3 .
Used always GanttUnits.
Flow rounding, to these units will be all dates in GanttFlow rounded, possible values are the same as GanttUnits.
Attributes to specify and change zoom level for whole Gantt chart column.
The individual zoom levels can be defined globally by root <Zoom> tag and individual <Z> tags (since 6.4) or for the specified Gantt column by GanttZoomList.
Example:
<Cols><C ... GanttZoom="weeks" ... /> ... </Cols>
<Zoom>
<Z Name='weeks' GanttUnits='w' GanttChartRound='M' GanttHeader1='w#%d'/>
<Z Name='days' GanttUnits='d' GanttChartRound='w' GanttHeader1='d#%d'/>
<Z Name='hours' GanttUnits='h' GanttChartRound='d' GanttHeader1='h#HH:'/>
</Zoom>
OR
<Cols><C ... GanttZoom="weeks" GanttZoomList="[
{ Name:'weeks',GanttUnits:'w',GanttChartRound:'M',GanttHeader1:'w#%d' },
{ Name:'days',GanttUnits:'d',GanttChartRound:'w',GanttHeader1:'d#%d' },
{ Name:'hours',GanttUnits:'h',GanttChartRound:'d',GanttHeader1:'h#HH:' }
]" ... /> ... </Cols>
<Zoom> <Z> new 6.4 .
<Z> tag defines individual one Gantt zoom level.
It can be placed in root <Zoom> tag.
It can have set its Name attribute to display in SelectGanttZoom Type dialog and to access by GanttZoom attribute.
Every <Z> tag can contain individual settings for Gantt attributes from Zoom options, Header, Background.
After the zoom level is selected, all the attributes are set to the Gantt column and Gantt chart is recalculated.
To use smooth zoom in / zoom out the list of <Z> tags inside <Zoom> must be sorted according to zoom size, from smallest zoom size up.
Zoom size is specified by GanttUnits and GanttWidth attributes.
It is possible to set different zoom settings for case the Exclude is active by items with suffix Ex, like ... GanttWidth:18,GanttWidthEx:22 ...
<Z> string Name new 6.4 .
Name of the zoom level. It will be used by GanttZoom attribute and in the SelectGanttZoom combo.
<C> string GanttZoomList new 6.3 .
A list of predefined zoom levels in JSON format. It contains an array of individual objects as zoom levels.
It can be used instead of global <Zoom> tag when there are more Gantt columns in grid, or if JSON format is preferred by the developer.
Every object has set its Name attribute to display in SelectGanttZoom Type dialog.
Every object can contain individual settings of attributes from Zoom options, Header, Background.
After the zoom level is selected, all the attributes are set to the Gantt column and Gantt chart is recalculated.
To use smooth zoom in / zoom out the list must be sorted according to zoom size, from smallest zoom size up.
Zoom size is specified by GanttUnits and GanttWidth attributes.
It is possible to set different zoom settings for case the Exclude is active by items with suffix Ex, like ... GanttWidth:18,GanttWidthEx:22 ...
<C> string GanttZoom Saved to cookies, to avoid it set <Cfg GanttLap=’1’/> new 6.3 .
Name of the actually selected or predefined item from GanttZoomList.
<C> string GanttZoomDate [ ] new 7.0 .
Date to scroll to in Gantt for given zoom.
Can be date string in English format or count of milliseconds since 1/1/1970.
<C> string GanttZoomDateAlign [“Center”] new 7.0 .
Where the GanttZoomDate will be shown, can be Left, Center, Right. Case insensitive.
<C> bool GanttSmoothZoom [1] new 6.3 .
If the chosen zoom level unit width (GanttWidth) attribute can be increased to display exactly the selected range.
For zoom by dragging.
<Space cell> string Type Type=”SelectGanttZoom” new 6.3 .
Special combo box to select zoom level defined by GanttZoomList. It displayed and changes GanttZoom attribute.
It presets these cell attribute: Type=”Html” Button=”Defaults” Defaults=GanttZoomList OnChange=change GanttZoom
API method bool ChangeZoom (string Name) new 6.3 .
Changes actual zoom level (GanttZoom) to item Name from GanttZoomList and refreshes Gantt chart.
Returns true for success, false for error.
API method bool ZoomTo (Date start, Date end, int width = null) new 6.3 .
Selects appropriate zoom to display date range from start to end to be wide with pixels.
If the width is null, it is the maximal visible space available for Gantt chart within actual Main tag.
If required, it also scrolls the Gantt column to show the given range.
Returns true for success, false for error.
API method void ScrollToDate (Date date, string align = “Center”) new 7.0 .
Scrolls to given date. align can be “Left”, “Center”, “Right”. Case insensitive.
If the date is not displayed because of actual zoom level, it shows the appropriate part of the chart, but never changes zoom level.
API method bool CanZoomIn ( ) new 6.3 .
Returns true if the actual GanttZoom value is not the last from GanttZoomList
API method bool CanZoomOut ( ) new 6.3 .
Returns true if the actual GanttZoom value is not the first from GanttZoomList
<Actions> ZoomGantt Attached to OnDragGanttHeader event, can be attached also to OnDragGantt new 6.3 .
Provides zoom by dragging functionality.
A user selects a range by mouse dragging to be zoomed into.
<Actions> UndoZoom Attached to OnRightClickGanttHeader event new 6.3 .
Switches back to previously chosen zoom level by ZoomGantt action or ZoomTo method.
It can be called more times to go back in the queue.
<Actions> ZoomIn Attached to OnClickGanttHeader event new 6.3 .
Chooses next zoom level from GanttZoomList.
<Actions> ZoomOut Attached to OnRightClickGanttHeader event new 6.3 .
Chooses previous zoom level from GanttZoomList.
<Actions> ZoomFit Not attached to any event new 6.3 .
Chooses zoom level to show the whole Gantt chart without horizontal scrolling.
<Actions> ZoomFitAll Not attached to any event new 6.3 .
Chooses zoom levels to show the whole Gantt chart and hide horizontal scrollbar.
The difference to ZoomFit is that it shows also other variable columns.
<Actions> ZoomHeader Attached to OnClickGanttHeader event new 6.3 .
Zooms to the exact header unit under mouse cursor if the cursor is above header.