Cells

TreeGrid documentation

Cell type

Cell type. Specifies the basic behavior of the cell. How it will be displayed, edited, calculated sorted, filtered and so on.

Editable types

Text	One line text, formatted, edited in <input>.
Lines	Multi line text, formatted, edited in <textarea>, can accept Enters.
Int	Integer number, formatted, edited in <input>
Float	Floating point number, formatted, edited in <input>
Date	Date and / or time, formatted, edited in <input> or selected from popup calendar.
Pass	Password. It is displayed as “***”, editing in <input type="password">.
Img	Editable image. Displayed as <img> tag or as background image in <div>. For simple not editable image use Icon type.
Link	Editable link to any url. For simple not editable link use Link attribute with any type.

Changeable types

Bool	Boolean value 1 and 0 – it is displayed and edited as checkbox.
Radio	Enumeration with radio buttons instead of combo box. Displayed and edited as radio buttons or checkboxes.
Enum	Combo box to select one or more values from menu.
Select	Cell with predefined values chosen from menu. It is shortcut for Button of type Defaults with non-editable Html cell.

Button types

Button	One button in cell: clickable button, switch button, radio / tab button, menu button, combo switch button, combo radio / tab button.
Panel	One or more clickable buttons in cell.

Special interactive types

Pager	Special simple pager cell, only for Space rows. Displays buttons GoFirst,GoPrevious,GoNext,GoLast and editable cell with page number and number of pages.
Pages	Special simple page links, displays links for all pages as numbers from 1.
DropCols	Drop target to drag column names here. Only for cell in Space rows.
Gantt	Interactive Gantt chart. This type must be used for tag only.

Not editable HTML types

Html	Any HTML code displayed as is.
Icon	Simple image.
Abs	HTML elements absolutely positioned inside the cell in layers. It does not affect row height, it is always overflowed.
List	List of items to build an HTML string.

Called whenever grid reads the cell type to change the Type dynamically. It must be very fast.
Return new type or type.
Returns cell Type in string. It just reads all appropriate Type attributes and calls OnGetType.
Use to speed up rendering of simple cells without the most TreeGrid attributes. Bit array.
It has sense only in large grids with many simple cells like numbers, dates or simple strings or HTML.
If set to whole column <C>, it is used only for variable cells, not fixed.

1.bit (&1)	Ignores attributes: CanFocus, CanEdit, Class, NoColor, Color, Background, Wrap, Align, Visible, Link, HtmlPrefix, HtmlPostfix, ClassInner, Rotate.
2.bit (&2)	Sets CanEdit value for bit 1. It means Simple = 1 for not editable cells, Simple = 3 for editable cells.
3.bit (&4)	Ignores Button and Icon and does not show any side button for Enum and Date.
4.bit (&8)	Ignores Format and Type specification, use only for simple not formatted texts or numbers.

For example Simple = 7 shows simple editable cell without side button. Simple = 9 shows simple not editable, not formatted text, but possibly with side button.

Cell format

Cells are formatted according to its type. Individual formats are described in individual types documents. Specifies a cell format for display. Its presence, meaning and structure varies according to the cell type therefore the formats are described for individual types.
See text format (Text, Lines, Pass), number format (Int, Float), Date format, Html format, Img format, Link format, List format, DropCols format. Specifies cell format for editing. Its presence, meaning and structure varies according to the cell type therefore the formats are described for individual types.
See text edit format (Text, Lines, Pass), number edit format (Int, Float), Date edit format, Html edit format, Img edit format, Link edit format. Called to get cell format dynamically. Returns new format or format. It must be very fast.
If edit is false, it should return standard format, for true it should return format for editing.
Returns Format string for given cell. If edit is true, returns EditFormat. Calls also OnGetFormat.

Dynamic format

See also auto Type Auto. If the cell Type, Format and other such attributes can be changed dynamically by users or automatically according to the cell value.
0 - no

1 - yes
The cell format can be dynamically changed by users using actions SetFormat... and ChooseFormat....
It shows also Format combo cell on toolbar.

