Grid size and scroll

TreeGrid documentation

Describes how to control width and height of the whole grid and when and how to scroll its content.

Default behavior

By default TreeGrid is rendered into its main div tag and does not change its size. The main tag should have set its height and width style attributes, otherwise grid sets them to 100%.
In strict mode the main tag height attribute should be set to fixed height if it can affect body height, otherwise grid automatically sets <Cfg MaxVScroll='2000'/>.
If the grid content is smaller than the main tag, there is shown empty space inside the main tag, if the grid is bigger than the main tag it shows its scrollbars.
The main tag has automatically set overflow:hidden and you must not change it.
When grid cannot show its content because it wider or higher than the main tag size, it shows error message "Too small extents". To not show the message, set <Lang><Text ExtentErr=""/></Lang>.
When grid cannot show its content horizontally, it first tries to minimize all fixed columns and Pager that have CanResize='1' to their MinWidth. If it is not enough, it hides all fixed columns and Pager that have CanHide='1'.
If the size of grid is computed according to the real main tag size.
For 1 it preserves also percentage width inside tables and similar layouts.
Set it to 0 for large tables when grid becomes slow when updating layout.
If used external objects like Flash or SilverLight in grid cells, it should be set to 0.
Called when the grid cannot be rendered due too small size of the main tag.
Solve this problem by changing grid content or resizing the main tag, call Update() and return true.
width is the available width in pixels, negative means error.
height is the available height in pixels, negative means error.

Maximize grid width and height

To fill the whole main tag by grid content set <Cfg ConstHeight='1' ConstWidth='1'/> or use some row with <I RelHeight='1'/> and column with <C RelWidth='1'/>.
To fill the whole window by main tag set <Cfg MaxHeight='1' MaxWidth='1'/>, ensure that your page layout fulfills all requirements for the MaxHeight attribute!
You can set minimal size of the main tag by <Cfg MinTagHeight='...' MinTagWidth='...'/>, maximal size of the main tag by <Cfg MaxTagHeight='...' MaxTagWidth='...'/>.
If set to 1, updates height of grid to fill whole main tag. It does not modify main tag height, see MaxHeight.
It is ignored when set NoVScroll = '1'.
In fact it adds to grid new special row <Space RelHeight='1' Space='2' Kind='Fill'/>. This row is positioned between body and foot section.
To better control this space, you can add this <Space> row by yourself instead of using ConstHeight attribute.
If grid already contains some row with RelHeight attribute set, the ConstHeight attribute is ignored.
! If you use ConstHeight, do not set height of main tag in percent. !
If set, it adds new white ConstWidth column to middle or right section to resize grid content to main tag width. It does not modify main tag width, see MaxWidth.
It add the column <C Name="_ConstWidth" ConstWidth='1' Def="ConstWidth"/> with also disabled all standard features like sorting, filtering or dragging.
The column uses CSS class GxCellEmpty for all cells except header, here uses GxCellHeaderEmpty

0	No column added
1	The column is placed between middle and right section, into right section if there is some column, otherwise to the middle section.
2	The column is always placed to the right end of middle section.
3	(new 7.0) The column is placed to the right end of right section if exists, otherwise to the middle section.
4	(new 7.0) It resizes the grid content to show at least Columns and Cfg buttons on toolbar.
	If the toolbar is hidden or it does not contain the buttons, it does nothing. Column position is the same as 3.
5	(new 13.0) It resizes the grid content to show all space cells. Column position is the same as 3.
6	(new 13.0) Like 5, but shows cells up to LastVisible only, if defined.
10 - 9999	(new 7.0) It resizes the grid content maximally to this pixel value, if less than main tag width. Column position is the same as 3.
	Useful to not hide some buttons on toolbar (e.g. Columns visibility menu), when grid is too narrow due hidden many columns
	For example ConstWidth="500" ensures the Toolbar will be at least 500px wide, but when the grid columns together are wider than 500px, it does not resize the grid any more.

It is ignored when set NoHScroll='1'.
If you permit users to hide all columns you should ensure that the columns menu will be still accessible, the simplest way is to set appropriate ConstWidth.
If set, updates height of main tag to fill the whole window. It does not modify grid content height, see ConstHeight.
It cannot be used when ResizingMain is set to 1 or 3 (vertical resizing).
Is possible to have more grids on page (vertically) with MaxHeight set, in this case their height is computed as ratio of their MaxHeight value or as percentage, see MaxHeightPercent.
To let grid maximize its main tag to window height, on your page there must not be:

