News in version
TreeGrid Gantt chart SpreadSheet Examples Documentation Download Development Licensing Prices References Contacts Buy Try it free
Documentation
Search in documentation
TreeGrid versions compatibility

Changes log (txt file) Upgrading from 9.3 to 10.0 Upgrading from 5.9 to 6.0

Creating grid

Simple examples Basic information Creating grid Deleting grid Reloading grid Rendering grid Accessing grid by API

Data & communication
Data communication with server

Communication types AJAX communication AJAX SOAP envelope Submit communication Directly included data Cross domain / local load by JSONP Sessions (AJAX) Server response (AJAX) Synchronous communication (AJAX) Caching (AJAX) API (AJAX)

Download data

Settings for data download Layout XML structure Data XML structure

Upload data

Settings for data upload API for upload XML structure sent to server

Changing data from server

XML structure of download changes XML structure of request for a cell Synchronizing data with server

Input / output data formats

Complete list of tags Internal XML format Short XML format Extra short XML format DTD XML format JSON format

Cells
Cell basics

Cell type Cell format Dynamic format and type Cell value Reading / writing attributes by API Cell HTML Range or more values in one cell Cell with link URL Cell hint Cell tooltip / title Cell popup menu

Cell editing and changing values

Cell editability Defaults list Suggest list (auto complete) Changing cell value Mass cell change Clearing cells Editing cells Controlling <input> tag by JavaScript Input validation and restrictions Side checkbox Cell selecting

Calculations - cell formulas

Basics Formulas Mathematical functions Aggregate functions Special functions for actions Custom functions

Calculations - editable cell formulas

Basics Suggest list (auto complete) Mathematical functions String functions Date functions Summary functions Custom functions

Cell side buttons

Introduction Right side Button Left side Icon

Cell spanning

Column span Row span Dynamic spanning

Cell style and color

Basic grid style Special cell style attributes Cell CSS class Cell background color Dynamic cell border Cell HTML style Row color alteration Cell mouse cursor

Cell types
String - Text, Lines & Pass
Number - Int & Float

Format Localization

Date and time - Date

Format Calendar component Dates dialog Localization

List & combo - Enum & Radio

Introduction Definition Related lists Enum specific Radio specific

Checkbox - Bool
Action button - Button

Introduction Basic clickable button Switch button Radio / tab button Menu button Combo switch button Combo radio / tab button Special Space rows with buttons

Panel with more buttons - Panel

Definition Standard fast panel Custom panel

HTML and special types

Html type Icon type Abs type List type Editable Link type Editable Img type DropCols type Upload File type

Columns

Column basics Column index Column visibility Column visibility menu Column selecting Column tree Column position and moving Column adding and copying Column deleting Column width Column API

Rows
Row basics

Rows by functionality Rows by position Row name Row id Row index

Default rows

Description Example of default rows Example of changing default row Attributes

Row tree

Tree attributes Actions & API for expand / collapse

Row identification

Setting row id attribute Row id attribute in tree Row id created from cell values API for row ids

Row visibility
Row adding and copying

Five ways of adding rows to grid Adding and copying restrictions Adding new empty rows Copying existing rows

Row deleting Row moving and dragging Row selecting Row height Row API Space rows
Features
Sorting rows

Sort settings Controlling sort position Comparing strings Sorting actions Sorting API

Grouping rows to tree

Group settings Creating groups Comparing strings Created group rows <D Group='1'/> User interface to choose grouping Grouping actions and API

Filtering rows

Filter settings Comparing strings User interface to choose filter Filter actions and API

Searching in rows and cells

Search settings User interface for search Search actions and API

Printing grid

Print settings Choosing items to print Page size Print API

Print / export to PDF

Introduction Client side settings Printing options Client side API Server side API Data sent from client to server

Export to Excel or CSV

Introduction Basic settings Communication with server Export API Client export Server export

Copy & paste rows via clipboard

Copy & paste permissions Copying to clipboard Pasting from clipboard

Master - detail grids

Introduction External master - detail grids Nested master - detail grids Synchronizing grids Other attributes for master - detail