2 - yes + auto type
Since 13.0 it is replaced by Type Auto.
Like 1 and also chooses cell Type according to cell value. It does not change Auto type.
The Type is chosen: on grid load, after value is edited by a user, after value is calculated by editable formula.
If the Type is changed, it resets also other cell attributes according to TextFormat, NumberFormat or DateFormat.
JSON menu definition with all available formats to be set to cells.
The definition is "{Items:[{format1},{format2},...]}" where formatx object defines these attributes:
Name - unique name of the format definition. It is shown in Format combo value on toolbar; it is use in Format, DateFormat, NumberFormat and TextFormat attributes. Name can be '-' for menu item separator.
Text - menu item text shown in the popup menu or list with the formats.
Type - cell Type attribute; it is set to cell when format item is chosen or by action SetFormat when Format contains this menu item Name. It is ignored for cell type Auto.
Format, EditFormat, EditMask, ResultMask and similar attributes are set to the cell like the Type attribute.
Default value of Formats see in Defaults.xml file.

Since 13.0 it can contain special named items (the attribute Name starts by "@"):
Name="@Enter" - A user can enter custom format string that is used as is in the cell Format attribute.
Name="@Custom" - A item with submenu showing all custom formats in grid and added custom formats. The item must have attributes Menu and Items.
Name="@Refresh" - A user can clear all unused custom formats, it lists only formats used in grid cells.
Predefined format Name from Formats that will be set to cell(s) by SetFormat... action.
If the format can be set dynamically or automatically in the row or column cells.
0 - both automatically and dynamically (like DynamicFormat=2)
1 - only dynamically by users, not automatically according to the cell value (like DynamicFormat=1)
2 - never (like DynamicFormat=0).
By default it is 2 for Header and Panel rows and Index and Panel columns and 0 for other rows and columns.
Starting cell value by this character forces its auto type to "Text" or "Lines".
This first character is not displayed in the cell. Default is apostrophe.
In Auto type it forces to always display the value as string regardless on its Format.
Searches the cell Type and Format in formats menu and returns the item Name if found. Otherwise returns default.
formats has the same format as Formats.
Adds given format string to the Formats value, as a child of the @Custom item.
If the name is set, sets it to the item Name, otherwise the format is set also to the Name.
The format and name can be also arrays to add more items at once.
Sets attributes chosen by Format in Formats to TextColor in actual or focused cell or in all focused cells or in all selected cells.
Shows menu with items in global Formats. If used in Menu, shows submenu with the global Formats.
And sets attributes chosen in the menu to TextColor in actual or focused cell or in all focused cells or in all selected cells.

Dynamic type

Since 13.0 it is replaced by Type Auto.

Dynamic type is active if set <Cfg DynamicFormat="2"/>.
It is used for types Text, Lines, Int, Float and Date. It is not used for Auto type.
Predefined format Name from Formats that will be set to cell(s) when auto choosing the cell Type as "Text" or "Lines" due DynamicFormat='2'.
Predefined format Name from Formats that will be set to cell(s) when auto choosing the cell Type as "Int" or "Float" due DynamicFormat='2'.
Predefined format Name from Formats that will be set to cell(s) when auto choosing the cell Type as "Date" due DynamicFormat='2'.
When it is restricted to convert cell type to Date for DynamicFormat = 2 0 - the type is set as Date if it is positive number less than 4e12, the cell Type is not Float and it is not called from calculating editable formula. Or if the value is a date string (containing only numbers, spaces and date/time separators).
1 - the type is set as Date only if the value is a number and cell Type is Date or the value is a date string.
2 - the type is set as Date only if the value is date string.
3 - the type is never set as Date automatically.
Called to choose cell Type according to the value val. type is suggested Type.
Return new Type according to the value val, permitted types are now "Text", "Lines", "Int", "Float" and "Date".
It is called from FindType method.
(new 12.1) If set calc=1, it is called when calculating editable formula.
Chooses cell Type according to the value val.
Chooses the cell type as text, number or date, reads the TextFormat, NumberFormat or DateFormat and sets all its attributes from Formats to the cell.
Returns the chosen cell Type.
If set refresh=1, refreshes the cell HTML to show the changes.
(new 12.1) If set calc=1, it means calculated from edit formula, it is less restrictive in changing Float to Date.