a) any parent tag (in hierarchy from grid to <body>) with overflow set to hidden, auto or scroll.
b) any parent tag (in hierarchy from grid to <body>) with position:absolute.
c) any tag (except tags included in tag with not visible overflow or absolute position) with height set to percentage (like height:100%).

If the MaxHeight attribute is set in percentage or as ratio
0 - the MaxHeight is ratio of the sum of all these tags in the MaxHeightParent or body - the tags always fill exactly the whole MaxHeightParent or body
1 - the MaxHeight is % of 100%, the 100% is the remaining height in the MaxHeightParent or body
This height will be reserved empty in the MaxHeightParent or body, in pixels.
This space will be always empty when applying MaxHeight.
Offset parent to calculate the height according to, when applying MaxHeight. The id of the tag.
If it not set, the offset parent is document.body or the nearest parent tag with overflow set or absolute position.
The parent must have set fixed height except the <body>!
Sets MaxHeight to the value. Call Update(); after the change.
If set to 1, updates width of main tag to fill the whole parent tag or body. It does not modify grid width, see ConstWidth.
It cannot be used when ResizingMain is set to 2 or 3 (horizontal resizing).
Now it just sets width of main tag to 100%.
The main tag should not have set any padding, border or margin, if required, set them to some parent tag.
Minimal height of main tag in pixels. This value is used when main tag is shrunk because of resizing by user or when applying MaxHeight attribute.
It is also used when main tag has set percentage height in style, but in this case it does not restore the percentage height when tag can be higher!
Minimal width of main tag in pixels. This value is used when main tag is shrunk because of resizing by user or when applying MaxWidth attribute.
It is also used when main tag has set percentage width in style.
Maximal height of main tag in pixels. This value is used when main tag is enlarged because of resizing by user or when applying MaxHeight attribute.
It is also used when main tag has set percentage height in style, but in this case it does not restore the percentage height when tag can be higher!
Maximal width of main tag in pixels. This value is used when main tag is enlarged because of resizing by user or when applying MaxWidth attribute.
It is also used when main tag has set percentage width in style.

Update size according to the content

To shrink or enlarge the main tag according to grid content. set <Cfg NoVScroll='1' NoHScroll='1'/>.
To shrink or enlarge the main tag up to specific size only, set <Cfg MaxVScroll='...' MaxHScroll='...'/>, when grid content reaches this maximum, it shows its scrollbars.
To use your own scrolling behavior set <Cfg NoScroll='1'/>. There will be used scrollbars of parent tag with overflow set or window scrollbars.
If set to 1, the TreeGrid always resizes vertically the main tag to show the entire grid.
When set, a user cannot resize the main tag vertically (ResizingMain ignores 1 or 3). It disables all RelHeight rows and ConstHeight.
Since 13.0 it works also with Paging, ChildParts and AutoPages.
If set to 1, the TreeGrid always resizes horizontally the main tag to show the entire grid.
When set, a user cannot resize the main tag horizontally (ResizingMain ignores 2 or 3). It also disables all RelWidth columns and ConstWidth.
Since 13.0 it works also with ColPaging, GanttPaging and AutoColPages.
If set, resizes vertically the main tag tag to show the entire grid, but only up to the specified size in pixels. Grid behaves in this way:
When grid content is higher than this maximum, it sets the main tag height to the maximum and shows vertical scrollbar.
When grid content is smaller than this maximum, it shrinks the main tag to accommodate the grid only.
When set, it disables all RelHeight rows and ConstHeight.
If set, resizes horizontally the main tag to show the entire grid, but only up to the specified size in pixels. Grid behaves in this way:
When grid content is wider than this maximum, it sets the main tag width to the maximum and shows horizontal scrollbar.
When grid content is smaller than this maximum, it shrinks the main tag to accommodate the grid only.
When set, it disables all RelWidth columns and ConstWidth.
Since 7.0 the event is called also when resizing main tag by NoVScroll, NoHScroll, MaxVScroll and MaxHScroll. But not by NoScroll.
When set, it sets NoVScroll and / or NoHScroll, if there is not enough room to display the grid readable. Bit array.
It is applied after ShrinkStyleSize.
1. bit &1 - Horizontal limit. Sets NoHScroll if the width of any column section is lower than the MinLeftWidth / MinMidWidth / MinRightWidth value.
2. bit &2 - Vertical limit. Sets NoVScroll if the height of visible variable rows count is smaller than MinBodyRows value.
3. bit &4 - Space width limit. Sets NoHScroll if any Space row does not display all its cells fully because too small grid width. The columns must be wider than all the space rows or ConstWidth or RelWidth column must be defined.
4. bit &8 - Reserved
5. bit &16 - If set, sets always both NoVScroll and NoHScroll.
Called before changed NoHScroll or NoVScroll due LimitScroll.
Return true to cancel the change. Return -1 to cancel the change and to not continue (in case the handler calls Update())
clear is set before NoHScroll / NoVScroll is set to false, clear is false before NoHScroll / NoVScroll is set to true.
The handler should not change the grid layout (e.g. show / hide row / column), such action do in setTimeout. id of the tag that scrolls grid instead of Main tag if set NoVScroll or NoHScroll.
For API it is a HTML tag object.
If not set, the whole document body is used.
If set to 1, does not use TreeGrid’s scrollbars. The main tag is always resized to accommodate exactly the grid content.
In this case are used scrollbars of parent tag with overflow set or browser window.
In this case the main tag has automatically set overflow:visible and it must not be changed.