Pivot tables

Pivot attributes & API Pivot formulas

External objects (like Adobe Flash) Undo & Redo
Gantt and bar chart
Gantt objects

Gantt objects list Display settings Edit settings

Main bar

Definition of main bar and plans Main bar as Task Edit settings Main bar content and side html Tip on mouse hover Vertical position and height Style specific attributes API to manipulate Main bars Actions Side text (deprecated) Real Flow (deprecated)

Run bar

GanttRun Definition Extended definition Run bar as Task Edit settings Save format Selecting Run boxes Run box content and side html Tip on mouse hover Box identification Vertical position and height Style specific attributes Overlaid (Error) boxes Dragging - moving and resizing API to manipulate Run boxes Actions Run special formulas

Summary task

Main for Main Main for Run Editable Main Editable Run

Gantt icons - Flag & Point

Flag - icon with text Point - math points

Gantt display objects

Header - column captions Cell and column Background Vertical movable Line Mark & Progress line

Gantt zoom

Zoom options Chart size limits Zoom selection Paging in Gantt chart

Dependency, constraints & schedule

Introduction Data units Defining dependencies Dependency colors and shapes Changing dependencies Correcting dependencies Scheduling algorithm Project date constraints Task date constraints Critical path - Slack (Float)

Gantt calendars

Global base calendar Local calendar Calendar list Calendars dialog Other settings

Gantt resources

Resources list Resources assign Resources filter Resources calculations Availability chart Resource usage chart Generated resource usage chart

Gantt popup menu Gantt API
Line and XY points charts

Charts in grid cells Chart JSON definition Base chart settings Basic attributes Size Axis and caption Individual chart lines Data sources Visual settings API for standalone usage

Paging in large grids
Paging root rows

Paging types and attributes Auto adding root pages API for paging

Pager components

Side pager Side pager type Pages Side pager type Gantt Side pager type Custom Pager with navigation buttons & edit Pager as list of page indexes

Paging in tree

ChildPaging - load / render on expand MaxChildren - limit children count ChildParts - load / render on scroll

Paging columns

Paging types and attributes Auto adding column pages API for column paging

Server paging

Server paging for root rows Server communication in root paging Root paging in very large tables Server paging in tree Server communication in tree paging XML Request for Data in root paging XML Download Data in root paging XML Request for root Page / children XML Download root Page / children API for server paging

TreeGrid DLL/SO for server paging

Introduction Compatibility with TreeGrid control Using TreeGrid server DLL/SO ASP.NET C# ASP.NET VB PHP JSP Java TreeGrid server concepts Function reference Calculations

JSON menus and dialogs
JSON menu description JSON menu definition example
Menu settings

Base attributes Visual settings Key navigation Behavior Size and scroll

Menu item settings

Base attributes Clickable item Inactive caption Collapsible sub level Popup sub menu Columns Bool item Enum item Edit item

Custom menu in JavaScript

Show custom menu Custom menu position Custom menu advanced settings Custom menu JavaScript events Custom menu JavaScript methods

Calendar dialog Custom calendar & JavaScript events Custom dialog in JavaScript
Global grid settings
Grid size and scroll

Default behavior Maximize grid height and width Update size according to the content Let a user to control the grid size Widths of individual sections Other scrolling attributes and API Media rules - responsive design

Grid cursor - Focus & hover

Focused cell and row Focused cell range Move and copy focused cells Filling cell values by dragging Tabulator navigation Key navigation Cursor look - focus & hover

Selecting rows, cells and columns

Selecting base Selecting rows Selecting cells Selecting columns

Global settings

Status messages Configuration menus Configuration menu - options Configuration menu - columns Configuration menu - print / PDF Configuration menu - export Default toolbar Language & regional setup (Text.xml) Useful API function Help file

Grid configuration in cookies
Mouse & key events & actions

List of event handler types TreeGrid mouse events Mouse event names Key and mouse button prefixes Touch event names Event targets Assigning event actions / callbacks Event action parameters Calling actions from JavaScript Creating custom actions Focused vs. Actual cell TreeGrid key events JavaScript API events