Cell value

Cell value in the row. It cannot be set into the whole column, to preset default value to more or all rows in some column use default <D> rows.
The value is not an attribute name! The cell value is set as assignment to column name in row, e.g <I Col1=’value of col1’ Col2=’value of col2’ Col2CanEdit=’0’/>.
Floating point numbers always use ‘.’ as decimal separator and no thousands separator.
Date and time values are in XML in string in English format (M/d/yyyy HH:mm:ss) and in API are in number of milliseconds from 1.1.1970 00:00:00.000.
By API you can read the value by GetValue, GetString or by global functions Get or Is.
By API you can set SetValue / SetString. You can set the value also directly by row[col] = val, but without any update and refresh.
Called to get formatted HTML cell value to display. val is unformatted cell value.
Return formatted value as HTML string. If returned value is not null, it is used instead of internal formatting by Format or Enum attributes.
Return null to use default formatting behavior.
Since 13.0 return an array as [value,type,format] to change some or all of the attributes. The value is raw value to be formatted by given or default type and format.
Returns cell value as number or string. For date returns internal format (count of msec from 1/1/1970).
The cell value can be set by SetValue method.
Returns cell value as string, in standard format (non editing).
The cell value as string can be set by SetString method.
Returns cell value as string for editing. If the cell contains EFormula, it returns the EFormula starting by '='.
Call it before mass update of cell values, adding more rows, showing / hiding more rows and so on.
It disables calculations, updating layout, uploading changes with AutoUpdate and updating Gantt chart. It also starts Undo block.
It is possible to nest blocks StartUpdate / EndUpdate - only the call of the most outer block's EndUpdate will enable updating.
Call it after the action for StartUpdate finished.
It enables calculations and recalculates grid. If set row and col it recalculates grid like after change the cell, otherwise it recalculates the whole grid.
It updates grid layout by calling Update.
It enables AutoUpdate and uploads changes to server. If set row, it uploads only changes in the row, otherwise it uploads all changes.
It updates Gantt chart and dependencies.
It closes actual Undo block, all actions within StartUpdate and EndUpdate will be undone or redone together.

Reading / writing attributes by API

Returns value of row’s attribute. Remember, all attributes are often of string types. If the row has not this attribute set, it returns default value from its default row.
To get cell attribute use Get(row,col+"attribute"), e.g. Get(row,"Col1CanEdit")
Returns true if row’s attribute has positive value or returns false for 0, null or empty string. Remember, all attributes are often of string types.
If the row has not this attribute set, it returns default value from its default row.
Returns a cell (<I>), row (<I>) or column (<C>) attribute, in this order.
If row is null, returns only column attribute.
If col is null, returns only row attribute.
If attribute is null, returns cell value as internal value. To get cell value as string use GetString method.
Example: grid.GetAttribute(row,col,"CanEdit");
Sets a cell (<I>), row (<I>) or column (<C>) attribute to the value and refreshes it.
Remember, not all attributes can be set via this method! If there exists a direct API method for setting the attribute, use it instead !
If row is null, sets only column attribute. In this case the refresh of the whole column can be slow!
If col is null, sets only row attribute and refreshes the whole row.
If attribute is null, sets cell value via SetString method.
If set undo adds the change to Undo and can undone and redone. If called for cell value, the undo is always 1.
Example: grid.SetAttribute(row,col,"CanEdit",0,1);

Cell HTML

Refreshes cell’s html element, re-renders the whole cell.
Call it after any change that affects the cell, like when you directly set its value by row[col] or any attribute by row[col+attribute]
Refreshes row’s html element, re-renders whole row.
Call it after any change that affects the whole row, like changing its Class.
The API functions for changing rows like DeleteRow do the changes automatically.
It is faster than refreshing all cells in row by RefreshCell.
Returns HTML cell element, tag <td>.
Don’t change the HTML directly! To change the cell content use some grid method to change data and call RefreshCell.
You should use this method only if you really know what are you doing.
Remember, TreeGrid can anytime re-render the cell and any your custom changes done in the HTML will be lost.

Range or more values in one cell