Let a user to control the grid size

To let a user to resize main tag, set <Cfg ResizingMain='3'/>.
The user will resize the main tag, but not the grid content, to update grid content to fill the resized main tag set <Cfg ConstHeight='1' ConstWidth='1'/> or use some row with <I RelHeight='1'/> and column with <C RelWidth='1'/> .
You can set minimal permitted size of the main tag by <Cfg MinTagHeight='...' MinTagWidth='...'/> and maximal size by <Cfg MaxTagHeight='...' MaxTagWidth='...'/>.
If set, main tag can be resized by user by dragging by bottom right edge of toolbar.
= 1 resizes vertically (height), 2 resizes horizontally (width), 3 resizes both sides.
If added 4, it does not hide the table while resizing.
(new 12.0) If added 8 or 12, it hides content also of other grids on page (8 all grids with MaxHeight set, 12 all grids).
(new 12.0) If added 16, it does not use LeftWidth / MidWidth / RightWidth when calculating minimal permitted width.
Extents of main tag are saved to cookies, to suppress it set ResizingMainLap='1'.
Resizing height cannot be done when set MaxHeight or NoVScroll. If set MaxVScroll, the main tag can be resized up to the grid content height.
Resizing width cannot be done when set MaxWidth, NoHScroll. If set MaxHScroll, the main tag can be resized up to the grid content width.
If resizing main tag is permitted, it is also resized automatically if it cannot accommodate the grid (the fixed sections of grid are too high or wide), to preserve displaying "Too small extents" message.
Starts resizing main tag by mouse.
Resizes main tag back to its original size after it was resized by a user.
Called after main tag is resized by a user.
Since 7.0 the event is called also when resizing main tag by NoVScroll, NoHScroo, MaxVScroll and MaxHScroll. But not by NoScroll.

Widths of individual sections

TreeGrid supports scrolling of all three column sections (left, mid, right).
By default is scrolled only the middle (variable) section. Only if the grid cannot accommodate the other section, they are scrolled too.

The algorithm to show scrollbars for sections

1) If there is enough space to show all columns in their original widths, no scrollbar is shown. The widths of sections cannot be resized by a user.
2) If there is no room to show all columns, the sections are resized to their Width (LeftWidth/MidWidth/RightWidth).
3) If there is still no room, the sections without Width are resized to their MinWidth (MinLeftWidth/MinMidWidth/MinRightWidth). Still in the same order.
4) If there is still no room, the sections with Width are resized to their MinWidth. Still in the same order.
5) If there is still no room and vertical pager is displayed, the pager is resized to its MinWidth. Since 11.0 the order of points 4 and 5 was changed.
6) If there is still no room, all sections are resized to their border width only (few pixels). Still in the same order.
7) If there is still no room, the "Too small grid size" message is shown and the grid is disabled.

