FastGrid layout

FastGrid documentation

FastGrid layout is split to horizontal and vertical Parts.
Horizontal parts named as ColParts define columns and vertical scrollbars.
Vertical parts names RowParts define rows, toolbars and horizontal scrollbars.
Both rows and columns can be sorted, grouped, searched and manipulated in the same way.
Cell values and attributes are defined only in RowParts, in rows and toolbars.

Parts - ColParts and RowParts

Array of horizontal parts in grid. Every part in the array is object with at least id attribute defined.
The individual parts define columns and vertical scrollbar.
Default ColParts content is defined in Defaults.js as:
ColParts:[
    { id:"LeftScroll",Type:"Scroll", Item:"$ItemLeftScroll", Hidden:1 },
    { id:"LeftCols", Type:"Cols", Rel:100000, MinWidth:70, MinWidthResize:21, ExportFixed:1 },
    { id:"FCols", Sealed:0 }, only in Sheet
    { id:"Cols", Type:"Cols", Rel:2, MinWidth:70, MaxAuto:475254, AcceptImages:1 },
    { id:"RightCols",Type:"Cols", Rel:100000, MinWidth:70, MinWidthResize:21 },
    { id:"RightScroll",Type:"Scroll", Item:"$ItemRightScroll" }
    ]
The most of grids don't need to redefine the ColParts, the default definition with three column parts (the middle one maximized) and right vertical scrollbar is often suitable.
The input data can contain more ColParts definitions. The later ColParts definition changes attributes of previously defined parts (by id) and adds new parts to the end.
The ColParts definition can contain first item as { Clear:1 } to clear all previously define col parts.
For example: ColParts:[ {id:"Cols",Rel:0}, {id:"Cols2",Type:"Cols",Rel:1} ] redefines the Cols part with Rel:0 and defines next part Cols2.
Array of vertical parts in grid. Every part in the array is object with at least id attribute defined.
The individual parts define rows, toolbars, column tree and horizontal scrollbar.
Default RowParts content is defined in Defaults.js as:
RowParts:[
    { id:"Top", Type:"Toolbars" },
    { id:"TopScroll", Type:"Scroll", Item:"$ItemTopScroll", Hidden:1 },
    { id:"Tree", Type:"Tree", Add:1, Item:"$ItemColTree" },
    { id:"Head", Type:"Rows", ExportFixed:1, Highlight:0, Rel:100000, MinHeight:70, MinHeightResize:0 },
    { id:"FBody", Sealed:0 }, only in Sheet
    { id:"Body", Type:"Rows", Rel:2, MinHeight:70, MinHeightResize:0, Sealed:0, Group:"", NoData:"$NoData", MaxAuto:3000000, AcceptImages:1 },
    { id:"Foot", Type:"Rows", Rel:100000, MinHeight:70, MinHeightResize:0 },
    { id:"BottomScroll", Type:"Scroll", Item:"$ItemBottomScroll" },
    { id:"Bottom", Type:"Toolbars" }
    ]
