TreeGrid v6.0
Grid size and scroll
Describes how to control width and height of the whole grid and when and how to scroll its content.
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’.
<Cfg> bool ExactSize [1] new 6.0 .
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.
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=’...’/>.
<Cfg> bool ConstHeight .
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 !
<Cfg> int ConstWidth [4] chg 7.0 .
If set, it adds new white RelWidth 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” RelWidth=’1’/> 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 into 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 - 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.
<Cfg> int MaxHeight .
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%).
<Cfg> bool MaxHeightPercent new 6.0 .
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
e.g. two rows with MaxHeight=’20’ and MaxHeight=’30’ will be high 20/(20+30) = 0.4 and 30/(20+30) = 0.6
1 - the MaxHeight is % of 100%, the 100% is the remaining height in the MaxHeightParent or body
e.g. two rows with MaxHeight=’20’ and MaxHeight=’30’ will be high 20% and 30% and there will be empty space with 50% remaining height.
<Cfg> int MaxHeightReserved new 6.0 .
This height will be reserved empty in the MaxHeightParent or body, in pixels.
This space will be always empty when applying MaxHeight.
<Cfg> string MaxHeightParent new 6.0 .
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>!
<Cfg> bool MaxWidth upd 6.0 .
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.
<Cfg> int MinTagHeight .
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!
<Cfg> int MinTagWidth .
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.
<Cfg> int MaxTagHeight chg 6.0 .
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!
<Cfg> int MaxTagWidth .
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.
<Cfg> bool NoVScroll .
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.
<Cfg> bool NoHScroll .
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.
<Cfg> int MaxVScroll renamed 6.0 .
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, a user cannot resize the main tag vertically (ResizingMain ignores 1 or 3). It also disables all RelHeight rows and ConstHeight.
<Cfg> int MaxHScroll new 6.0 .
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, a user cannot resize the main tag horizontally (ResizingMain ignores 2 or 3). It also disables all RelWidth columns and ConstWidth.
API event void OnResizeMain (TGrid grid) chg 7.0 .
Since 7.0 the event is called also when resizing main tag by NoVScroll, NoHScroo, MaxVScroll and MaxHScroll. But not by NoScroll.
<Cfg> bool NoScroll .
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=’...’/>.
<Cfg> int ResizingMain main tag extents are saved to cookies, avoid it by <Cfg ResizingMainLap=’1’/> .
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
Extents of main tag are saved to cookies, to suppress it set ResizingMainLap=’1’.
Resizing height cannot be done when set MaxHeight, NoVScroll, MaxVScroll.
Resizing width cannot be done when set MaxWidth, NoHScroll, MaxHScroll.
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.
<Actions> GridResize Attached to OnDragResize and OnDragButtonResize, can be attached to OnDrag... events only .
Starts resizing main tag by mouse.
<Actions> GridResizeDefault Attached to OnDblClickResize and OnDblClickButtonResize .
Resizes main tag back to its original size after it was resized by a user.
API event void OnResizeMain (TGrid grid) .
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.
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).
If section has not set its width, it is not resized.
The sections are resized in the order: Mid, Right, Left. So first is resized the middle section to its Width, if there is still no room it continues with right and next width the left one.
3) If there is still no room, the sections without Width are resized to their MinWidth (MinLeftWidth/MinMidWidth/MinRightWidth). Still in order Mid, Right, Left.
4) If there is still no room and vertical pager is displayed, the pager is resized to its MinWidth
5) If there is still no room, the sections with Width are resized to their MinWidth. Still in order Mid, Right, Left.
6) If there is still no room, all sections are resized to their border width only (few pixels). Still in order Mid, Right, Left.
7) If there is still no room, the “Small grid size” message is shown and grid is disabled.
<Cfg> bool WideHScroll [0] new 6.5 .
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 width” message is displayed and grid is disabled. No column resize/hide is done unlike versions below 6.5!
<Cfg> bool ShortHScroll deleted 6.5 .
Replaced by WideHScroll
If set to 1, the horizontal scrollbar is displayed only below variable columns. It is just visual effect.
<Cfg> int LeftWidth Saved to cookies, avoid it by <Cfg SectionWidthLap=’1’/> new 6.5 .
Expected maximal width (in pixels) of the left columns section.
If the section content becomes wider, scrollbar is shown
<Cfg> int MidWidth Saved to cookies, avoid it by <Cfg SectionWidthLap=’1’/> new 6.5 .
Expected maximal width (in pixels) of the middle (variable) columns section.
If the section content becomes wider, scrollbar is shown
<Cfg> int RightWidth Saved to cookies, avoid it by <Cfg SectionWidthLap=’1’/> new 6.5 .
Expected maximal width (in pixels) of the right columns section.
If the section content becomes wider, scrollbar is shown
<Cfg> int MinLeftWidth [50] new 6.5 .
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.
<Cfg> int MinMidWidth [50] new 6.5 .
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.
<Cfg> int MinRightWidth [50] new 6.5 .
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.
<Cfg> bool LeftCanResize [1] new 6.5 .
If left section can be resized by a user.
It can be resized only if it set LeftWidth. The resizing changes LeftWidth.
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.
<Cfg> bool RightCanResize [1] new 6.5 .
If right / middle section can be resized by a user.
It can be resized only if it set RightWidth or MidWidth. The resizing changes MidWidth, or if it is not set, the RightWidth.
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.
<Actions> SectionResize Mouse dragging action, only for OnDrag... event new 6.5 .
Starts resizing column section by mouse.
By default is the action attached to OnDragHScrollLeft (left/middle scrollbar), OnDragHScrollRight (middle/right scrollbar).
API event void OnSectionResize (TGrid grid, int section, int widthchange) new 6.5 .
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.
API event void OnAfterSectionResize (TGrid grid, int section) new 6.5 .
Called after section (0-left, 1 middle, 2 – right) is resized by a user. It is called only once.
Other scrolling attributes and API
<Cfg> int CustomScroll [0] new 7.0 .
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.
<Cfg> int TouchScroll [1] new 7.0 .
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 iPad 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.
<Cfg> int ScrollAction [ ] new 7.0 .
For iPad only.
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.
<Cfg> int CustomHScroll [0] new 7.0 .
Presets different value of CustomScroll for horizontal scrollbar(s).
<Cfg> bool HideHScroll .
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’
<Cfg> bool ShowVScroll .
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.
<Cfg> int RoundVScroll new 7.0 .
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
<Cfg> bool NoScrollAfterExpand [1] chg 7.0 .
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.
<Actions> Scroll Mouse dragging action, only for OnDrag... event new 7.0 .
Starts scrolling grid section (columns or rows) under mouse cursor. Scrolls in both directions.
By default is the action attached to OnDrag2Row for scrolling with two fingers on touchpad (e.g. on iPad).
See also CustomScroll and TouchScroll attributes.
API event void OnScroll (TGrid grid, int hpos1, int vpos, int oldhpos1, int oldvpos, int hpos0, int oldhpos0, int hpos2, int oldhpos2) upd 6.5 .
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
API method bool Update ( ) renamed 6.0 .
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.
API method void UpdatePos ( ) new 6.0 .
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’/>).
API method void ScrollIntoView (TRow row, string col, int pagepos=null) .
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.
API method TRow[] GetShownRows ( ) new 6.0 .
Returns an array of all rows actually visible by scroll.
API method TRow[] GetShownCols ( int sec = 1 ) new 6.0;upd 6.5.
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)
<Cfg> int ScrollLeft Can be saved to cookies if set<Cfg ScrollLeftLap=’0’/> new 6.3 .
Initial horizontal scroll of middle (variable) columns, in pixels.
<Cfg> int LeftScrollLeft Can be saved to cookies if set<Cfg ScrollLeftLap=’0’/> new 6.5 .
Initial horizontal scroll of left columns, in pixels.
<Cfg> int RightScrollLeft Can be saved to cookies if set<Cfg ScrollLeftLap=’0’/> new 6.5 .
Initial horizontal scroll of right columns, in pixels.
API method int GetScrollLeft ( int sec = 1 ) new 6.0;upd 6.5.
Returns actual horizontal scroll of body, in pixels.
(new 6.5) The sec is column section (0 – left, 1 – middle, 2 – right)
API method int SetScrollLeft (int pos, int sec = 1) new 6.0;upd 6.5.
Sets new horizontal scroll of body, in pixels.
(new 6.5) The sec is column section (0 – left, 1 – middle, 2 – right)
API method int GetColLeft (string col) new 6.0 .
Returns position of column within its section, in pixels
The return value can be used to SetScrollLeft method to scroll exactly to the column.
API method int GetBodyWidth ( int sec = 1 ) new 6.2;upd 6.5.
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)
API method int GetBodyScrollWidth ( int sec = 1 ) new 7.0 .
Returns scroll width of the given columns area – sum of all visible columns Width in the given area.
<Cfg> int ScrollTop Can be saved to cookies if set<Cfg ScrollTopLap=’0’/> new 6.3 .
Initial vertical scroll of body, in pixels.
API method int GetScrollTop ( ) new 6.0 .
Returns actual vertical scroll of body, in pixels.
API method int SetScrollTop (int pos) new 6.0 .
Sets new vertical scroll of body, in pixels.
API method int GetRowTop (TRow row) new 6.0 .
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.
API method int GetBodyHeight ( ) new 6.2 .
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.
API method int GetBodyScrollHeight ( ) new 7.0 .
Returns scroll height of the body – sum of heights of all pages.
API variable bool Rendering [0] .
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.