Mouse API event TreeGrid files
Debugging and testing

Debug window Automated testing

Sorting rows

TreeGrid documentation

Rows in TreeGrid can be sorted by one or more columns. Up to three columns are supported by defaults.
Only variable body rows can be sorted.
The values can be sorted as numbers or as strings, see NumberSort.
Strings can be sorted case sensitive or insensitive. Can be also sorted according to actual browser language or by special settings. See comparing strings.

Sorting can be changed by a user by click to header, see also SortIcons.
Sorting can be preset by <Cfg Sort /> attributes. This attribute is saved to cookies.
Sorting can be changed by API method ChangeSort.
<Cfg> bool

Sorting

[1]
If rows in grid can be sorted.
If set to 0, a user cannot sort grid, also the sort icons in header are hidden.
<Cfg> bool

Sorted

[1] Saved to cookies, to not load it, set SortedLap='1'
If sorting is enabled by a user.
A user can enable / disable sorting by click to sort icon on toolbar (Button named Sort).
<C> bool

CanSort

[1]
If a user can sort rows according to this column.
If set to 0, the column can be still set to Sort by API, but its sorting icon is not visible.
chg 6.0 <Cfg> string[ ]

Sort

[""] Saved to cookies, to not load it, set SortLap='1'
Predefined or actual sorting.
Array of column names (comma separated), according to them are rows sorted, in this order.
By default are column sorted ascending, to sort by column descending, list its name with minus sign, e.g. Sort='Col1,-Col2,Col3' - the second column is sorted descending.
If the first column(s) in this array have set Visible=0 and CanHide=0, a user cannot change sorting for these columns and they will stay the first forever - use this case to predefine some sorting behavior.
renamed 6.0 <Cfg> string

DefaultSort

A column according to that is grid sorted when no other sorting is set or as the last sort column to pre-set row positions to some default state.
This column can be hidden (Visible='0' CanHide='0'). When it is visible, only two columns (see MaxSort) for sorting are available, this default column is always as the third.
renamed 6.0 <Cfg> int

MaxSort

[3]
Maximal count of columns according to grid can be sorted. The more columns the slower sorting.
Different icons are only for first three sorting columns, next columns have the same icon as the third column.
In this count are not included invisible columns (Visible=0 and CanHide=0).
<Cfg> int

SortIcons

[1] Saved to cookies, to not load it, set SortIconsLap='1'
How a user can set sorting and icons are displayed in all headers
0 - hides icons and sorts ascent by click to cell, descent by double click,
1 - shows icons and sorts ascent by click to cell, descent by double click,
2 - sorts by click to icon only, bottom icon ascent, upper icon descent,
3 - sorts by click to cell, bottom part ascent, upper part descent,
To change direction meaning set ReversedSortIcons attribute.
new 6.4 <Header> int

SortIcons

[1]
If and which sort icons will be shown on the header.
0the sort icons are hidden and the caption is inactive, columns cannot be sorted by clicking
1all sorting icons are shown and captions are active
2shows only icons for sorted columns, but all captions are active
<Cfg> bool

ReversedSortIcons

If set to 1, the sort icons for ascending and descending sorting are swapped.
<Cfg> bool

AutoSort

Saved to cookies, to not load it, set AutoSortLap='1'
If set to1, row is automatically sorted (moved) after value is changed by user's edit.
Row can be moved only inside its page.
<Cfg> bool

ReSort

Server paging, output attribute only
This attribute is filled in Request XML as request for re-sorting grid after sorting has been permitted by user.

Controlling sort position

<I> <Root> bool

CanSort

[1]
If row's immediate children can be sorted (to suppress sorting for root rows, you can set this parameter in <Root> tag).
<I> int

SortPos

If set, suppresses sorting of this row and places it always to specified position independently on sorting state.
Positive number places the row from beginning, negative number places the row from end.
Therefore rows with SortPos will be placed in this way: 1,2,3, ... ,all sorted rows without SortPos, ... , -3, -2, -1
If more rows have the same SortPos, they will be sorted inside the group only.
new 6.0 <C> <cell> bool