The most of grids don't need to redefine the RowParts, the default definition with three row parts (the middle one maximized), top and bottom toolbar, top column tree and bottom horizontal scrollbar is often suitable.
The input data can contain more RowParts definitions. The later RowParts definition changes attributes of previously defined parts (by id) and adds new parts to the end.
The RowParts definition can contain first item as { Clear:1 } to clear all previously define col parts.
For example: RowParts:[ {id:"Body",NoData:""}, {id:"NextRows",Type:"Rows",Rel:1} ] redefines the Body part with NoData:"" and defines next part NextRows.
Unique identification of the part. It must be unique among all RowParts and ColParts.
Under this tag name can be defined content of the part (rows, column, toolbars).
The id must not contain dollar "$" and underscore character "_".
Specifies base type of the part and its content. It can be:
Cols - columns part, defines one or more columns. Can be horizontally scrolled.
Rows - rows part, defines one or more rows. Can be vertically scrolled.
Toolbars - toolbars part, defines one or more toolbars.
Tree - column tree part, special part to show tree to expand / collapse columns.
Scroll - scrollbar part, shows vertical scrollbar if defined in ColTree or horizontal scrollbar if defined in RowTree.
Empty - empty part without any content. It can contain Width or Height attribute to specify its size.
Default value is "Cols" if defined in ColParts and "Rows" if defined in RowParts.
Text shown if the row part does not have any visible rows.
Default is "$NoData" for Body part and empty for all other row parts.
Next part in for iteration. All parts in chain PrevPart / NextPart chain are iterated together. These parts permits e.g. focus rect between the parts.
The chain parts with PrevPart / NextPart must not be closed loop, there must be always the first and the last part in the chain!
Previous part in for iteration. All parts in chain PrevPart / NextPart chain are iterated together. These parts permits e.g. focus rect between the parts.
The chain parts with PrevPart / NextPart must not be closed loop, there must be always the first and the last part in the chain!
If set and the part (rows/columns/toolbars) has no content on start, it is removed.
By default it set 1 to all defined parts except Body.
Places the part before the part with given id.
Use it to move the part to different position than the order in the RowParts or ColParts.
The Next part must be already defined and correctly placed.
For example: RowParts:[{id:"Top",Next:"Body"}] moves the Top part before the Body part.
Places the part after the part with given id.
Use it to move the part to different position than the order in the RowParts or ColParts.
The Prev part must be already defined and correctly placed.
For example: RowParts:[{id:"Top",Prev:"Body"}] moves the Top part after the Body part.
If set, removes all previously defined parts of the same type (row parts or column parts).
Background color of the assigned horizontal (for col part) or vertical (for row part) scrollbar. To color not used scrollbar usually by "header" color.
Border color for outer border of the part. It can be one color as color for all edges or four comma separated values for top, right, bottom, left edge colors; if one edge is missing, no color change is done, e.g. ",header,,#FF00FF"
It is read from column part before row part. Border color for outer border of the part set. The {Part id} can be row part id if set in column part or column part id if set in row part id.
It is read from column part before row part. If set, it is preferred to BorderColor.
If is ignored for bottom line in horizontal scrollbar and for all borders in toolbars part or empty horizontal part. Border color for outer border of the part used when printed, preferred to BorderColor.
Border color for outer border of the part set used when printed, preferred to BorderColor{Part id}.
Definition of one ColPart / RowPart, base set. It can contain array of rows, columns or toolbars.
The tag name is the Part id.
By default there are three column sections: LeftCols, Cols, RightCols,
three row sections: Head, Body, Foot
and two toolbar sections Top, Bottom.
It is possible to redefine the parts in ColParts and RowParts.
The Part array can contain items specified by its Type.

It is possible to define the Part in more tags with different suffix "_xxx" and / or in more input files, the Part content arrays are merged in order they are defined.
It is also possible to define the Part tag as object with attributes, to set the Part attributes instead of its content.
For example:
Body: [ {id:1}, {id:2} ], ...
Body_attrs: { Height:100, MinHeight:50 }, ...
Body_new: [ {id:3}, {id:4}, {id:5} ]
Default row part id. The row part must exist. Used when some row has not specified the part it belongs to. Default column part id. The column part must exist. Used when some column has not specified the part it belongs to. It is faster but less universal and safe than Get.
Returns value of attribute attr of given Part part (id of the Part).
Returns null for error - for not existing part, attr or set.
If set set (id of the Set), returns attribute of given Set in the Part.
It is faster but less universal and safe than Set.
Sets value of attribute attr of given Part part (id of the Part) to value.
Returns true if the attribute was changed and Paint() is required or false if the attribute had the value already.
Returns null for error - for not existing part, attr or set.
If set set (id of the Set), sets attribute of given Set in the Part.
Adds or moves given part before the next part.
part can be an object to create and add new part. The part object should have set at least id and Type.
part can be a string to move existing part or add new part with the id = part and Type = "Rows" or "Cols".
next can be also 0 to add to end of RowParts or 1 to add to end of ColParts.
Returns id of the added or moved part.
Removes the part and all its rows / column / toolbars. Hides / shows given row or column part. hide = 0 - shows, 1 - hides, null - changes the visibility. Initial visibility of the scrollbar can be set by the part Hiden attribute.
It does the change immediately, but for parts except scrollbars it does need Paint.

Part size