Synchronize sections widths among more grids

a) If the grids have the same columns, do in all the affected grids:
b) If the grids have different columns, do in all the affected grids:

0	All three column sections can be scrolled, depending on their ...Width attributes presets.
	If the sections are wider than grid, the sections are shrunk and their scrollbars are shown. The section order is [middle,right,left].
1	There is only one horizontal scrollbar spanned for all three column sections and controls only the middle section.
	Only the middle section can be scrolled.
	It was default and only behavior in versions prior to 6.5
	If left and right fixed columns are wider than the grid, "Too small grid size" message is displayed and grid is disabled. No column resize/hide is done unlike versions below 6.5!

Replaced by WideHScroll
If set to 1, the horizontal scrollbar is displayed only below variable columns. It is just visual effect.
Expected maximal width (in pixels) of the left columns section.
If the section content becomes wider, scrollbar is shown.
It can be changed when resizing section, see LeftCanResize.
Since 12.0 if set to 0, it is set to width of all left columns (for RelWidth columns used MinWidth or 0).
Expected maximal width (in pixels) of the middle (variable) columns section.
If the section content becomes wider, scrollbar is shown.
It can be changed when resizing section, see LeftCanResize or RightCanResize.
Since 12.0 if set to 0, it is set to width of all variable columns (for RelWidth columns used MinWidth or 0).
Expected maximal width (in pixels) of the right columns section.
If the section content becomes wider, scrollbar is shown.
It can be changed when resizing section, see RightCanResize.
Since 12.0 if set to 0, it is set to width of all right columns (for RelWidth columns used MinWidth or 0).
Expected minimal width (in pixels) of the left columns section.
The section is not shrunk below this limit, except all other sections reached their minimal width and grid horizontal space is still too small.
Expected minimal width (in pixels) of the middle (variable) columns section.
The section is not shrunk below this limit, except all other sections reached their minimal width and grid horizontal space is still too small.
Expected minimal width (in pixels) of the right columns section.
The section is not shrunk below this limit, except all other sections reached their minimal width and grid horizontal space is still too small.
If and how the column sections can be resized. Individual section resizing permissions are set by LeftCanResize and RightCanResize.
0 - No resizing is permitted, regardless on LeftCanResize / RightCanResize settings,
1 - Resizing can be done by dragging vertical splitter shown between the sections (new 9.2).
2 - Resizing can be done by dragging small vertical splitters between horizontal scrollbars (default behavior prior 9.2).
When and how the edge between left and middle column section can be moved.
0 - Never
1 - Only if the LeftWidth is set and there is scrollbar in left or middle section.
2 - (new 9.2) Always when there is scrollbar in left or middle section.
3 - (new 9.2) Always when there is scrollbar in any section (left, middle, right). The right section width can be also changed if the middle section cannot be resized enough.
4 - (new 11.0) Even if there is no scrollbar and the sections have defined some column with RelWidth='1' or ConstWidth='1' and RelWidthType='1'
The resizing changes LeftWidth and MidWidth, (for 3 and 4 also RightWidth).
The section can be caught and dragged by the place between left and middle scrollbar.
Sections cannot be resized below their Min...Width and above sum of their column widths.
When and how the edge between right and middle column section can be moved.
0 - Never
1 - Only if the RightWidth or MidWidth is set and there is scrollbar in right or middle section.
2 - (new 9.2) Always when there is scrollbar in right or middle section.
3 - (new 9.2) Always when there is scrollbar in any section (left, middle, right). The left section width can be also changed if the middle section cannot be resized enough.
4 - (new 11.0) Even if there is no scrollbar and the sections have defined some column with RelWidth='1' or ConstWidth='1' and RelWidthType='1'.
The resizing changes RightWidth and MidWidth, (for 3 and 4 also LeftWidth).
The section can be caught and dragged by the place between right and middle scrollbar.
Sections cannot be resized below their Min...Width and above sum of their column widths.
In this order the column sections are shrunk if there is no room for them. See the resizing algorithm.
Can be any combination of words left, mid, right; case insensitive.
Starts resizing column section by mouse.
By default is the action attached to OnDragHScrollLeft (left/middle scrollbar), OnDragHScrollRight (middle/right scrollbar).
Called when section (0 - left, 1 - middle, 2 - right) is resized by a user.
It can be called more times during resizing column by a user, for every change.
Called after section (0 - left, 1 - middle, 2 - right) is resized by a user. It is called only once.