NumberSort

[null]
Set it to 0 to always sort root rows or row's children according to the column values as strings.
Set it to 1 to always sort root rows or row's children according to the column values as numbers.
If not set, the number sort is chosen for columns of types Int, Float and Date and for all the others is used string sort.
Set it to 1 for Bool type if you want to distinguish between 0 and "", when CanEmpty is set to support three states Bool.
new 7.0 <C> <cell> int

RawSort

[0]
By default for 0 it sorts values formatted according to its Type and Format.
Set it to 1 to sort directly by the unformatted cell value. For Enum with and set by EnumKeys it sorts by the key name.
Set it to 2 for Enum type to sort it by position in Enum / EnumKeys array. It is slower than setting Enum values by index and sorting them as numbers (with NumberSort='1').
upd 6.0 <cell> string

SortValue

Value used for compare when sorting and grouping instead of cell value.
Useful for special non editable cells like Html, Icon, List.
upd 6.0 <cell> string

SortDescValue

Value used for compare when done descending sorting instead of cell value.
Useful to set if you want to preserve row position when sorting by the column.
API event string

OnGetSortValue

(TGrid grid, TRow row, string col, type val, bool desc, bool group)
Called to get value for sorting and grouping, val is predefined value, returns val or new value.
desc is true for descending sorting, group is true when called while grouping.

Comparing strings

You can also specify these settings for whole grid in default column <Def><D Name='C'/></Def>.
new 6.0 <C> <cell> bool

LocaleCompare

[0]
If strings are compared according to browser's locale settings. For sorting, filtering and grouping.
It is done only for first 1920 Unicode characters.
For higher Unicode characters like Chinese, Korean or Japanese you must define CharCodes instead.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.
new 6.0 <C> <cell> bool

CaseSensitive

[1]
If strings are compared case sensitive. For sorting, filtering and grouping.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.
chg 6.0 <C> <cell> string

WhiteChars