If the cell accepts a range or more values. Usable especially in filter cell or in Gantt source cells.
Cell types Int, Float and Date accept more values separated by ';' and range of values separated by '~'. For example "1;3~7;12;16~33" or "1/1/2000~3/3/2000;1/1/2007".
Calendar component for selecting date supports selecting more dates or range of dates by mouse drag.
Cell types Enum and Select can select more values from combo box. Defaults dialog supports selecting more values for any cell type.
Cell types Text and Lines accepts more strings separated by ';'.
The characters ';' and '~' can be changed by <Lang><Format ValueSeparator=';' RangeSeparator='~'/></Lang>
The range value should not be used as input for calculations, because formulas treats is as single string.
Sorting of range value is done only according to the first value ascending and the last value descending.
Filtering is done only according to the first value.
Search and group treat the range value as single string.
Separator to separate individual values in Range cell. This separator must not be contained in any individual value.
This separator is used in the value itself and for editing.
The default is semicolon.
A string displayed in cell instead of ValueSeparator in Range cell.
The default is semicolon + space.
It is displayed in Int, Float, Date. Since 9.0 it is displayed also in Enum and Html type.
It is not displayed in Text and Lines type, use their Format attribute to change the separator, e.g. Format="||||\;|g| ... "
Separator to separate the bounds in Range cell. Used only for number types: Int, Float and Date.
This separator is used in the value itself and for editing.
The default is tilde.
A string displayed in cell instead of RangeSeparator in Range cell. Used only for number types: Int, Float and Date and for Html type.
The default is space + tilde + space.

Cell with link URL

Cells can display it content as clickable link (<a href>).
The cell must not be editable to process the link click or the editing must not be started on cell click.
Only types Html, Img, Text, Lines, Int, Float and Date can have a link.
The link URL (<a href>). If set, the cell has a link and browser will be navigated to this link after click to the link.
Remember, the cell must not be editable to process the link click or the editing must not be started on click.
The link target (<a target>). Name of browser window to open the link here.
It can be "_blank" to open in new window or "_top" to open in main frame.
By default the link opens in the same window.
Link base url prefix.
This string is added before the Link. To easily change an url of more links together.

Cell hint

The hint is a complete cell value displayed in place of the cell, if the cell content is bigger than the cell itself.
The hint can also display anything else than the cell content, it can be changed in OnHint event.
The hint is displayed immediately the mouse enters the cell and is displayed until the mouse leaves the cell or click happens or grid enters edit mode or shows dialog.
If the Hint is shown for the cell.
0 - no, 1 - on not fully visible cell due its size, 2 - (new 11.0) also on not fully visible cell due scroll. 3 - (new 12.0) always, should be controlled by OnHint API event.
The Hint is never shown for cell types Bool, Radio, Icon, Pages, Abs, Chart and Gantt.
It is read from row before column.
Hint value to be used instead of cell value. It must correspond with the cell type. It is formatted by the cell format before it is shown in the hint.
If set, shifts the hint left, if there is no room for it on right side. Called when Hint is being displayed for given cell.
Since 12.0 the reason is why the hint is shown, bit array: &1 due width overflow, &2 due height overflow, &4 due cell overflow.
Return new string to display or hint. hint is by default cell html content.
Return null to not display the Hint at all.
Displays value of the actual cell as Hint, only if required and possible.
Displays value of the actual cell as Hint, only if required and possible.
This Hint is static and is not hidden on mouse move, only on mouse click.
Displays cell value as Hint, only if required and possible.
Since 12.0 if set static = 1, the hint is not hidden on mouse move, only on mouse click.
Since 12.0 if set test = 1, the hint is not shown, just tests the possibility.
Since 12.0 it returns true for success.
Hides the actually displayed Hint.

Cell tooltip / title

