Gantt zoom

TreeGrid documentation

Zoom options

Attributes to control unit size and rounding for whole Gantt chart column.
Width in pixels of one base unit set by GanttUnits.
It can be automatically increased for smooth zoom, see GanttSmoothZoom.
When GanttExclude dates are hidden, the GanttWidth is increased to have the same average unit width as with GanttExclude visible.
Since 6.3 it can be floating point number and not only integer.
Base unit time, in these units is the Gantt chart shown, it can be date units:
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), if set GanttRoundUnits.
To these units are also rounded all box resizing and moving changes (but not the resulted dates themselves), if not set GanttDragUnits.
Since 6.3 it is never used for Gantt calculations, only for display.
Since 10.0 it is possible to define also any custom units, even with variable length, by global API function AddGanttUnits.
Prior to 14.0.10 the "w" was starting on Sunday, "w1" in Hijri started on Saturday and "w0" and "w6" did not exist. Round units for dragging. To these units is the dragging resize or move change rounded. If not set, it is rounded to actual GanttUnits.
The values are the same as GanttUnits.
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".
For 1 rounds all objects in chart except Run and Points to actual GanttUnits. It is default behavior in TreeGrid prior 8.0.
For 0 it does not round any date and displays the objects exactly where they are. The minimal object width is usually 6 pixels.
The rounding start date for newly created main bars and rounding date of newly created objects (starting main bar 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.
The rounding end date for newly created main bars and rounding date of newly created objects (ending main bar 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.
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.
The rounding never shrinks the chart width.
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.
Used always GanttUnits.
Flow rounding, to these units will be all dates in GanttFlow rounded, possible values are the same as GanttUnits.
Gantt chart time rounding when splitting chart to pages when printing.
To these units will be rounded the first and the last date for the chart parts, possible values are the same as GanttUnits.
Cfg attribute! If set, it prints only visible part of the actually scrolled / zoomed Gantt chart (horizontally).
It can be changed via print menu and is saved to cookies.
If Gantt chart column can be split if it is wider than selected page by PrintPageWidth.
Minimal size in pixels of printed part of Gantt when split by PrintGanttSplit.
It affects the first and last page part of the printed Gantt.
Adds new GanttUnits to the TreeGrid.
It is global function, it can (and should) be called after TreeGrid code (GridE.js file) is loaded, even before any grid is created.
The new units can be used like standard Gantt units in GanttUnits, GanttDataUnits, GanttHeader, GanttBackground and so on.
The new units cannot be used to define GanttExclude and Gantt calendars.
units is the units name that will be used, e.g. in GanttUnits.
width is the units length in milliseconds. For units with variable length must be set to average length.
exactwidth is the exact units length in milliseconds. It is usually the same as width or null for units with variable length.
For units with variable length (e.g. months or years) or units not starting on 1/1/1970 (e.g. weeks) or if set GMT='0' must be defined OnIncDate and OnRoundDate API events.
Since 14.1 if used GridED.js on demand script instead of GridE.js static script, the function downloads the GridE.js asynchronously and next add the Gantt units.

Example how to define fiscal year starting on April (for different month change the two 3 in the OnRoundDate). Use it like GanttHeader1="yf#yyyy" GanttSize="yf".
AddGanttUnits("yf",86400000*365.2425,null);
Grids.OnRoundDate = function(G,d,t){ if(t=="yf") { d = new Date(d); d.setUTCHours(0,0,0,0); d.setUTCFullYear(d.getUTCFullYear()-(d.getUTCMonth<3?1:0),3,1); return d-0; } }
Grids.OnIncDate = function(G,d,t,c){ if(t=="yf") { d = new Date(d); d.setUTCFullYear(d.getUTCFullYear()+c); return d-0; } }
Grids.OnGetGanttHeader = function (G,val,index,date,nextdate,units,width,partial,col){ if(units=='yf') return DateToString(date,'yyyy') + " - " + DateToString(nextdate,'yyyy'); return val; }
Called to round the date to the start of the custom Gantt units. See AddGanttUnits for example of usage.
date is a date in milliseconds since 1/1/1970. units is the custom defined units.
Return the rounded date in milliseconds since 1/1/1970 or Date object.
This event can be called also for standard Gantt units, so for all other units than the custom ones return null.
The event is called many times, so the code in the event must be very fast.
Called to increase the date by given count of custom Gantt units. See AddGanttUnits for example of usage.
date is a date in milliseconds since 1/1/1970. units is the custom defined units.
count is a count of the units to increase / decrease the date by. It can be negative. It is always integer.
The increased date must not be rounded, it should preserve all other parts (e.g. increasing 5/6/2000 10:15 by 10 years will be 5/6/2010 10:15)
Return the changed date in milliseconds since 1/1/1970 or Date object.
This event can be called also for standard Gantt units, so for all other units than the custom ones return null.
The event is called many times, so the code in the event must be very fast.

Chart size limits

Limits the size of the chart to this unit. The values are the same as the GanttUnits.
For example GanttSize='M' shows always Gantt chart for one month.
This value can be used to show only part of the chart or for paging in Gantt chart using side pager Type='Gantt'.
If set to empty string, it tries to show the whole chart. Also moving Gantt object outside the visible range will resize the visible range. It is default behavior in grid prior 9.0.
If set to 0, it tries to show the whole chart, moving Gantt object outside the visible range never resizes the visible range.
Count of GanttUnits added before GanttSize range, to show it from previous range.
Count of GanttUnits added after GanttSize range, to show it from next range.
If set to 1, it resizes / shrinks the Gantt chart for the selected GanttSize to the space for the Gantt chart.
(Since 12.0) If set to 2, it only resizes, but does not shrink the Gantt chart.
It calculates and modifies GanttWidth attribute only.
(Since 10.0) If set for GanttSize="" or "0", it shrinks the chart to show only the Gantt objects also on zoom change.
Since 12.0 its behavior is affected by GanttZoomFit attribute.
If set to 1, only visible rows are used to specify Gantt width (for GanttSize='0' or GanttSize='' and fit width for GanttSizeFit='1' or GanttZoom='' or action ZoomFit).
If set to 3, it behaves like 1 and also ignores GanttBase and GanttFinish when calculating GanttWidth.
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
The chart will always start at least at this date or before. It can be date string or integer.
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
The chart will always end at least at this date or after. It can be date string or integer.
Replaced by GanttChartMinStart
Replaced by GanttChartMaxEnd
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.
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.
Minimal width of the column in pixels.
It can be automatically decreased, if the whole Gantt in actual zoom between GanttChartMinStart and GanttChartMaxEnd is smaller than the MinWidth.
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 width for IE7 and IE8/9 quirks mode is 178957 pixels, except if used GanttPaging. Old versions of Opera were limited by 23000 pixels.
Maximal width for IE in GanttPaging is 1193049 for IE8 strict mode, 1342177 for IE8 quirks mode and 1533918 for other IE versions. Other browsers are not limited.
The MaxWidth can be automatically overflown if one unit of GanttChartRound x GanttWidth is wider than the MaxWidth (except the maximums in IE browsers).
Default MaxWidth is 10000 except for GanttPaging that is 1193049 (since 10.0).

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>
<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 GanttExclude is active by items with suffix Ex, like ... GanttWidth:18,GanttWidthEx:22 ...
Name of the zoom level. It will be used by GanttZoom attribute, in the SelectGanttZoom combo and in GanttMenu zoom items.
(Since 12.0) The zoom Name can be replaced in SelectGanttZoom and in GanttMenu by localized text in <Lang><Zoom name1='text1' name2='text2' ... /></Lang>
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 GanttExclude is active by items with suffix Ex, like ... GanttWidth:18,GanttWidthEx:22 ...
Name of the actually selected or predefined item from GanttZoomList.
(Since 9.1) If set to empty string, it fits the zoom to fill the whole available width, it calls action ZoomFit.
Date to scroll to in Gantt for given zoom.
Can be date string in English format or count of milliseconds since 1/1/1970.
Where the GanttZoomDate will be shown, can be Left, Center, Right. Case insensitive.
If the chosen zoom level unit width (GanttWidth) attribute can be increased to display exactly the selected range.
For zoom by dragging.
(Since 10.0) If set to 2 it increases the GanttWidth except in the last zoom level and does not shrink it in the first zoom.
(Since 13.2) If set to 3 it works as 2, but also for zoom fit.
How will behave changing zoom level.
0 - Actual view size will be preserved for GanttSize="" and "0"
1 - Actual view size will be reset for GanttSize="" and "0"
Which zoom changes will be added to undo. It does not affect zoom changes done by pager, see Pager ZoomUndo
0 - No zoom change is added to zoom undo
1 - Zoom changes done mouse, zooming to chosen date, date ranges and zoom fit are added zoom undo
2 - All zoom changes are added to zoom undo, including zoom in, zoom out and simple change zoom.
Controls action ZoomFit and since 12.0 also GanttSizeFit. Bit array.

1. + 2. bit, &3	0 - fits the Gantt into actual width of the column section where the Gantt column is or to GanttZoomFitWidth.
	1 - fits the Gantt into maximal width of the column section where the Gantt column is. See Widths of individual column sections.
	2 - fits the Gantt into minimal width of the column section where the Gantt column is. See Widths of individual column sections.
	3 - reserved
3. bit, &4	Reduces the section available width by other column widths in the section, if any. Value 4 replaces ZoomFitAll action.
4. bit, &8	Ignores side texts set by GanttShowHtml = 3 and GanttRunShowHtml = 3.
5. bit, &16	(new 16.1) Preserves GanttSize. If set, it never chooses zoom level with GanttSize that restricts showing the whole range.
6. bit, &32	(new 16.1) Ignores GanttChartMaxStart and GanttChartMinEnd - displays horizontal scrollbar like GanttZoomFitRound.

Controls action ZoomFit, permits zooming to show all content in the visible area with horizontal scroll to the rest.
The visible area is rounded to the GanttZoomFitRound and the whole chart area to the GanttChartRound.
Set it to 1 to round to actual GanttUnits or to Gantt units to round to these units.
Fixed width to fit the Gantt by GanttZoomFit. Useful if set NoVScroll or MaxVScroll. 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
What settings to synchronize among selected grids - among all grids with the same SyncId value.
Comma separated list of keywords, case insensitive.
All (substitution for Sort,Filter,Group,Search,Cols,Style), Sort, Filter, Group, Search, Cols (size, visibility and position),
Sec (new 9.3, width of column section), Horz (horizontal scroll), Horz0, Horz1, Horz2 (new 11.0, horizontal scroll of individual section, 0 left, 1 mid, 2 right), Vert (vertical scroll),
Style (new 9.0, CSS style), Zoom (new 9.3, Gantt zoom level and width)
For synchronizing Gantt charts by Zoom the Gantt should have the same width by setting the same GanttSize. All the grids should have the same Sync value to be synchronized in both ways.
For more information see Synchronizing grids.
Changes actual zoom level (GanttZoom) to item Name from GanttZoomList and refreshes Gantt chart.
Returns true for success, false for error.
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.
(Since 10.0) The width can be set negative to use null width increased by this number of pixels.
Returns true for success, false for error.
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.
Extends Gantt chart by given count of units. If count is negative, extends left side, otherwise extends right side.
Returns true if the actual GanttZoom value is not the last from GanttZoomList
Returns true if the actual GanttZoom value is not the last from GanttZoomList
Called after zoom level in chart changes or when the first or last displayed date changes (Gantt is scrolled to another window).
The zoom is name of actual zoom level.
The FirstDate is the first (left) date (in milliseconds) that is displayed in chart (regardless on scroll).
The LastDate is the last (right) date (in milliseconds) that is displayed in chart (regardless on scroll) plus 1.
Returns actual zoom levels list defined in <Zoom> tag or GanttZoomList attribute.
Returns JavaScript Array of the individual zoom level objects (<Z> tags).
It is possible to modify the individual zoom level attributes or even add or delete the individual zoom level objects.
The changes are shown only after change of zoom level, not in actual zoom level. To change actual zoom level settings, modify them directly in Gantt column and refresh the Gantt.
Provides zoom by dragging functionality.
A user selects a range by mouse dragging to be zoomed into.
Zooms or unzooms Gantt chart by pinch gesture on touch screen. 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.
Chooses next zoom level from GanttZoomList.
Chooses previous zoom level from GanttZoomList.
Chooses zoom level to show the whole Gantt chart without horizontal scrolling.
(Since 9.1) It is also called on start when set GanttZoom="".
(Since 10.0) Its functionality is controlled by GanttZoomFit attribute.
Replaced by ZoomFit and GanttZoomFit = 4.
Zooms to the exact header unit under mouse cursor if the cursor is above header.
Zooms to fit the actual bar (main, run)
Zooms to fit all the objects in the Gantt cell (main, run, flags, points, constraints)

Paging in Gantt

Vertical paging (rows)

Rows in TreeGrid with Gantt chart can be paged vertically like in normal tree / grid.
It can use root rows paging, child paging and child parts.
Also server paging and server child paging is supported for Gantt chart grids with few restrictions. Dependencies cannot be linked between tasks on different pages or child pages. The Gantt size cannot be calculated according to its content.

Horizontal paging by side pager

It is possible to set the Gantt chart to show only part of its range and switch among the parts by API or by one or more side pager Type='Gantt'.

Horizontal paging by scroll

Render only visible (due horizontal scroll) part of Gantt chart.
If set, permits paging in Gantt by horizontal scroll.
What will be paged in Gantt chart, bit mask. Used only if set GanttPaging='1'
If the bit is set to 0, the part is rendered for the whole Gantt chart. It will slow the Gantt initial rendering. Also showing too many items can slow down the grid responses or even throw JS errors, especially in IE.
If the bit is set to 1, the part is rendered only to Gantt page and is re-rendered for every page change. It can slow down the page rendering.
The variable rows are paged always. By default are paged Foot rows and Background.

1. bit (&1)	Head rows with Gantt header. If set to 0, the individual header rows can be paged by GanttHeaderPaging1...X attributes.
	It is recommended to display the first header with large units fully and next headers with small units paged.
2. bit (&2)	Foot rows. If the Gantt header is also in Foot rows, both the Head and Foot bits (&3) must be set the same.
3. bit (&4)	GanttBackground in variable rows. Background in fixed rows is controlled by the bits above.

If the header will be paged.
Used only if not set the first bit of GanttPagingFixed.
Useful to display fully only header(s) with large units to identify the position and the rest of headers (with small) display only inside actual page.
Width of the Gantt page in pixels (e.g. "2000") or in percent (e.g. "200%").
The percentage is of width of the actual visible columns section (the section with the horizontal scrollbar). It should be equal to or greater than 100%.
Initial width of the Gantt area to calculate GanttPageWidth when the grid is not rendered yet. In pixels.
Can be set to 0 to render the Gantt page after the grid is rendered.
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 width for IE7 and IE8/9 quirks mode is 178957 pixels, except if used GanttPaging. Old versions of Opera were limited by 23000 pixels.
Maximal width for IE in GanttPaging is 1193049 for IE8 strict mode, 1342177 of IE8 quirks mode and 1533918 of other IE versions. Other browsers are not limited.
The MaxWidth can be automatically overflown if one unit of GanttChartRound x GanttWidth is wider than the MaxWidth (except the maximums in IE browsers).
Default MaxWidth is 10000 except for GanttPaging that is 1193049 (since 10.0).
Called before new Gantt page is rendered.
size is an array [left, width, dragleft, dragwidth]:
It is possible to change the left and width values to render different page. The left and width are values as returned from UpdateGanttPage.
It is possible to return true to not render the Gantt page now, e.g. for asynchronous downloading data. In this case RenderGanttPage(col, size[0], size[1]) must be called later.
It is possible to return false to always render the Gantt page now, even if set zoom = true.
Return null or zoom to render the Gantt page only if set zoom = false.
zoom is true if called on start or on zoom change, actual left scroll is always 0 in this case.

It is possible to change the source Gantt data in the OnGanttPage to simulate server paging.
If set dragrow, you cannot delete old data from the Gantt by deleting the dragrow, because it contains source data being dragged. You have to add the new data to the dragrow cells instead.
dragrow is set to source row when the OnGanttPage is called during dragging in Gantt chart.
Renders actual Gantt page on given position.
Call it when OnGanttPage returned true or called UpdateGanttPage.
Calculates new Gantt page according to actual scroll position and returns [left,width] as position and width in pixels.
It is called automatically after horizontal scroll is changed.
You can call it to update the Gantt page immediately. There must be called also RenderGanttPage after the UpdateGanttPage.