If set, resizes / shrinks the part width (ColParts) or height (RowParts) to fill the whole grid width / height.
If more parts have set Rel attribute, their widths/heights are resized according their Rel ratio (except Rel values 1 and -1).
If the part contains columns / rows with attribute Rel set, the part width/height change resizes also the columns / row.
If set Rel value negative, it is taken as positive, but the part cannot be resized beyond its content even if it contains columns / rows with attribute Rel. In this case the Rel columns/rows are used only to fill Fix>0 and MinWidth / Width / MinHeight / Height.
If Rel > 1 or Rel <- 1 or Rel = 1 and part contains some column/row with Rel set, the base ratio is 0 and if main tag has not set width/height, the part is resized to 0!
To use Rel values as ratio to resize more parts the main tag must have set width/height and no Rel have value 1 or -1.
Default is 1 in Body and Cols parts and 0 in other parts.
If the part width (ColParts) or height (RowParts) can be higher than the part content.
It will add empty space to the rest or resizes columns / rows with Rel attribute.
0 - no
Part size is between 0 - Width / Height (or MaxWidth / MaxHeight or unlimited) according to the part content.
Part resize by Rel is between MinWidth / MinHeight (or 0) - Width / Height (or MaxWidth / MaxHeight or unlimited).
1 - fix MinWidth / MinHeight
Part size is between MinWidth / MinHeight (or 0) - Width / Height (or MaxWidth / MaxHeight or unlimited) according to the part content.
Part resize by Rel is between MinWidth / MinHeight (or 0) - Width / Height (or MaxWidth / MaxHeight or unlimited).
2 - fix Width / Height
Part size is always Width / Height regardless on the part content (or like 1 if not defined Width / Height). Also for resize by Rel.
If set to 1, the part is not displayed. It can be set also to scrollbar part (Type="Scroll").
If the part width / height can be resized by mouse dragging scroll bar edge.
Width of col Part in pixels. Its usage depends on part Fix and Rel values.
It can be changed by users when resizing the part (by dragging part edge in horizontal scrollbar).
Sets given width to the part Width. If set max, sets MaxWidth instead of Width.
Returns actual width of the part without its border in pixels. Similar to clientWidth. Returns actual width of the part content in pixels. Similar to scrollWidth.
If the part has no horizontal scrollbar, it is equal to GetPartWidth return.
Minimal width of col Part in pixels. Its usage depends on part Fix and Rel values.
Minimal width of col Part in pixels for resizing by mouse dragging. It is used instead of MinWidth.
To ignore it and use MinWidth, set it to null or to -1.
Maximal width of col Part in pixels. Its usage depends on part Fix and Rel values.
Maximal width of col Part in pixels for resizing by mouse dragging. It is used instead of MaxWidth.
If set to 1, it permits resizing the col part without limit.
If set to >1, it permits resizing the col part to this limit in pixels.
If set to -1, it permits resizing the col part without limit and changes the part MaxWidth instead of Width.
If set to <-1, it permits resizing the col part to this limit as positive in pixels and changes the part MaxWidth instead of Width.
Negative value is expected to use with max width of the grid tag set by Cfg MaxWidth.
Minimal width of all Rel columns in the part.
Height of row Part in pixels. Its usage depends on part Fix and Rel values.
It can be changed by users when resizing the part (by dragging part edge in vertical scrollbar).
Sets given height to the part Height. If set max, sets MaxHeight instead of Height.
Returns actual height of the part without its border in pixels. Similar to clientHeight. Returns actual height of the part content in pixels. Similar to scrollHeight.
If the part has no vertical scrollbar, it is equal to GetPartHeight return.
Minimal height of row Part in pixels. Its usage depends on part Fix and Rel values.
Minimal height of row Part in pixels for resizing by mouse dragging. It is used instead of MinHeight.
To ignore it and use MinHeight, set it to null or to -1.
Maximal height of row Part in pixels. Its usage depends on part Fix and Rel values.
Maximal height of row Part in pixels for resizing by mouse dragging. It is used instead of MaxHeight.
If set to 1, it permits resizing the row part without limit.
If set to >1, it permits resizing the row part to this limit in pixels.
If set to -1, it permits resizing the row part without limit and changes the part MaxHeight instead of Height.
If set to <-1, it permits resizing the row part to this limit as positive in pixels and changes the part MaxHeight instead of Height.
Negative value is expected to use with max height of the grid tag set by Cfg MaxHeight.
If row parts can be resized by dragging their bottom edge in the vertical scrollbar area.
If column parts can be resized by dragging their right edge in the horizontal scrollbar area.
Width on horizontal scrollbar and height on vertical scrollbar of the part resize area.
The resize area is placed on both edges of every scrollbar and dragging this area resizes the part (Height and Width attributes).
It can be set to comma separated string or array of column part ids.
Cells in the listed parts can overlay the cell in the next column part (if listed too).
Only cells containing HTML tags in value (and with Type="Html" or Type="Auto" plus AutoHtml = 1) or cells with set attribute Static / TextFont / TextSize / TextStyle / Align>=16 will be affected.
Note, all the cells that can overlay to the next column part also overlay all the next cells in the same column part.
The border between the column parts can be removed by setting BorderColor. Border between cells inside part can be removed by ColBorder.
Use for parts containing only special rows like Sticky usually with Static cells.