Tool tip text displayed when mouse hovers the cell.
The tip can contain HTML code except is set StandardTip='1'.
When cell contains Error attribute, the Error string is displayed instead of the Tip.
It can be set to 1 to display cell value as tip.
Since 13.0 it can contain keyword "*Value*" to display the cell value inside the tip text.
Tool tip text displayed for given cell value. The XXX is actual cell value. If such tip does not exist, the normal Tip is displayed.
It has sense especially for Bool or Button types, to show different tooltip for checked / pressed and unchecked / not pressed state.
For example: <C Type="Bool" Tip0="Unchecked" Tip1="Checked"/> Tool tip text displayed for given cell event target. The XXX is actual cell event target under mouse cursor. If such tip does not exist, the normal Tip is displayed.
The XXX can be any event target name, see mouse event targets, for example EditIntTip, ButtonSaveTip, SideDefaultsTip, SideTip, ContentTip and so on.
It is intended to show different tool tip for part of the cell like side or tree button.
An inner class for the tip.
It can be used to show the tip in different classes in different rows, columns or cells.
Position of the tip dialog. By default it is placed under mouse cursor.
You can specify different Align to align it to the cell instead. For example TipPosition='{Align:"left above",Y:-4}' places the dialog above the cell.
See TPosition JSON attributes. The TipPosition automatically contains the actual cell as Tag attribute.
Called when tooltip is being displayed. Return new string to display or tip. Return empty string to not display the tip.
It is called whenever mouse doesn’t move for TipStart milliseconds. It is called only once for the mouse position.
clientX, clientY are mouse coordinates in browser window. X, Y are mouse coordinates inside the cell row, col.
By default is the Tip shown as TreeGrid tooltip. Its behavior can be controlled by other attributes and events. It also supports multiline and HTML tip.
Set it to 1, to show the Tip by standard browser tooltip - by HTML title attribute. All the other settings and events are ignored in this case.
Time in milliseconds before tooltip is displayed while mouse is not moving.
If set to 0, the tip is never displayed, if set to 1, the tip is displayed immediately.
Time in milliseconds when tip will be automatically hidden. It must be higher than TipStart otherwise the tip is never shown.
If it is empty or 0, the tip is never automatically hidden.
JSON setting for tip dialog, similar to TreeGrid JSON menu settings.
For example <Cfg TipDialog="{CloseMove:1000}"/>, never closes the tip just for mouse move.
Shows tip on actual mouse position.
Hides the actually displayed tooltip.

Cell popup menu

An action menu for the cell. It can be displayed on click to the cell, to the panel button, on right click to the cell and so on. It is shown by action ShowMenu (next to the cell) and ShowPopupMenu (on mouse position).
It can contain two item types, action item and custom item.

The action item (since 12.0) is named as some TreeGrid action and this action is run on click to the item.
The action item is automatically hidden, if the action is not suitable for the cell or its actual state.
The action item name can end with @num, it will show the item only if the action will affect at least num items. For example "DeleteRows@2" will be shown only if there are at least two focused rows to delete.

As the action can be used any TreeGrid <Action> except: all dragging actions, all mouse cursor actions, ShowPage (click to pager page), ShowTreeLevel (click Levels button), Invert...First (invert range according to the first cell), Tab... (tab navigation - focus), ChangeRadio (clicked radio button), ButtonUp / ButtonDown (simulated click to Button), Paste (paste from clipboard).
The action item names and their texts are defined in Text.xml, in <MenuCell> tag.

The custom item is any other name than TreeGrid action name. It is always visible.
It can have assigned OnClick action, if the Menu is defined in JSON format to be called after click to the item. The OnClick function can return true to not call the OnContextMenu.
After user clicks to custom menu item it is called OnContextMenu.

The Menu can be first character separated array of menu item names. They can contain any HTML code. Separator can be shown as item named '-'
Or it can be in standard TreeGrid menu format as complex menu with sub levels, sub menus, columns and so on.
See also API ShowMenu function to show custom menu from JavaScript.

