TreeGrid v6.3

Gantt display and zoom

TreeGrid documentation index

 

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.

 

Background

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.

 

Zoom options

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.

 

Zoom selection

 

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.