Part scroll position

Horizontal scroll position in column part in pixels on start. Column id to scroll to this column on start. The column will be the first left column in the view.
Returns horizontal scroll position in given column part. Sets horizontal scroll position in given column part. Vertical scroll position in row part in pixels on start. Row id to scroll to this row on start. The row will be the first top row in the view.
Returns vertical scroll position in given row part. Sets vertical scroll position in given row part. &1 - If set, ignores ScrollTop, ScrollTopRow, ScrollLeft, ScrollLeftCol attributes on start. Ignores also scroll settings in xlsx.
&2 - If set, does not scroll to focused cell on start.
If set, hides vertical scrollbar(s), if not needed. It can slow down paint after row manipulation.
If set, hides horizontal scrollbar(s), if not needed. What will be scrolled when mouse drags above the part. Scrolls vertically for row part and horizontally for column part.
It is array or comma separated string with these items: [bound1,scroll1,scrollpart1,bound2,scroll2,scrollpart2,bound3,...]
If set to empty string or array, it disables the scroll on drag for this part.

boundX - the scrollX is applied if mouse is between 0 and boundX on actual actual row / column part. Positive value of boundX is taken from left / top, negative value is taken from right / bottom.
The array is tested from start and the first suitable boundX is used and its scrollX is applied, the next items are ignored.
scrollX specifies how much will be scrolled, positive value scrolls down, negative value scrolls up.
scrollpartX is id of the part to scroll, if empty or omitted, it scrolls actual part.

If the boundX or scrollX value is >1, it is value in pixels.
If the boundX or scrollX value is <=1, it is taken as ratio of the part width / height.
If the boundX or scrollX value is ends by "%" (e.g. "50%"), it is used as percentage of default column width / row height.

For example "15,100%,30,3,-15,-100%,-30,-3", for range 0-15 scrolls the same part by one row/column, for range 15-30 scrolls by 3 pixels.
For example "0.5,100%,Body,1,1,Body", for range 0-50% scrolls Body by one row down, for range 50% - 100% scrolls Body by one page.

If and how will be scrolled parts vertically when dragging their top and bottom edge. Format the same as ScrollOnDrag.
If and how will be scrolled parts horizontally when dragging their left and right edge. Format the same as ScrollOnDrag.
If set, shows in the appropriate row cell the values of parent(s) of the first row displayed in the part view. Similar behavior to CSS position: sticky.
It is id of any row or toolbar in grid.
The row cell, where to display the information from parents is set by StickyCol or if not set and it is row and not toolbar, uses StickyTree or Tree. This cell should have set Static = 1 to speed up its update!
Note that the static cells can also overlay to the next column part cells if set OverlayParts.
This row is automatically hidden, if the part has not set Tree.
For more complex sticky behavior use event OnScroll (optionally with OnGrouped) instead of the StickyRow attribute.
Column or toolbar cell where to display the values in StickyRow.
It must be set for toolbar. If not set for normal row, the StickyTree or Tree is used.
Column from which are read the parent values. The parent values are joined by $StickySeparator text.
If not set, Tree is used.
What movement is done on scrolling by mouse wheel (vertical).
0 - no scroll, 1 - scroll only in chosen direction, 2 - if not possible to scroll vertically, scrolls horizontally, 3 - like 1, but never scrolls page or grid parent when no scrolling in grid is available.
If set and scrollable part scrolled by touch cannot be scrolled more or at all in given direction, it permits scrolling its scrollable parent tag or body. &1 - horizontally, &2 - vertically.
Fix scroll change to whole rows or block heights. Used only if scrolled by scrollbars or by mouse wheel.
It also sets number of rows to fix scroll to, e.g. 2 fixes to every the second row, useful for Alternate.
Options for FixedScroll.
1+2. bit &3 - 0 - no fixed scroll, 1 - fixed large scroll, 2 - fixed large and wheel scroll, 3 - fixed all scroll.
3. bit &4 - Rounds scroll position to the whole rows - the grid will always display the whole row on top its row part.
How many pixels should be scrolled for large scroll, used by FixedScrollType.
Called on scroll if FixedScroll is applied.
Use to fix scroll only to specific row, to fix the scroll to block of rows. The block should be enough narrow, only a few rows, to not break the scrolling! Return the row or different row to fix the scroll position on it.
change is the scroll change in pixels, negative up, positive down. Called after any scroll position in grid changed.
rowpart is affected row part, the top is its actual scroll position and oldtop is previous scroll position.
colpart is affected column part, the left is its actual scroll position and oldleft is previous scroll position.
Usually is scroll in one direction only, so top equals to oldtop or left equals to oldleft.