Other scrolling attributes and API

Type of scrollbars used in grid. It affects only the base vertical and horizontal scrollbars scrolling the whole grid section.
0 - standard browser scrollbar
1 - normal style scrollbar, 2 - big style scrollbar, 3 - small (simple) style scrollbar
4 - hidden (no) scrollbars, you can assign action Scroll to some drag event to scroll on drag. Scrolling is also possible by mouse wheel or by focus by arrow keys.
Custom scrollbars are not suitable for very large grids with many rows or columns, because the custom scrollbar step is too big for them.
Type of scrollbars used in grid only on touchpad, e.g. on iPad. It affects only the base vertical and horizontal scrollbars scrolling the whole grid section.
It changes value of CustomScroll for tablets only.
0 - standard browser scrollbar
1 - normal style scrollbar, 2 - big style scrollbar, 3 - small (simple) style scrollbar
4 - hidden (no) scrollbars, you can assign action Scroll to some drag event to scroll on drag. Scrolling is also possible by mouse wheel or by focus by arrow keys.
For tablets only.
Since 12.0 it is deprecated to control the tablets by one finger.
Predefines behavior of scrolling action (DragXRow and DragXGrid). When set, users can change this setting also via configuration menu.
By default it is empty to not modify the <Actions> settings.
0 - No scroll action, scrolling can be done only by scrollbars.
1 - Scroll by one finger, it replaces default iPad screen move.
2 - Scroll by two fingers, it replaces default iPad zooming, it is default grid behavior.
3 - Scroll by three fingers, it replaces grid row dragging.
For tablets only.
If set, uses momentum scrolling on WebKit tablets by -webkit-overflow-scrolling: touch;
If set, it always disables the ScrollAuto action and uses default tablet scrolling.
The momentum scrolling scrolls also when finger is out the tablet, until it is stopped by next touch.
Since 12.1 if set to 2 disables the momentum scrolling if some TreeGrid dialog is opened to avoid Safari bug that scrolls the grid behind the dialog. The value 2 can slightly slow down the dialog display and old iOS it blinks.
Since 12.1 if set to 3 it behaves like 2 on Safari 8+ and like 1 on older Safari.
Presets different value of CustomScroll for horizontal scrollbar(s).
If set to 1, the horizontal scrollbar is not visible and it cannot be used by a user to scroll the grid horizontally.
All other scrolling ways (by focus, by API) are still possible like the scrollbar is visible.
It can be used to hide the scrollbar and provide custom way for horizontal scrolling, e.g. some buttons.
Since 7.0 it sets CustomHScroll = '4'
If set to 1, the horizontal scrollbar(s) is still visible even if it is not required.
If set to 1, the vertical scrollbar is still visible even if it is not required.
It automatically sets <Cfg ConstHeight='1'/> if not set and no RelHeight row exists. Ignored when set NoVScroll or MaxVScroll.
Set it to 1 if there are many columns with RelWidth and showing / hiding vertical scrollbar slows down the grid, especially for tree.
If set, to this will be all vertical scroll steps rounded.
For example set it to 18, if your rows are 18 pixels high (default in many styles) to scroll always to the whole rows.
If set to 0, TreeGrid scrolls down if the children are not shown all.
If set to 1, when expanding row, does not scroll into view the row's children - the icon always stays under mouse cursor.
Since 7.0 the default value is 1. If mouse wheel scrolls the grid body if mouse is above other grid section.
0 - never, 1 - also if above Head or Foot section, 2 - also if above inner space row (Space=1,2), 3 - also if above other space row (Space=0,3,4), 4 - also if above outer space row (Space=-1,5), 5 - also if above side pager, 6 - also if above outside space (with Tag set).
Set it to 1 if the grid is placed in tag with CSS position:fixed;
Starts scrolling grid section (columns or rows) under mouse cursor. Scrolls in both directions.
See also CustomScroll and TouchScroll attributes.
Since 13.0 if set NoHScroll or NoVScroll it scrolls the whole window or ScrollParent.
Starts scrolling grid columns section under mouse cursor. Scrolls horizontally.
If set NoHScroll it scrolls the whole window or ScrollParent.
Starts scrolling grid variable rows section if it is under mouse cursor. Scrolls vertically.
If set NoVScroll it scrolls the whole window or ScrollParent.
Starts scrolling grid section (columns or rows) under mouse cursor. Scrolls in both directions.
If the scrolling shift is too small, it does nothing and permits default action.
Use with NoVScroll or NoHScroll to have default scroll in one direction and TreeGrid scroll in the other direction.
For example on iPad set <Cfg NoVScroll='1'/> <Actions OnDrag1Row="ScrollAuto"/> to use default vertical scroll for whole page and horizontal scroll for individual column sections (e.g. Gantt chart).
Since 12.0 it is not attached to any event by default to use default scrolling behavior. You can attach it to OnDrag1Row and OnDrag1Gantt events for behavior prior to 12.0.
It is disabled on tablets if set MomentumScroll (it is on by default).
The same action like ScrollAuto, but in Gantt it works only if no Gantt object is focused.
To avoid unwanted scroll when misses the Gantt object while trying to drag it.
Usually used with TouchClearFocused set to some short time.
Called after body was scrolled
hpos1 is new middle scrollLeft, vpos is new scrollTop, oldhpos1 is original middle scrollLeft, oldvpos is original scrollTop, all in pixels.
(new 6.5) hpos0, oldhpos0, hpos2, oldhpos2 are values for left and right column section.
Updates grid layout, especially scrollbars.
Call it after all changes inside or outside the grid that affect grid size and are not recognized by the grid automatically or to update layout immediately after the change occurs.
Call it if you modify cell content directly without API and the cell changes its height. Or when you do some action that resizes main tag.
Returns true for success and false if grid cannot be shown and the error message "Too small extents" is displayed.
Updates information about position and size of the parent tags - the absolute position of grid on page. Updates also all absolute cursor positions.
Call it after all changes outside the grid that affect grid position and/or size and are not recognized by the grid automatically or to update layout immediately after the change occurs.
Call it if you modify html page layout and grid main tag moves inside page flow to another position. Or when parent tag with overflow set (if any) resizes.
Call it especially when grid is placed inside tag with overflow set or grid does not show scrollbars (<Cfg NoScroll='1' or NoHScroll='1' or NoVScroll='1'/>). Scrolls grid to show the cell [row,col]. The grid is scrolled as little as possible to show the cell.
If row represents a page set pagepos to expected row's position (index) at this page (when server paging used and page is not loaded yet).
If you want to scroll to exact position, you can use SetScrollTop and GetRowTop methods.
Returns an array of all rows actually visible by scroll.
Returns an array of all column names actually visible by scroll.
(new 6.5) The sec is column section (0 - left, 1 - middle, 2 - right)
Initial horizontal scroll of middle (variable) columns, in pixels.
Initial horizontal scroll of left columns, in pixels.
Initial horizontal scroll of right columns, in pixels.
Returns actual horizontal scroll of body, in pixels.
(new 6.5) The sec is column section (0 - left, 1 - middle, 2 - right)
Sets new horizontal scroll of body, in pixels.
(new 6.5) The sec is column section (0 - left, 1 - middle, 2 - right)
Returns position of column within its section, in pixels
The return value can be used to SetScrollLeft method to scroll exactly to the column.
Returns inner width of the variable columns area (clientWidth of the body).
Can be used width GetColLeft and GetScrollLeft to compute exact visibility and position of some variable column.
(new 6.5) The sec is column section (0 - left, 1 - middle, 2 - right)
Returns scroll width of the given columns area - sum of all visible columns Width in the given area.
Initial vertical scroll of body, in pixels.
Returns actual vertical scroll of body, in pixels.
Sets new vertical scroll of body, in pixels.
Returns position of variable row or page within body, in pixels.
The return value can be used to SetScrollTop method to scroll exactly to the row.
Returns inner height of the variable rows area (clientHeight of the body).
Can be used width GetRowTop and GetScrollTop to compute exact visibility and position of some variable row.
Returns scroll height of the body - sum of heights of all pages.
If grid is rendering now.
You should not call any API function that modifies TreeGrid HTML while it is rendering (or Loading).
You can set Rendering to true, if you plan to show or hide many rows to speed up the action. After finish, you need set Rendering to false and call function Update to update grid layout.