List of characters to ignore when sorting, filtering or grouping.
It can be set for example to " " (space) to ignore spaces (it means that for example "a b c" and "abc" strings are the same.
Setting this attribute can slow down sorting, grouping and filtering.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.
upd 6.0 <C> <cell> string[*]

CharCodes

It changes characters in comparing strings for sorting, filtering and grouping.
It is first character separated array of pair of characters to replace the first character by the second when comparing strings.
For example "|y|i|Y|I|.|," - replaces 'y' by 'i', 'Y' by 'I' and '.' by ','
- it means that when comparing strings does not differ between letter 'y' and 'i', both cases and also does not differ between comma and point.
The first character must be one letter, but the second in fact can be any letter or string or even empty string, like "|a|xxx|b||c|ff"
If you use TreeGrid server DLL/SO, there must be the second character one letter only too.
Setting this attribute can slow down sorting, grouping and filtering.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.

Sorting actions

By default TreeGrid sorts according to the last clicked column as the first, the default settings are:
<Actions OnClickSort="SortAsc OR SortDesc" OnClickSortUp="SortAsc" OnClickSortDown="SortDesc"/>

To reverse the sorting order to have the first clicked column as the first sorting column set
When there are more than two seconds between clicks, the sorting is cleared and starts with clicked column
<Actions OnClickSort="SortAscAdd OR SortDescAdd" OnClickSortUp="SortAscAdd" OnClickSortDown="SortDescAdd"/>

To have the same sorting behavior as MS Outlook or Excel, set
On click sorts only by one column, on shift click adds the column to the end of sorting
<Actions OnClickSort="SortAscOne OR SortDescOne" OnClickSortUp="SortAscOne" OnClickSortDown="SortDescOne"/>
<Actions OnShiftClickSort="SortAscAppend OR SortDescAppend" OnShiftClickSortUp="SortAscAppend" OnShiftClickSortDown="SortDescAppend"/>
<Actions>

SortAsc ...F

Attached to events OnClickSort and OnClickSortUp
Sorts according to actual or focused column ascending - adds the column as the first to sorting.
Returns false if the column is already the first column and is sorted ascending otherwise sorts it ascending.
<Actions>

SortDesc ...F

Attached to events OnClickSort and OnClickSortDown
Sorts according to actual or focused column descending - adds the column as the first to sorting.
Returns false if the column is already the first column and is sorted descending otherwise sorts it descending.
new 6.1 <Actions>

SortAscOne ...F

Not attached to any event
Sorts according to actual or focused column only.
Returns false if the column is already the first column and is sorted ascending otherwise sorts it ascending.
new 6.1 <Actions>

SortDescOne ...F

Not attached to any event
Sorts according to actual or focused column only.
Returns false if the column is already the first column and is sorted descending otherwise sorts it descending.
<Actions>

SortAscAdd ...F

Attached to events OnCtrlClickSort, OnCtrlClickSortUp
Adds the actual or focused column to sorting to the end and sorts it ascending.
If the column is already sorted, returns false if it is sorted ascending otherwise sorts it ascending, but does not change its position in sorting.
If there are already three columns sorted, it returns false.
When between clicks are more than two seconds or a user clicks also outside header, it clears sorting and starts from first column again.
<Actions>

SortDescAdd ...F

Attached to events OnCtrlClickSort, OnCtrlClickSortDown
Adds the actual or focused column to sorting to the end and sorts it descending, see the SortAscAdd.
new 6.1 <Actions>

SortAscAppend ...F

Not attached to any event
Adds the actual or focused column to sorting to the end and sorts it ascending.
If the column is already sorted, returns false if it is sorted ascending otherwise sorts it ascending, but does not change its position in sorting.
If there are already three columns sorted, it returns false.
The same as SortAscAdd, but without the two second limit.
new 6.1 <Actions>

SortDescAppend ...F

Not attached to any event
Adds the actual or focused column to sorting to the end and sorts it descending, see the SortAscAppend.
The same as SortDescAdd, but without the two second limit.
<Actions>

NoSort ...F

Not attached to any event
Removes the actual or focused column from sorting and re-sorts grid.
<Actions>

DefaultSort

Not attached to any event
Restores the sorting settings set in input XML data.
If no Sort attribute was set in input XML, it does not do anything.
<Actions>

SortOn

Attached to event OnClickButtonSort
Enables sorting in grid and re-sorts grid. It fails if sorting is already enabled.
<Actions>

SortOff

Attached to event OnClickButtonSort
Disables sorting in grid. It fails if sorting is already disabled.

Sorting API

upd 6.1 API event int

OnSort

(TGrid grid, string col, string sort)
Called when user clicks to header for sort, before grid is sorted by the column.
Return -1 to suppress the action completely.
Return 1 to suppress sorting, provide your own sorting and let change sort icon.
col is clicked column that will be added to sorting, can be null if it was called from control panel (from SortOn action).
sort is the resulted Sort after the col will be added to the actual (added in 6.1).
Here you can call ChangeSort to modify sorting (in this case you have to return -1).

For example this code always sorts according to column named 'B' as second column:
Grids.OnSort = function (G,col){ if(col!='B') { G.ChangeSort((G.Sort.indexOf(col)==0?"-":"")+col+",B"); return -1; } }
API event void

OnSortFinish

(TGrid grid)
Called after grid was re-sorted, all changes are already displayed.
Called only for sorting on client, not for server paging.
chg 6.0 API method void

ChangeSort

(string sortcols)
Sorts grid according to given columns. sortcols is new value for Sort.
If it is called from OnSort event, the event handler must return -1 for proper sort.
API method void

SortClick

(string col, bool desc = null)
Simulates click to sort icon in the given column.
desc can be 0 for ascending and 1 for descending sorting.
API method void

SortRow

(TRow row, string col = null, bool show = false)
Sorts (and moves) one row by actual sort settings.
If col is set, test only this sorting column for changes.
It is ignored when AutoSort is 0.
API method void

SortRows

( )
Sorts all rows, according to sort settings and paging type, asynchronous.
Shows all changes.