Sets

Every grid has one base RowSet (set of rows) and one base ColSet (set of columns).
The rows / columns and attributes in base sets are defined directly in the Part.
The most of grids don't use other row and column sets, they have only the two base sets.
The rows / columns and attributes for the other sets are defined in PartSet named as Part_id+"$"+Set_id.
Definition of one ColPart / RowPart, specified set. It can contain array of rows or columns.
The tag name is the Part id + '$' + setid.
The setid must be unique among all row and col sets in grid. The setid is defined just by using it in this definition. The setid must not contain underscore character "_".
The specified ColSet is used for rows with attribute S="setid".
The specified RowSet is used for ColPart with attribute S="setid".

It is possible to define the PartSet in more tags with different suffix "_xxx" and / or in more input files, the PartSet content arrays are merged in order they are defined.
It is also possible to define the PartSet tag as object with attributes, to set the Part attributes instead of its content.
For example:
Body$Set2: [ {id:1}, {id:2} ], ...
Body$Set2_attrs: { Tree:"B" }, ...
Body$Set2_new: [ {id:3}, {id:4}, {id:5} ]
It is faster but less universal and safe than Get.
Returns id of ColSet assigned to the row or RowSet assigned to the ColPart part. Use Parts[id] to get particular ColPart.
For base set returns empty string.
Returns null if called with different object than row or part.
It is faster but less universal and safe than Set.
Assigns given set id as ColSet to the row or RowSet to the ColPart part.
If set is not set, assigns base Set.
Returns true for success, false for incorrect set and null if called with different object than row or part.

ColSet

Every row can show specified ColSet in its ColParts. All ColParts in the row always show the same ColSet.
ColSets can be used to display rows with different columns and their width in one grid.
ColSets can be used to display nested grids with different layout in parent grid.
If the specified ColSet does not have definition for some ColPart, it displays columns from the base ColSet.
If row in some ColSet have smaller width than the widest row, empty space is shown in the rest.
Example with three ColSets:

