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 upd 6.0 .
If set 1, updates width of grid to fill whole main tag. It does not modify main tag height, see MaxWidth.
It is ignored when set NoHScroll=’1’.
In fact it adds to grid new column <RightCols><C Name=“_ConstWidth” RelWidth=’1’/></RightCols>. It is positioned as the first right fixed column.
If there is no right column in grid or the ConstWidth is set to 2, it positions the ConstWidth column as the most right variable colum in Mid section.
To better control the grid width, use RelWidth attribute of existing columns instead of using ConstWidth attribute.
If grid already contains some column with RelWidth attribute set, the ConstWidth attribute is ignored.
<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.
<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.
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> 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> 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.
<Cfg> bool NoScrollAfterExpand .
If set to 1, when expanding row, does not scroll into view the row’s children – the icon always stays under mouse cursor
By default TreeGrid scrolls down if the children are not shown all.
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)
<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 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.
.