By default it is set in <Panel> as PanelCopyMenu, PanelCopyAllMenu, PanelColCopy, PanelColCopyAll and in <Toolbar> as AddMenu, AddChild and AddCol.
Menu for the individual Panel button.
If the menu action items that cannot be run are hidden.
0 no, they are disabled
1 yes, they are hidden
2 yes like 1 and also if the parent item contains only one available child item, the child item is shown instead of the parent.
3 yes like 1 and also the parent items are hidden, if they have no child items
4 yes like 2 and 3. For 1, if the Menu contains only one valid action item, it shows the menu anyway. Otherwise for 0 it does the action immediately without showing the menu. Called to get the popup Menu attribute dynamically by JavaScript.
menu is the original Menu for the cell. It should return new menu string.
Called before the cell Menu is shown.
menu is the TMenu menu object for the cell. position is the menu TPosition object.
The menu and position can be changed in this event. Return true to not show the menu.
Called when user clicks to context menu set by Menu attribute.
result is Value or Name of the clicked item or all values.
Return true to not close the menu.
Displays Menu for the actual or focused cell.
Since 12.0 it processes the menu for TreeGrid actions, for previous behavior use ShowPopupMenuNoActions instead.
Displays Menu for the actual or focused cell on mouse position.
Displays Menu for the actual or focused cell on mouse position.
Shows the menu without processing the action items. Use for compatibility with versions prior to 12.0 Shows message that there is no available menu items. Never fails. Shows custom popup menu on mouse position.
Closes any actually shown dialog in grid.
Menu is string with menu items (first character separated) or TMenu object.
Func is function (TMenuItem I) called after click to the menu. The I has set at least I.Name as the item name. It replaces Menu.OnSave.
If no Func is set, calls Menu.OnSave if defined or OnContextMenu API event.
For more information about the parameters see global function ShowMenu or ShowPopup.
Shows custom menu for given cell.
Closes any actually shown dialog in grid. If there is already dialog shown for this cell and not set always, it closes the dialog and returns null.
Menu is string with menu items (first character separated) or TMenu object.
Func is function (TMenuItem I) called after click to the menu. The I has set at least I.Name as the item name. It replaces Menu.OnSave.
For more information about the parameters see global function ShowMenu.
Shows custom dialog for given cell.
Closes any actually shown dialog in grid. If there is already dialog shown for this cell and not set always, it closes the dialog and returns null.
Dialog is string with HTML to display or TDialog object with dialog settings.
Since 11.0 the parameters changed, although the previous parameter set still work.
Creates and shows new grid as popup dialog for given cell.
data is XML or JSON string to be used as data source to create the grid from. The grid is always created synchronously (Sync=1).
width (new 7.1) is exact width of the main grid tag in pixels. If not set, the grid has set NoHScroll and uses scrollbar of the dialog.
height (new 7.1) is exact height of the main grid tag in pixels. If not set, the grid has set NoVScroll and uses scrollbar of the dialog.
Dialog (since 11.0) is the TDialog object with settings for grid parent dialog.
Pos (since 11.0) is the TPosition with position settings for the dialog.
The grid will get ZIndex = 270 or if the parent has set ZIndex, it will get ZIndex+20.
It returns the popup grid object.
(Since 11.0) popupgrid.ParentGrid returns the parent grid from popup grid.
(Since 11.0) popupgrid.ParentDialog returns the dialog object from popup grid. For example popup.ParentDialog.Close() closes the popup dialog and clears the popup grid.
(Since 11.0) popupgrid.ParentDialog.Row returns the row in parent grid from popup grid.
(Since 11.0) popupgrid.ParentDialog.Col returns the column in parent grid from popup grid.
(Since 11.0) parentgrid.Dialog.Grid returns the popup grid from parent grid. Note, here is an exception, because in other dialogs the Dialog.Grid shows back to the parent grid.
(Since 11.0) parentgrid.Dialog returns the dialog object from parent grid.
Note, this function is expected to show small grids as popup dialog for the source grid. For large popup grids use your own dialogs / windows with dynamically created grid by TreeGrid( ) function.
Closes actually displayed grid popup menu or dialog (Enum, Defaults, Menu, Calendar). Clears the Dialog property.
Closes also custom menus or dialogs shown by ShowPopup, ShowMenu, ShowDialog, ShowCalendar, or ShowPopupGrid.
Actually displayed grid popup dialog or menu.
It is TMenu object with all settings.
Set it if you show custom dialog by global (not TGrid method) API function ShowMenu, ShowDialog or ShowCalendar.
Or set it to you custom dialog object if you create your custom dialog, this object must have defined Close ( ) method that closes the dialog.