FGrid.Data = {
LeftCols: [ { id:"L" } ],
LeftCols$Set2: [ { id:"L2", Width:120 } ],
Cols: [ { id:"M",Width:90 }, { id:"N",Width:90 }, { id:"O",Width:90 } ],
Cols$Set2: [ { id:"M2", Width:150 }, { id:"N2", Width:120 } ],
Cols$Set3: [ { id:"M3",Width:120 }, { id:"N3", Width:150 } ],
RightCols$Set3: [ { id:"R3" } ],
Head: [ 
   { id:"H1", Kind:"Header", V: { L:"H1-L", L2:"H1-L2", M:"H1-M", M2:"H1-M2", M3:"H1-M3", N:"H1-N", N2:"H1-N2", N3:"H1-N3", O:"H1-O", R3:"H1-R3"} },
   { id:"H2", Kind:"Header", V: { L:"H1-Set2-L", L2:"H1-Set2-L2", M:"H1-Set2-M", M2:"H1-Set2-M2", M3:"H1-Set2-M3", N:"H1-Set2-N", N2:"H1-Set2-N2", N3:"H1-Set2-N3", O:"H1-Set2-O", R2:"H1-Set2-R2" }, S:"Set2" }
   ],
Body: [ 
   { id:"B1", V: { L:"B1-L", L2:"B1-L2", M:"B1-M", M2:"B1-M2", M3:"B1-M3", N:"B1-N", N2:"B1-N2", N3:"B1-N3", O:"B1-O", R3:"B1-R3" } }, 
   { id:"B2", V: { L:"B2-L", L2:"B2-L2", M:"B2-M", M2:"B2-M2", M3:"B2-M3", N:"B2-N", N2:"B2-N2", N3:"B2-N3", O:"B2-O", R3:"B2-R3" } }, 
   { id:"B1-Set2", V: { L:"B1-Set2-L", L2:"B1-Set2-L2", M:"B1-Set2-M", M2:"B1-Set2-M2", M3:"B1-Set2-M3", N:"B1-Set2-N", N2:"B1-Set2-N2", N3:"B1-Set2-N3", O:"B1-Set2-O", R3:"B1-Set2-R3" }, S:"Set2" },
   { id:"B1-Set3", V: { L:"B1-Set3-L", L2:"B1-Set3-L2", M:"B1-Set3-M", M2:"B1-Set3-M2", M3:"B1-Set3-M3", N:"B1-Set3-N", N2:"B1-Set3-N2", N3:"B1-Set3-N3", O:"B1-Set3-O", R3:"B1-Set3-R3" }, S:"Set3" },
   ],
Foot: [ { id:"F1-Set3", V: { L:"F1-Set3-L", L2:"F1-Set3-L2", M:"F1-Set3-M", M2:"F1-Set3-M2", M3:"F1-Set3-M3", N:"F1-Set3-N", N2:"F1-Set3-N2", N3:"F1-Set3-N3", O:"F1-Set3-O", R3:"F1-Set3-R3"}, S:"Set3" } ]
};

ColSet id displayed in this row. The columns for the ColSet are defined in {Part id}${Set id}
Only for RowPart Type="Tree".
ColSet id its tree is displayed in this row part. The columns for the ColSet are defined in {Part id}${Set id}

RowSet

Every ColPart can show specified RowSet in its RowParts. All RowParts in the ColPart always show the same RowSet.
If the specified RowSet does not have definition for some RowPart, it displays rows from the base RowSet.
If ColPart in some RowSet have smaller height than the highest ColPart, empty space is shown in the rest.
Example with three RowSets:

FGrid.Data = {
   ColParts: [ { id:"LeftCols", S:"Set2" }, { id:"RightCols", S:"Set3" } ],
   LeftCols: [ { id:"L" } ],
   Cols: [ { id:"M" }, { id:"N" } ],
   RightCols: [ { id:"R" } ],
   Head: [ { id:"H1", Kind:"Header", V: { L:"H1-L", M:"H1-M", N:"H1-N", R:"H1-R"} } ],
   Head$Set2: [ { id:"H1-Set2", V: { L:"H1-Set2-L", M:"H1-Set2-M", N:"H1-Set2-N", R:"H1-Set2-R" } } ],
   Body: [ { id:"B1", V: { L:"B1-L", M:"B1-M", N:"B1-N", R:"B1-R" } }, { id:"B2", V: { L:"B2-L", M:"B2-M", N:"B2-N", R:"R2-R" } }, { id:"B3", V: { L:"B3-L", M:"B3-M", N:"B3-N", R:"R3-R" } } ],
   Body$Set2: [ { id:"B1-Set2", V: { L:"B1-Set2-L", M:"B1-Set2-M", N:"B1-Set2-N", R:"B1-Set2-R" } } ],
   Body$Set3: [ { id:"B1-Set3", V: { L:"B1-Set3-L", M:"B1-Set3-M", N:"B1-Set3-N", R:"B1-Set3-R"} } ],
   Foot$Set3: [ { id:"F1-Set3", V: { L:"F1-Set3-L", M:"F1-Set3-M", N:"F1-Set3-N", R:"F1-Set3-R"} } ]
   };

RowSet id displayed in this ColPart. The rows for the RowSet are defined in {Part id}${Set id}