JavaScript API Reference

TreeGrid v4.6

This document describes API objects, events and functions to control TreeGrid from JavaScript on client side. The API is needed only to advanced use of TreeGrid, all basic settings can be done by TreeGrid XML data format.

This document describes Extended API and Simple API for the TreeGrid.

Simple API is included in all licenses. Extended API is not included in any license and must be purchased apart.

Every property and function in JavaScript is public, but due to compressing and coding of script are visible just these.

ro means read only property in runtime – you must not change its value.

Members in blue are most important and are also in Simple API.

Members in green are also in Simple API.

Members in brown are important, but are in Extended API only.

Other members in black are in Extended API only.

Grayed members are now disabled.

TreeGrid data structure

In TreeGrid rows are represented as standard object HTMLElement and these elements are grouped to tree as done in input XML data. In Extended API you can iterate through rows as through any HTMLDocument. Every row has standard properties parentNode, nextSibling, previousSibling, firstChild, lastChild, childNodes and so on. But for iteration use predefined methods, as GetNext, GetNextVisible and so on rather then nextSibling or getElementsByTagName, because it is much faster. And for manipulating rows also use predefined functions, not HTMLElement methods.

In this documentation, the row object is named as TRow, but this object in fact does not exist.

All attributes loaded from XML data are in rows represented as properties with the same name as in Internal format (name consists from column name + property name). For example you can access row.Selected or row.Added. There is not predefined type for attributes, it can be string or number, depends on many factors. Therefore if you expect boolean value, you cannot test it as if(row.Selected) but if(row.Selected-0). Some attribute types are converted to internal representation, for example Enum is Array, Formula is function, ... For many attributes is better to read them by predefined methods as CanEdit, CanFocus and so on. Most of row’s attributes are expected to be read only, thus don’t change their values directly. For list of all possible attributes see tag <I> and cell descriptions.

Generally, use predefined functions to read or change row’s attribute values instead of accessing them directly.

Also use these properties as read only. To get row’s attribute use global function Get rather then direct access to attribute.

Rows are in Extended API in three root HTMLElements, XH (head rows), XF (foot rows), XB (body rows). XH and XF have only immediate child rows <I> as fixed rows. In XB are immediate children pages <B> and their children are rows <I>. If TreeGrid don’t use paging, XB has one <B> child with all rows.

Header is represented as single HTMLElement in XHeader.

All other XML data (defaults, columns, panel, toolbar, pager, configuration menu, language texts) are represented as JavaScript object (or arrays of these objects accessed by name) with properties of same name as XML attributes. These properties has converted type, therefore numbers are always numbers not strings. But it depends on property value not on expected type (the conversion is universal).

Grid configuration (tag <Cfg>) is filled to properties of basic TGrid object. TGrid object has all properties named as <Cfg> tag attributes. Values are also converted by their value types.

In all functions columns are identified by its name (given in XML, <C Name=””>). By this name column object can be got from TGrid.Cols array.

In HTML table is every row represented by one <tr> tag for every section (left columns, variable columns, right columns), see TreeGrid layout. You can access row’s sections by GetRow function and cell by GetCell function.

Any grid on page can be accessed from global JavaScript array Grids. By its Index or by its id.

Global properties

TGrid ro Grids [id/idx] This is global array of all grids on page. Is indexed by grid index (from 0) or by grid id (string)

Members are added by creating grids on start or by function TreeGrid ( ). Every call adds one object with index++.

Existing grid can be added by function SetIdentity ( ) and removed by DelIdentity ( ).

TGrid Grids.Active Pointer to active grid under the mouse cursor. It processes mouse wheel events.

TGrid Grids.Focused Pointer to focused grid, processes key events. If you want to process key events in other controls, set it to null.

int Grids.CookieExpires When configuration in cookies expires, 0 (default) never, 1 only this session, >1 after xxx seconds, or can be of type Date – exact expiration date.

string Grids.CookieParam Other cookie parameters (path, domain, secure) in string, starting with ‘;’. For example “; path=/”.

int Grids.NoTryActiveX When set to 1 in IE does not try to create ActiveX objects, event if it is possible and uses slower script XML parsing,

but don’t show any message to a user about ActiveX. See example Examples/Html/SubmitNoActiveX.html.

This property has sense only if is not used AJAX and all data, include Defaults.xml and Text.xml, are included in HTML page.

char Grids.CharCodes[] If you would like to better control sorting and filtering strings you can define this array.

If this array is defined, all strings before sorting or filtering are modified by this array. Defining this array can slow down sorting or filtering.

It contains array of characters to replace characters in string.

For example you can set Grids.CharCodes[‘a’] = ‘b’, this means that all characters ‘a’ will be replaced by ‘b’ for sorting and filtering.

Global functions

TGrid TreeGrid (TDataIO D, string tag = “”, string id = “”) Creates and renders the grid. Connects the grid to the given data D.

D is object with data settings, it corresponds to <treegrid> tag attributes. TDataIO has the same properties as <treegrid> tag, see documentation.

If the <treegrid> attributes contain “_”, this means new sub-objects in TDataIO,

for example “Data_Url” means D.Data.Url or Upload_Param_F1 means D.Upload.Param.F1.

You can create it as new TDataIO object with predefined default settings.

D can be also of string type. In this case it contains full XML source for TreeGrid to create from. And TreeGrid cannot upload data.

tag is an id attribute of main tag or main tag object itself (usually <div>) to render grid to, this is required attribute.

id is the unique id of the grid, used to identify it, especially in saving configuration to the cookies. It can be undefined if set in downloaded data.

This function also sets the grid identity.

Function returns created TGrid object. Remember, creating and rendering is asynchronous, thus at the moment of function return, the grid is not fully prepared yet.

After finish will be fired OnRenderFinish and OnRenderPageFinish or OnLoadError event.

void StartTreeGrid (Event event) Starts creating grids from HTML tags <treegrid>. By default it is called from window.onload event.

You can also use this function to create grid on the fly instead of TreeGrid function.

Just create some <treegrid> tag as inner HTML of <div> tag you want to render grid to and call StartTreeGrid().

The function is asynchronous, in time of return, the grids are not created yet.

Use OnRenderFinish or OnRenderPageFinish events to catch the end of grid creating.

This function creates treegrid in place of <treegrid> tag and destroys it, so it can be called as many times as you want.

object Get (TRow row, string attr) Returns value of row’s attribute. Remember, all attributes are often of string types. If row has not this attribute set, it returns default value.

bool Is (TRow row, string attr) Returns true if row’s attribute has “1” value. Remember, all attributes are often of string types.

If row has not this attribute set, it returns default value.

void SetEvent (string name, string id, function func) Sets TreeGrid event handler for grid with given id.

Use it, if you have more grids and want to call for every grid different function.

name – event name like “OnClick”, id – id of the grid, func – any JavaScript function to be called for event raised.

If id is null, the function will be called for all other grids then for that have attached the event handler by SetEvent.

Example:

Standard way: Grids.OnClick = function(G){ if(G.id=="G1") alert("G1 clicked"); if(G.id=="G2") alert("G2 clicked"); }

New way: SetEvent("OnClick","G1",function(){ alert("G1 clicked");} );

SetEvent("OnClick","G2",function(){ alert("G2 clicked");} );

Do not use both ways together, if you set Grids.OnClick, you cannot set it also by SetEvent and vice versa.

SetEvent is useful also when using automatic merging web pages like by Java portal - JSR-000168 Portlet.

Format – Independent functions, can be overridden to change data conversion

string DateToString (Date date, string format) Converts date to string according to format string as in function ToString() in C#.NET.

date can be string, will be converted to date by standard Date(string).

If format is missing, uses English format “mm/dd/yyyy hh:mm:ss”, for today uses “hh:mm:ss”, for 00:00:00 uses “mm/dd/yyyy”, seconds are omitted if is 0.

Date StringToDate (string str, string format) Converts string to date according to format string as in function ToString() in C#.NET.

If format is missing, converts str as in standard format for date “d.m.y”, “d.m”, “m/d/y”, “m/d”, “y-m-d”,”m-d” and time “hh:mm:ss”, “hh:mm”

and for date and time combines these formats separated by any other character

string NumberToString (Number num, string format) Converts number to string according to format string as in function ToString() in C#.NET.

Number StringToNumber (string str) Converts number to string

bool KeyInt (Event event, string Value) Tests pressed key if can be added into integer number

bool KeyFloat (Event event, string Value) Tests pressed key if can be added into floating point number

bool KeyDate (Event event, string Value) Tests pressed key if can be added into date/time value

Functions – Independent helping functions

object GetElem (string id) Returns htlm element by its id (returns document.getElementById)

int GetKey (Event event) Returns pressed key (unicode code) in the event

Array [2] GetWindowSize () Returns size of browser’s window, returns [width, height]

Array [2] GetWindowScroll () Returns amount of scroll of browser’s window, returns [dX,dY]

Array [2] EventXYToElement (Event event, object elem ) Converts event.clientX, event.clientY to coordinates relative to elem. Returns [X,Y]

Array [2] ElemToParent (object elem, object parent) Returns relative position of element in its parent. Returns [X,Y]

void CancelEvent (Event event, int type = 0) Cancels propagation and prevents default of event. If type==1 cancels propagation only, 2 prevents default only.

Style GetStyle (object Elem) Returns computed style of the element.

Document CreateXML (string str) Creates XML document from string. This document can be iterated by DOM functions.

In all browsers all its nodes has property xml which returns the node as XML string.

object CopyObject (object o) Creates deep copy of any value.

void ShowHTML (string HTML, string name) Opens browser’s window named name with HTML content. If HTML does not begins with ‘<’ shows it as text.

void SaveCache (string id, string val) Saves value to persistent cache according to given id. Only for IE 5+ and Firefox 2+

You can also redefine this function to do your own caching mechanism when set <Cfg PersistentCfg>

string LoadCache (string id) Loads and returns value from persistent cache saved by SaveCache function.

Events

Events in TreeGrid are defined as methods of global Grids object. If this event method is not declared, event is not fired.

You can create new event in this way: Grids.OnGetColor = function(G,row,col,r,g,b,type){ /*your code*/ };

Style events

string OnGetColor (TGrid grid, TRow row, string col, int r, int g, int b, int type) Called for getting state color of the cell. If col is null, color is for whole row.

r,g,b are predefined colors for this state. type = 0 – normal row, 1 – focused cell, 2 – edited cell. Returns string color for style change (“#RRGGBB” or “rgb(r,g,b)”).

Can return null to use r,g,b values unchanged. Returned color is result color for the cell or row and is not modified according to state

int OnGetDefaultColor (TGrid grid, TRow row, string col, int rgbcolor) Called to get default color for the cell or row. rgb is predefined color (#RRGGBB)

Returns new integer #RRGGBB color or null to use default. The returned color is modified according to row state.

string OnGetClass (TGrid grid, TRow row, string col, string cls) Called for getting class attribute for cell or for cell input control. cls see file Grid.css.

grid – index of grid (from 0), row, col – cell, cls – name of default style for this cell. row can be grid.XHeader for caption, col can be “Panel” for button panel.

returns new name of style class (without leading ‘.’) or back cls. Remember, one cell or row has more then on style class, don’t change all these to one.

! Don’t return class with another extents (padding,border,...) than original class ! Don’t use classes with margin properties !

string OnGetType (TGrid grid, TRow row, string col, string type) Called for getting cell type. Returns new type or type.

string OnGetFormat (TGrid grid, TRow row, string col, string format, bool edit) Called for getting cell format. Returns new format or format.

if edit is false returns standard format, for true returns edit format

string OnGetEnum (TGrid grid, TRow row, string col, string[] enum) Called for getting enum array for enum cell. Returns new enum array or enum.

bool OnCanEdit (TGrid grid, TRow row, string col, bool can) Called before start editing cell. ce is predefined result.

Returns true to continue editing, false for prohibit editing or can.

bool OnCanEditDate (TGrid grid, TRow row, string col, Date date) Called when displaying date picker to permit only some dates to select by user.

string[] OnGetDefaults (TGrid grid, TRow row, string col, string[] defaults) Called before displaying menu for Button type Defaults.

Returns original or modified defaults array.

State events

type OnValueChanged (TGrid grid, TRow row, string col, type val) Called before cell values is changed by user edit. Return new value or val.

void OnAfterValueChanged (TGrid grid, TRow row, string col) Called after cell values is changed by user edit, only if value was changed to another.

int OnResultMask (TGrid grid, TRow row, string col, string val) Called when value collide with ResultMask

Returns 0 – default action, 1 – suppress default action, 2 – save value and stop edit, 3 – don’t save value and stop edit

void OnRowMoveToGrid (TGrid grid, TRow row, TGrid togrid, TRow torow, bool copy) Called after moving or copying row to another grid.

Called from function MoveRowsToGrid ( ).

New row (torow) is positioned yet, but not displayed. Old row (row) is still set and visible. If copy = true, old row will not be hidden.

void OnRowMove (TGrid grid, TRow row, TRow oldparent, TRow oldnext) Called after row have been moved inside one grid.

Row is still displayed in old position but have new settings. oldparent is original parent of the row, oldnext is original next sibling.

int OnCanDrag (TGrid grid, TRow row, TGrid togrid, TRow torow, int type) Called during dragging row above other row to find out if and

how row can be dragged / dropped. Return new type or type.

grid, row – dragged row, togrid, torow – drop target, type - 0 – cannot drop, 1 – in front of torow, 2 – to the end of children of torow, 3 – after torow

void OnRowDelete (TGrid grid, TRow row, int type) Called before deleting every row – if row is marked as deleted.

Fires for every row being deleted, even for its children. Type = 1 - hide + mark, 2 – show + unmark. If row is really deleted by DelRow ( ), event is not fired !

int OnCanRowDelete (TGrid grid, TRow row, int type) Called before row is deleted. Called to find out if and how can the row be deleted. Not called for its children.

type = 0 – cannot delete, 1 – user must confirm deleting, 2 - delete, 3 – undelete. Returns new type or type.

If fires, when deleting selected rows, type = 1 has no meaning.

bool OnCanRowAdd (TGrid grid, TRow parent, TRow next) Called before row is added to find out if can be added to this position. Called from control panel.

parent is parent row in tree or page for root row. next is next row behind the row in their parent or null if row is added to the end of the parent children.

void OnRowAdd (TGrid grid, TRow row) Called after the row is added (from control panel) but before it is displayed. Usually to change default values.

void OnRowCopy (TGrid grid, TRow row, TRow source, bool empty) Called after the row is copied from source row. empty is true if values were not copied.

bool OnExpand (TGrid grid, TRow row) Called before the row is expanded or collapsed. Return true to suppress action.

string[2] OnPrint (TGrid grid) Called before grid is printed. Return true to cancel printing or own print.

Or return string array with HTML prefix [0] and HTML postfix [1] to add to <body> when printing.

bool OnPrintFinish (TGrid grid, Window window) Called after print report is created and before the printing dialog is displayed.

window is browser’s window that contains the report.

You can also use this event to get back changes you done in OnPrint event (for example changes in grid.Img setting).

Return true to suppress default action. You can call w.print() in this event and do some action after, for example to close the window.

string OnSetRowId (TGrid grid, TRow row, string newid) Called when new id attribute is generated for the row. Returns new id. The row has still old id.

The newid and returned id is value for row id attribute. It is full id, includes all parts and optionally parent id.

string OnGenerateId (TGrid grid, TRow row, string newid) Called when new unique part of id is generated or updated for the row. Returns new id value.

The newid and returned id is the generated part of id, this is the value of the last attribute from IdNames list.

void OnColResize (TGrid grid, string col) Called after column is resized, by user or column with relative width.

void OnColMove (TGrid grid, string col) Called after column is moved to another position

void OnResizeMain (TGrid grid) Called after main tag is resized by user.

Function events – filter, sort, calculations,...

bool OnCanFilter (TGrid grid, bool start) Called when grid will be re-filtered. You can provide own filtering and return false.

start is true when called by starting grid

void OnFilterFinish (TGrid grid) Called after grid was re-filtered. Called only for filtering on client.

bool OnRowFilter (TGrid grid, TRow row, bool show) Called when filtering row, show is the filter result. Must return if row will be visible or not.

type OnGetFilterValue (TGrid grid, TRow row, string col, type val) Called to get value for filtering, val is predefined value, returns val or new value.

bool OnSort (TGrid grid, string col) Called when sorting grid after user action. Return true to suppress default sorting.

col can be null if was called from control panel.

void OnSortFinish (TGrid grid) Called after grid was re-sorted. Called only for sorting on client.

type OnGetSortValue (TGrid grid, TRow row, string col, type val, bool desc) Called to get value for sorting, val is predefined value, returns val or new value.

desc is true for descending sorting. Now this event is called only for sorting in string columns !

type OnGetCopyValue (TGrid grid, TRow row, string col, type val) Called to get value for copy to clipboard by Ctrl + C, val is predefined value, returns val or new value.

string OnGetExportValue (TGrid grid, TRow row, string col, string str) Called to get value for export to Excel

str is html tag ending character (‘>’), so to return just string return str+your_value and to return formatted number return your_format+str+your_value.

bool OnCalculate (TGrid grid, int show, bool calconly, TRow row) Called for custom calculations. Return true to suppress default calculations.

Define this event if you want to calculate cells in special order that cannot be covered by CalcOrder.

Called for initial calculation or for recalculation of whole grid after reload or filter is applied. From Calculate method.

If row is set, it is called to calculate only row’s children after loading of page.

If show = 1 display all changes, if show = 2 display changes only in fixed rows. If calconly = true, calculate only calculated rows.

In custom calculations you cannot use predefined formulas, you just have to provide your owns to calculate cells.

And for iteration cells use GetFirst and GetNext to iterate all rows or DOM attributes firstChild and nextSibling to iterate row’s immediate children.

To get fixed rows use GetFixedRows method. You can also test row’s attributes Visible and Deleted. Or any other row’s attribute.

bool OnRecalculate (TGrid grid, TRow row, string col, bool show) Called for custom calculations. Return true to suppress default calculations.

Define this event if you want to calculate cells in special order that cannot be covered by CalcOrder.

Called for recalculation after cell content changes. From Recalculate method. Use it with OnCalculate event.

If col is null, the whole row was changed (for example moved or pasted text).

If show = 1 display all changes

bool OnGroup (TGrid grid, string[] Cols, int[] Types, string Main) Called when grouping grid after user action. Return true to suppress default sorting.

Cols is new value for GroupCols, Types is new value for GroupTypes and Main (can be null) is new value for GroupMain.

void OnGroupFinish (TGrid grid) Called after grid was re-grouped in data, but before are changes visible in grid.

string OnGetGroupDef (TGrid grid, string col, int colindex, string def) Called to get default row for the group when grouping according to column

col is column name, colindex is index of col in GroupCols, def is predefined name of default. Return new name of default or def.

Click and key events

bool OnButtonClick (TGrid grid, TRow row, string col) Called after user button click the button on the right of the cell.

If called from menu Defaults, can return false to not hide dialog if this events handler opened another dialog.

If called from standard button click, the return value is ignored.

bool OnLinkClick (TGrid grid, TRow row, string col, string url, string target) Called after user clicks link at cell of type Link or Img.

Returns true to suppress default action. url is url opened in browser, target is target browser’s window.

bool OnClick (TGrid grid, TRow row, string col, int x, int y, bool handled, Event event) Called after cell click. row==grid.XHeader for header, col==”Panel” for panel.

x, y is cursor position relative to the cell. Returns true to suppress default action; handled is true if grid has done its default action yet.

event is standard MouseEvent to get for example information about Ctrl/Alt/Shift keys or other information about click.

bool OnDblClick (TGrid grid, TRow row, string col, int x, int y, Event event) Called after cell is double clicked. row==grid.XHeader for header, col==”Panel” for panel.

x,y is cursor position relative to the cell. Returns true to suppress default action.

bool OnRightClick (TGrid grid, TRow row, string col, int x, int y, Event event) Called after cell is right clicked.

row==grid.XHeader for header, col==”Panel” for panel. x,y is cursor position relative to the cell. Returns true to suppress default action.

You can use it to display your popup menu in such way:

Grids.OnRightClick = function(G,row,col,x,y){

var names = ["item1","item2","item3"];

Grids[0].ShowMenu (row, col, names, null,

function func(index,G,row,col,UserData) { alert("User clicked to "+names[index]+", user data is "+UserData); }

,0,"",x,y,"my data");

return true;

}

bool OnContextMenu (TGrid grid, TRow row, string col, int index, string item) Called when user clicks to context menu set by Menu attribute.

index is menu item index (from 1), item is item name from Menu array an user clicked to.

bool OnKeyDown (TGrid grid, char key, Event event) Called when user hold down key in focused grid. Return true to suppress default action

bool OnKeyPress (TGrid grid, char key, Event event) Called when user presses key in focused grid. Return true to suppress default action.

bool OnTabOutside (TGrid grid, int move) Called when user presses tab key on first or last cell in grid to change focus to another control.

Return true if focus moved and grid lost it.

move is 1 to forward move (last cell), -1 to backward move (first cell).

void OnFocus (TGrid grid, TRow row, string col, TRow orow, string ocol, int pagepos) Called when cell is focused, row, col is actual (new) focused cell.

orow, ocol is previously focused cell. All rows and cols parameters can be nulls.

pagepos is not null if row is not rendered page or row with children, in this case it is position on the page. If paging is not used, it is always null.

Focusing is moving cursor to row’s cell. By mouse click or by arrow keys or by tab key. Don’t confuse selecting and focusing row.

void OnSelect (TGrid grid, TRow row, int type) Called before the selection state of the row is changed. type = 0 (unselect), 1 (select), 2 (change)

Selection is done by user by clicking on row’s panel O icon or by pressing space key.

Don’t confuse selecting and focusing row. In the grid can be more selected rows, but only one focused.

bool OnStartEdit (TGrid grid, TRow row, string col) Called before starting editing, can return true to suppress editing

object OnGetInputValue (TGrid grid, TRow row, string col, object V) Called to convert cell value to input string

V is object with these three properties: Value, Type and Mask. You can change any of them and return V back.

string OnSetInputValue (TGrid grid, TRow row, string col, string val) Called to convert input string back to cell value, returns new or original val.

int OnEndEdit (TGrid grid, TRow row, string col, bool save, type val) Called before editing is finished

Returns: 0 continue default action, -1 continue editing, 1 event handled and value changed and saved, 2 event handled and value was not changed

bool OnShowDetail (TGrid master, TGrid detail, TRow row) Called before master row is displayed in detail grid, can return true to suppress action

void OnShowDetailFinish (TGrid master, TGrid detail, TRow row) Called after master row is displayed in detail grid

bool OnGoToPage (TGrid grid, TRow page, TRow pagepos) Called when grid displays another page. Return true to cancel change.

page is page (<B> tag) which will changed to, pagepos is this page position inside body, from 0.

Data events

bool OnDataSend (TGrid grid, object iopart, string data, function func) Called when request is sent to server by AJAX

Returns true to suppress default communication. Parameters are the same as in data method Communicate ( ).

If it does return true, must call function func (int code, object response).

bool OnDataError (TGrid grid, int code, string mess, object iopart, TRow row) Called when got server response with error code in AJAX communication.

iopart is part of TDataIO object, row is set to page or row for that data was downloaded.

Returns true to suppress default alert or reload action for code==-6.

void OnDataReceive (TGrid grid, TRow row) Called when got server response with correct data in AJAX communication.

When called grid.IO contains object with <IO> settings. Event handler function can test or modify these settings.

The row parameter contains row or page if data for page or children was requested.

bool OnDownloadPage (TGrid grid, TRow row, function func) Called when data for page or row’s children are requested.

Returns true to suppress default downloading. If does return true, must call function func(int result), where result<0 is error code or 0 for ok.

bool OnReadData (TGrid grid, object iopart, function func) Called whed data for defaults, texts, layout or body are requested by any method (AJAX, submit, ...)

iopart is one part of TDataIO object, for example Grid.Data.Layout.

If it does return true, must call function func(int result), where result<0 is error code or 0 for ok.

bool OnSave (TGrid grid, TRow row, bool AutoUpdate) Called to submit or upload changes to the server by custom way. Returns true to suppress default data upload.

row – if only one row was changed, this is the row to update. AutoUpdate is set to true if this event was fired from auto update.

bool OnReload (TGrid grid) Called from control panel to cancel changes and reload data by custom way. Returns true to suppress default reload.

bool OnCanReload (TGrid grid, int changed) Called when reload is requested (when reloading or server side sorting/filtering/grouping),

called instead of confirming message to user. changed = &1 – grid contains changed rows, &2 – grid contains selected rows.

returns false to cancel action.

void OnLoaded (TGrid grid) Called when all body data were loaded, before OnLoadError.

void OnLoadError (TGrid grid) Called when data cannot be downloaded and grid cannot render and shows fatal error.

void OnRenderStart (TGrid grid) Called when all data are loaded and updated and rendering started. Or when called Render function.

void OnRenderFinish (TGrid grid) Called when rendering or re-rendering of grid is done. Use if you need to do some post-render actions.

This event is fired after whole grid layout and fixed rows are rendered, but before any variable row is rendered, see OnRenderPageFinish.

void OnRenderPageStart (TGrid grid, TRow row) Called before page is rendered.

When used child paging, this event is fired after rendering children of any expanding row.

void OnRenderPageFinish (TGrid grid, TRow row) Called after page is rendered.

If grid does not use paging, firing this event means, that whole grid is fully rendered.

When used child paging, this event is fired after rendering children of any expanding row.

bool OnLoadCfg (TGrid grid) Called when cfg is being loaded, returns true to suppress loading. Called even if SuppressCfg set.

void OnCfgLoaded (TGrid grid) Called when cfg is loaded to provide own update to cfg.

bool OnSaveCfg (TGrid grid) Called when cfg is being saved to cookis, returns true to suppress saving. Called even if SuppressCfg set.

Control panel events

bool OnCanShowPanelItem (TGrid grid, int index, bool show) Called to let to hide panel icon. Returns false to hide icon.

show – if button is visible by default according to grid type and supported functions, this handler usually returns this value.

index = 1 Save, 2 Reload, 3 Add, 4 Sort, 7 Help, 8 Expand all, 9 Collapse all, 10 Cfg, 11 AddChild, 12 Repaint, 13 Calc, 14 Columns menu, 15 Print

string OnGetUserPanel (TGrid grid) Called to show user icons on panel. These icons are inserted in front of columns, cfg and help icons.

This function returns empty string or HTML code of all user buttons. Every user button must be placed to <TD></TD> tags.

For example: "<td><button class=GButton onclick='alert(\"User toolbar button clicked!\");'>User</button></td>".

bool OnPanelClick (TGrid grid, int index) Called when user clicks button on control panel. Returns true to suppress default action.

index is button index, see OnCanShowPanelItem

bool OnCanShowCfgItem (TGrid grid, int index, bool show) Called to let to hide cfg menu item from JavaScript runtime. Returns false to hide item.

show – if button is visible by default according to grid type and supported functions, this handler usually returns this value.

index = 1 Show deleted, 2 Auto sort, 3 Auto update, 10 Mouse hover, 11 Show drag object, 12 Show left panel, 13 Show icons, 14 Show pager, 15 Show all pages

void OnCfgChanged (TGrid grid) Called when user presses OK button on configuration menu, after all changes have been set in data,

but before saving to cookies and before any updates in display. Fired even if user did not make changes.

void OnColumnsChanged (TGrid grid, bool[string]cols, int count) Called when user presses OK button on columns menu. Before any updates in data or display.

cols are array of changed columns, with string index as column name and value as its new visibility

Class TGrid

Design / runtime properties

The instance of TGrid has all properties from data tag <Cfg>, if value is number, it is converted to number.

Runtime only properties

int Index Unique index of grid to global array Grids. Grid gets first available index (from 0), when is created.

TCol [] Cols Array of all columns, every column has unique index. TCol is object with all attributes from XML <C> tag.

int RowCount Count of actually rendered variable rows. This variable is set when page was rendered and is updated for every next page rendered.

For non-paging grids, you can access this variable first in OnRenderPageFinish event handler.

HTMLElement XB <Body> node. This contains all pages <B> and variable rows <I>, in Internal format.

HTMLElement XH <Head> node. This contains all head rows <I>, in Internal format.

HTMLElement XF <Foot> node. This contains all foot rows <I>, in Internal format.

HTMLElement XHeader <Header> node. This represents column titles, node is in Internal format.

HTMLElement XGroup <I Kind=”Group”> node. This represents grouping row, node is in Internal format.

HTMLElement XPager <I Kind=”Pager”> node. This represents grouping row, node is in Internal format.

string [][] Lang Array of sections with texts, from node <Lang>, identified by names Lang[“section”][“ident”], for example Lang[“Alert”][“Row2”]

object [] Toolbar Array of toolbar settings, from node <Toolbar>, number values are converted to numbers. Instance is in ControlPanel property.

object [] MenuCfg Array of configuration menu settings, from node <MenuCfg>, number values are converted to numbers.

object [] Pager Array of pager settings, from node <Pager>, number values are converted to numbers.

string [][3] ColNames Three Arrays of column names (ColNames[0] = left, [1] = variable, [2] = right), sorted by position in table

TRow ro FRow [null] Focused Row

int ro FPagePos [null] If FRow is typeof page (not rendered yet), there is index of focused row on this page

string ro FCol [null] Focused Col

bool ro EditMode [false] If focused cell is edited now

TRow ro ARow [null] Row under mouse cursor

string ro ACol [null] Col under mouse cursor

bool ro Loading [false] Grid is starting now, loads and prepares its data, starting is background process. After Loading is cleared, grid starts rendering.

bool Rendering [false] Grid is rendering now, rendering is background process

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 SetScrollBars to update grid layout.

bool StopCalc [false] If true, does not refresh calculated cells after some value changed

TGridDialog Dialog [null] Displayed modal dialog or null

TDataIO Data [empty TDataIO] Object for connecting grid to the web server. Its parameters are the same as attributes of <treegrid> tag,

but are parsed to object arrays by char ‘_’. For example <treegrid Layout_Url> is Data.Layout.Url or <treegrid Layout_Param_P1> is Data.Layout.Param.P1.

TIO IO [empty TIO] Object of server response. Every communication changes this object. This contains all attributes of <IO> tag and vice versa.

TToolbar ControlPanel [object] Instance of toolbar. Setting is in Toolbar property.

Column methods

int[] GetSections ( ) Returns first and last visible section [c1,c2]. c1 is 0 if left cols are visible, 1 otherwise, c2 is 3 if right cols are visible otherwise 2.

string GetNextCol (string col) Returns next visible column according to its position in html

string GetPrevCol (string col) Returns previous visible column according to its position in html

string GetFirstCol (int sec) Returns first visible column in given section or null

string GetLastCol (int sec) Returns last visible column in given section or null

void MoveCol (string col, int pos, bool noshow) Moves visible column to new position, inside section only. If noshow set, does not display changes.

void ChangesColsPositions (string[] leftcols, string[] cols, string[] rightcols) Changes positions of all columns in grid and splits them to sections.

All three arguments are Arrays of column names sorted according their positions in given section

All column names must be given. Does not show changes (re-rendering is needed by Render function) and also does not save changes to cookies.

void ShowCol (string col) Displays hidden column. Can re-render grid, if needed.

void HideCol (string col) Hides visible column. Can re-render grid, if needed.

bool ChangeColsVisibility (string[] Hide, string[] Show, bool prefer=0) Changes visibility of given columns

Hide – array of column names to hide, Show – array of column names to show

If column is present in both arrays, it will be hidden for prefer = 0 or shown for prefer = 1

Returns true, if re-rendering is needed (by Render function).

TCol AddCol (string col, int sec, int pos, int width, bool show, string type, string caption, string formula, string enum) Adds one column to the table.

col is column name, sec is section of columns (0 – left, 1 – variable, 2 – right), position is column position in its section

width is column width or null for automatic computing, for show = true is column displayed in table,

type, caption, formula and enum are predefined values for these properties, can be null for default values.

Even if formula is set, does not calculate values in the column. When adding calculated columns, remember to update CalcOrder properties.

New column will have default values from <D Name=’C’>. Returns new column or null if column with given name already exists.

void DelCol (string col) Hides and deletes column. Column values in rows stay.

object[] GetColLeft (int left) Returns [string col, int left]. Returns column under given position in pixels and difference left-col.left.

string GetCaption (string col) Returns column caption (from XHeader).

Row methods

TRow is row object, it is type of HTMLElement. Column is identified by string name.

TRow [] GetRows (int sec) Returns rows from given section, head or foot rows only.

TRow [] GetFixedRows ( ) Returns all fixed rows (head and foot)

int GetPos (TRow row) Returns row’s position in its parent. It counts only visible rows.

TRow GetRowPage (TRow row) Returns page inside that row is.

int GetPagePos (TRow row) Returns row’s position in its page. It counts only visible rows.

TRow PagePosToRow (TRow page, int pos) Returns row on given position on page. It counts only visible rows. It is only for loaded pages (State>2).

int GetPageNum (TRow page) Returns position of page inside body

int GetFirst (TBody B, int type) Returns first (by position -> top) existing row in given body, if B = null, in first body, if(type&4) including head and foot rows.

int GetLast (TBody B, int type) Returns last (by position -> bottom) existing row in given body, if B = null, in last body.

if (type&1) ignores rows hidden by collapsing parent, if(type&4) including head and foot rows.

int GetNext (TRow row, int type) Returns next (by position -> under) existing row the given row.

if (type&1) ignores rows hidden by collapsing parent, if (type&2) only from actual page.

int GetPrev (TRow row, int type) Returns previous (by position -> above) existing row the given row. Attention, function is much slower than GetNext ( ).

if (type&1) ignores rows hidden by collapsing parent. if (type&2) only from actual page.

int GetFirstVisible (TBody B, int type) Returns first (by position -> top) visible row in grid. See GetFirst ( ).

int GetLastVisible (TBody B, int type) Returns last (by position -> bottom) visible row in grid. See GetLast ( ).

int GetNextVisible (TRow row, int type) Returns next (by position -> under) visible row the given row. See GetNext ( ).

int GetPrevVisible (TRow row, int type) Returns previous (by position -> above) visible row the given row. See GetPrev ( ).

object [] GetPrevShift (TRow row, int pagepos, int cnt) Returns [TRow row, int pagepos] . Returns previous visible row shifted by cnt rows.

row can be type of page, in this case pagepos is used.

object [] GetNextShift (TRow row, int pagepos, int cnt) Returns [TRow row, int pagepos] . Returns next visible row shifted by cnt rows.

TRow GetNextSibling (TRow row) Returns next sibling for root row on page.

TRow GetNextSiblingVisible (TRow row) Returns next visible sibling for root row on page.

bool HasChildren (TRow row) Returns if row has some visible children (shows icon expand/collapse)

TRow [] GetSelRows ( ) Returns all selected rows, in table order, including fixed rows.

Don’t confuse selected rows with focused row, focused row is set by FRow property.

TRow GetRowById (string id) Returns row with given id. The id must be full id, see IdNames.

int GetRowHeight (TRow row) Returns height of row in pixels. For page counts height of all rows. Remember, variable rows must have same height.

string GetCDef (TRow row) Returns CDef attribute for given row. For page returns XHeader CDef.

string GenerateId (TRow row) Generates new row’s id and saves it to LastId. Returns it. The id is only the last part for multi ids.

TRow AddRow (TRow parent, TRow next, bool show = false) Adds row to table and returns it. If show = true, displays it.

parent is parent row, next is row in front of adds new row. If next is null adds new row as last parent’s child. If parent and next are null adds row as last root row.

Also sets values to new row from its default row (according to CDef attribute of parent row). Also creates unique id for the row.

void DelRow (TRow row) Deletes row from table. The row is really deleted, not just marked ! For marking row use DeleteRow().

Deleted rows are not in output data, thus server cannot see which rows was deleted (only by comparing with original data).

void MoveRow (TRow row, TRow parent, TRow next, bool show = false) Moves row to the parent’s children in front of next. If show = true, displays changes.

If next is null moves new row as last parent’s child. If parent and next are null moves row as last root row.

TRow MoveRowsToGrid (TRow row, TGrid grid, TRow rowto, int type, bool copy = false) Moves or copies row with its children to another grid.

Displays changes. type = 1 – in front of rowto, 2 – into children of rowto, at the end, 3 – behind rowto

If copy is true, row is not deleted from grid. Returns added row.

void MoveRows (TRow row, TRow rowto, int type) Moves row with its children inside one grid, same function but faster then MoveRowsToGrid.

void ShowRow (TRow row, bool noshow = false) Displays the row in table (sets its Visible property to true).

Also expands its parent to show row. If noshow is true, only sets Visible but does not show the row.

void HideRow (TRow row, bool del = false, bool noshow = false) Hides the row from table.

If del = true, deletes row from html table (but not from data). If noshow is true, only sets Visible but does not hide the row.

void DeleteRow (TRow row, int type) Deletes / undeletes row from grid. Displays changes. Prepares deleting and calls DeleteRowT ( ).

type = 1 – delete + confirm dialog, 2 – delete, 3 – undelete. Deletes row with its children, but undeletes the row only. Only marks rows as deleted.

void DeleteRowT (TRow row, int type, bool noshow = false) Deletes / undeletes row from grid. Displays changes. type = 2 – delete, 3 – undelete.

Deletes row with its children, but undeletes the row only. Only marks rows as deleted.

void SelectRow (TRow row) Selects / unselects row

void SelectAllRows ( ) Selects / unselects all rows

void SelectRange (TRow row1, string col1, TRow row2, string col2, int select, int type) Selects range of cells, including given cells

If col1 is null, selects all rows, otherwise selects continuous range of cells.

select = 0 – unselects range, 1 – selectes range, 2 – unselects range if cell row1,col1 is selected, otherwise selects the range

type = bit array, &1 – selects only visible rows, &2 – ignores children of collapsed rows.

void Expand (TRow row) Expands row, for child paging is asynchronous

void ExpandParents (TRow row) Expands all parents to show the row. Row must not be hidden. For child paging is asynchronous.

void ExpandAll (int maxtime = 5000) Expands all rows. maxtime is time in milliseconds to wait for finish. After that time function stops and returns.

Remember, in grid with ChildPaging is not often possible to expand all rows, because rendering of thousands of rows is very slow.

void Collapse (TRow row) Collapses row

void CollapseAll ( ) Collapses all rows

void ShowDetail (TRow row, string detail_grid) Shows the row in the detail grid.

void RefreshDetail (TGrid grid, bool clear) Refreshes all detail grids for actual grid or if set grid, refreshes only this detail grid

If clear is true, clears all these detail grids

Html methods

object GetRow (TRow row, int sec) Returns row element from section (0 – left, 1 – variable, 2 - right)

object GetRowChildren (TRow row, int sec) Returns row children element from section (0 – left, 1 – variable, 2 - right)

object GetCell (TRow row, string col, int type = 0) Returns cell element according to type,

type==0 – returns object of whole cell (main tag TD)

type==1 – returns inner tag <TD> containing <DIV> with text (for MainCol and button) or inner tag <DIV class="width...">

type==2 – returns tag <IMG> or <BUTTON> for cell with button or null

Cell HTML = <TD class="border and background setting"><DIV class="width setting"><DIV class="text and align setting">text</DIV></DIV><TD>

MainCol cell = <TD class="border..."><DIV class="width..."><TABLE><TR><TD><IMG></TD><TD><IMG></TD>... <TD><DIV class="text...">text</TD></TR></TABLE></DIV>

Cell with button = <TD class="border..."><DIV class="width..."><TABLE><TR><TD><DIV class="text...">text</TD><TD><IMG></TD></TR></TABLE></DIV>

void RefreshRow (TRow row) Refreshes row’s html element, re-renders whole row.

void RefreshCell (TRow row, string col) Refreshes cell’s html element, re-renders whole cell

void ColorRow (TRow row) Updates color of row according to its state

void ColorCell (TRow row, string col) Updates color of cell according to its state

bool SetScrollBars ( ) Updates grid scrollbars. Call it, if main tag is resized. Returns false, if grid cannot be displayed (Too small extents error)

void ScrollIntoView (TRow row, string col, int pagepos=null) Scroll grid to show the cell, if row is page, set pagepos to expected row’s position (index) at page.

void SetWidth (string col, int dx, bool all) Changes column with about dx. If all = true - changes all cells, false – visible cells only or header only if there are too many rows.

int CalcWidth (string col) Computes column width according to couple of first values.

void StartEdit (TRow row = null, string col = null) Starts editing in cell, if row and col are not set, starts editing focused cell.

void EndEdit (TRow row, string col, bool save) Finishes / cancels editing cell. If save is true, saves changed value else restores original.

Returns true if value changed, false if not, null for error and -1 to continue editing

int GetCellWidth (TRow row, string col) Returns inner width of cell to put input tag.

Message methods

void ShowMessage (string message, int x = null, int y = null, bool always = false) Displays message (not dialog) on position x,y or at center of main tag

This hides previously displayed message. When message is displayed, grid is disabled. If always is true, displays message even if SuppressMessage is set.

void HideMessage ( ) Hides grid’s message and enables grid.

void Disable ( ) Disables the grid, the grid is grayed and does not react to user actions.

void Enable ( ) Enables disabled grid

TGridDialog ShowDialog (TRow row, string col, string html, int align, int X, int Y) Displays modal dialog bellow the cell with this innerHTML.

Closes previously displayed dialog. Returns created dialog. Dialog is closed if user clicks outside this dialog or presses key.

align = 0 – right (default), 1 – left alignment to the cell, html = any HTML code to fill in the dialog.

X, Y is position of the upper left corner of dialog relative to cell, if set align is ignored.

TGridDialog has these properties:

Grid – the grid it belongs to,

Close [null] – function (TGridDialog) called when dialog is closing

Tag – html tag of dialog

Start [false] – Set it to true after user clicks to your dialog and you don’t cancel this event

MainTag [null] – main tag dialog renders to, set it if you need id

void CloseDialog (bool always) Closes dialog displayed by ShowDialog. If always=true closes even if dialog has Start = true.

TGridDialog ShowMenu (TRow row, string col, string[] names, string[] icons, function func, int align, string caption, int X, int Y, object UserData)

Creates and shows popup menu as non modal dialog for given cell. If row is null, col is cell object for the dialog is shown

names is array of displayed captions, icons is array of images right to captions or null

bool func (int Index, TGrid Grid, TRow row, string col, object UserData).

func is function called after click to some item with its index (from 0) and given row, col and UserData attributes. Returns true to close dialog.

align = 0 right, 1 left, caption is HTML code of header

X, Y is position of the upper left corner of dialog relative to cell, if set, align is ignored.

Value methods

string ValueToString (type Value, int type, string format) Converts Value to string according to column type and format string

type StringToValue (string Value, int type, string format) Converts string to type according to column type and format string

string GetString (TRow row, string col) Returns cell value as string, in standard format (non editing)

type GetValue (TRow row, string col) Returns cell value as column type, for date returns internal format (count of msec from 1/1/1970)

void SetString (TRow row, string col, string Value, bool refresh = false) Sets cell values as string in editing format,

Set refresh to true to display changes in table or call RefreshCell method.

void SetValue (TRow row, string col, type Value, bool refresh = false) Sets cell value as column type,

Set refresh to true to display changes in table or call RefreshCell method.

string GetType (TRow row, string col) Returns cell type: “Bool”, “Int”, “Float”, “Enum”, “Date”, “Text”, “Html”, “Pass”, “Radio”,”List”,”Link”,”Img”

string GetFormat (TRow row, string col, bool edit = false) Returns format string for given cell. If edit = true, returns EditFormat.

string[] GetEnum (TRow row, string col) Returns Enum strings for given cell of type Enum.

bool CanEdit (TRow row, string col) If cell can be edited.

bool CanFocus (TRow row, string col) If cell can be focused.

Data methods

bool SetIdentity (string tag = “”, string id = “”) Sets grid identity and creates reference in global array Grids. Without this functions the grid cannot be used.

This function is called from TreeGrid function or when TreeGrid is created automatically.

If you want to set identity of grid, that already have identity set, you must call DelIdentity ( ) before.

Returns true, if identity was set, false if both tag in parameter and grid’s MainTag are not set.

void DelIdentity ( ) Deletes grid from global Grids array. But remember, if you delete grid and again set its identity, the grid will get another index.

void Communicate (object DataIO, string Data, function Func) Sends Data to the server and returns its response to function Func.

Data can be “”, in this case only downloads server response or sends parameters. DataIO is one part of TDataIO object, for example Grid.Data.Layout.

This function can be used for custom AJAX calls. In this case set DataIO.Url and optionally DataIO.Param string array.

It does not alert any message, only if Debug is set opens new browser’s windows.

Asynchronous function. After finish, calls function Func. function Func (int code, object response).

code is error code and response is error message or returned data for code = 0 (can be type of string or XmlNode)

code = 0 OK, -1 browser does not support the function, -2 bad URL, -3 URL not found, -4 bad document format, -5 SOAP Err, -6 Timeout

Remember, Func can be called even before Communicate returns, but always only once.

void Communicate2 (object DataIO, string Data, function Func) Sends Data to the server and adds its response XML to grid.

Alerts error/informational message from server if any. Uses Communicate function, see its DataIO and Data parameters.

Can be used for custom AJAX calls for updating data in grid.

Asynchronous function. After finish, calls function Func. function Func (int code). code is the same as in Communicate function.

void DownloadData (object DataIO, function Func) Downloads data from server. To server sends request with sort and filter settings. Alerts server message if any.

Asynchronous function. After finish, calls function Func. function Func (int code), see Communicate.

void DownloadPage (TRow row, function Func) Downloads children of given row or page. Sends to server request with page index or row id and filter and sort settings.

Alerts server message if any. Asynchronous function. After finish, calls function Func. function Func (int code), see Communicate.

void UploadChanges (TRow row, function Func) Uploads all changes to server, only if AutoUpdate is true. If row is set, upload changes in the row only.

Alerts server message if any. Asynchronous function. After finish, calls function Func. function Func (int code), see Communicate.

Accepts only if server Result is ok (>=0), if code < 0 does not accept changes.

void ReadData (object DataIO, function Func) Reads data from given source according to Url/Tag/Data parameters.

DataIO is one part of TDataIO object, for example Grid.Data.Layout. Alerts server message if any.

If downloads data, is asynchronous, but always after finish calls function Func. function Func (int code), see Communicate.

void ReloadBody (function Func) Reloads whole body (from source Grid.Data.Data).

Asynchronous, hides message. After finish, calls function Func. function Func (int code), see Communicate.

bool Reload (TDataIO D, string id) Reloads and re-renders whole grid. Asynchronous. If parameters are set, can override original settings.

If some changes were done or some rows are selected, warns user. It returns false if user disallowed the action or grid is loading or rendering.

After finish will be fired OnRenderFinish and OnRenderPageFinish or OnLoadError event. This function can be used to reload another data from another source.

void Clear (int type) Frees memory allocation for the TreeGrid. If you delete grid from JavaScript, call this function to free browser’s memory.

TreeGrid calls this function automatically when reloading or when window is closing.

type = 0 – clears only links between data and htm table, 1 – clears whole grid, including data and main tag.

void Save (Event event) Uploads all changes to server. Submits form if Grid.Data.Upload.Tag is set or uses XmlHttpRequest if Grid.Data.Upload.Url is set.

event is send to original submit event handler of the form if any. Synchronous, hides message (only if XmlHttpRequest is used).

string GetChanges (TRow row = null) Returns all changes as request string for server. If row is set, returns changes of this row only.

Format of request is used according to Grid.Data.Upload.Format.

int HasChanges ( ) Returns &1 if grid contains some change not yet uploaded to server. Only when SaveValues is not set.

Returns &2 if grid contains some selected rows. Only when SaveSelected is not set.

void AcceptChanges (TRow row = null) Accepts all changes in grid – clears all flags Changed, Added, Moved and clears rows marked as Deleted. Displays changes.

Can be called after server accepts sent data. If row is set, updates only this row.

string GetXmlData (int type = Upload_Type, string attrs = Upload_Attrs) Returns grid’s data according to type and attrs, see Upload_Type.

void AddDataFromServer (string Data) Adds XML data into grid as it was sent from server. Accepts all changes and does not send anything to server.

Use it to modify data by <Changes> tag with rows Added/Changed/Deleted/Moved if used custom AJAX call.

void LoadCfg ( ) Loads cfg from cookies. Does not display any changes.

void SaveCfg ( ) Saves cfg to cookies.

string GetCfgRequest (string format = “dtd”) Returns filter and sort settings for download request, without enclosing <Grid> tag. format can be “internal” or “dtd”

void CheckForUpdates (function Func) Checks for updates on server and downloads them if any, see Check_ data source. Calls Func after finish.

Paging and render methods

void Render (string message) Re-renders whole grid into main tag’s innerHTML.

This function may be slow, if many rows are present. So it runs asynchronous. message is the message displayed to user while grid renders.

void UpdateRows ( ) Updates all rows according to their position, if paging>1 re-renders body. Asynchronous.

void UpdateBody ( ) Re-renders whole body.

void GoToPage (TRow page) Scrolls or moves to given page

void GoToNextPage ( ) Scrolls or moves to next page

void GoToPrevPage ( ) Scrolls or moves to previous page

void UpdatePager ( ) Re-renders pager

string GetCellHtml (int row, int col) Return html of cell to change to GetCell (row,col).innerHTML.

void ShowPages ( ) Starts loading and rendering displayed pages. Asynchronous.

TRow AddPage (string name, string xml, int count) Adds new page to the end of pages. name is page name in pager, can contain HTML code.

xml is xml content for page, it can contain only rows like “<I A=’10’/><I A=’20’/>”.

For server paging (Paging=3) xml can be null and data for page will be loaded from server, in this case count is supposed count of rows on page.

Other methods

int GetColor (int row) Returns color of row according to its state

string GetText (string ident) Returns language text from Text section

string GetAlert (string ident) Returns language text from Alert section

bool Focus (TRow row, string col, int pagepos = null, bool show = false) Focuses cell, saves changed values on previously selected cell.

Returns true, if cell was focused.

If row is page, focuses cell on page on pagepos position after page renders (asynchronously). If paging is not used, pagepos is ignored.

If row is null, defocuses grid. If show is true expands all parents to show row.

bool TabInside (Event event, int move) Function to move focus to grid from another control by tab key. event is Event object from onkeypress or onkeydown event.

Returns true if focus moved to grid and control need to loose focus. move is 1 to forward move (to first cell), -1 to backward move ( to last cell)

Call this function from previous or next control in expected tab order from event handler onkeypress or onkeydown to move focus to the grid.

This function does not remove focus from the control. This functions tests pressed key for tab with or without shift.

void SortClick (string col, int type) Simulates click to sort icon in the given column, type can be sorting type

string Escape (string val) Converts string to show to HTML tag’s attribute value (changes entities).

void Calculate (int show = 0, bool calconly = false) Calculates grid. Grid can be calculated only if Paging<=2.

If show = 1 displays all changes, if show = 2 displays changes only in fixed rows. If calconly = true, calculates only calculated rows.

void Recalculate (TRow row, string col, bool show = false) Re-calculates grid after given cell changes, according to cell’s or row’s parameter Recalc.

Always recalculates fixed calulated rows.

void SortRow (TRow row, string col=null, bool show = false) Sorts (and moves) one row by sort settings. If col is set, test only this column for changes.

void SortRows ( ) Sorts all rows, according to sort settings and paging type, asynchronous.

void DoSort (bool show) Sorts all rows in place (used only when Paging <=2).

void DoFilter (TRow row = null, string col = null) Applies all filters (in Filter rows) to the grid. If set row and col updates operator for this cell in Filter row.

void DoGrouping (string[] Cols, int[] Types, string Main) Re-groups grids according given settings. If Cols is null, it un-groups grid.

Cols is new value for GroupCols, Types is new value for GroupTypes and Main (can be null) is new value for GroupMain.

Main can be used only if MainCol is not set.

void ChangeStyle (string ImgData, string StyleUrl) Changes grid style and images. ImgData is XML string with image settings <Grid><Img ...></Grid>

StyleUrl is href parameter for style link. This link must exist in HTML header. If there are more style links, the grid style link is identified by title, “GridStyle”

TClick GetClick (MouseEvent e) Returns information about mouse click from the event.

Returned TClick object has these attributes: TRow Row, string Col, int X, int Y. X and Y is mouse position relative to the cell.

string GetPrintable (int show, bool onepage) Returns TreeGrid HTML in printable format without scrollbars, toolbar, panel and pager.

show – what to show (default is 255), bit array- &1 header, &2 head, &4 foot, &8 body. onepage – for true returns only one page if AllPages is set to 0.

void UpdatePrintable (HTMLElement table) Updates tree icons in printable version if VarHeight is 1.

Class TToolbar

TToolbar object is accessible as TGrid.ControlPanel. It contains properties and functions for bottom toolbar. If you want to hide the toolbar and still use its buttons functions from JavaScript, just create it by constructor and use Click function.

TGrid Grid Grid it belongs to

object MainTag Main tag to that is rendered

bool Inside If it is inside TreeGrid (MainTag is part of the TreeGrid)

TToolbar (TGrid grid) Contructor. Creates tool bar for given grid. But does not render it.

void Render (object tag) Renders toolbar to given tag. tag can be HTMLElement or string id.

void Click (int num) Simulates click to given button, for button numbers see event OnCanShowPanelItem. Even if the button is not displayed.

void HideCfg (bool save) Hides configuration menu. if save = true saves changes done in menu.

Class TRow

TRow represents one row in table with all properties and data.

TRow is not JavaScript object, but it is standard DOM HTMLElement object. Therefore contains all properties and methods like firstChild or appendChild.

But don’t use these methods and properties, take them as private. Instead of them use TGrid’s method as GetFirst or AddRow.

Class TRow contains all properties set in input XML data in tags <I> and <D>. For reading these properties use global functions Get and Is.

For changing these properties you can use TGrid’s methods like SetString or SelectRow.

Class TRow can also contain any custom attributes set in input XML data or set by JavaScript by standard assignment like row.myProperty = 12.

See also paragraph TreeGrid data structure for more information about storing rows in table.

Class TRow has also these public properties:

int ro Level 0 = root, -1 = page, >0 children

string ro Fixed is set for fixed rows only. For head is “Head”, for foot rows is “Foot” and for header is “Header”

int ro ARow For multi line header only, the index of actual header row under mouse cursor, used usually in OnClick event

Class TCol

TCol represents one column in table with all settings, but without any data (data are stored in rows).

TCol is standard JavaScript object, but never create its instance, it is private object.

Class TCol contains all properties set in input XML data in tags <C> and <D Name=’C’>. For reading these properties standard JavaScript access like var w = col.Width.

For changing these properties you can use TGrid’s methods like HideCol or SetWidth.

Class TCol can also contain any custom attributes set in input XML data or set by JavaScript by standard assignment like col.myProperty = 12.

Class TCol has not any other public properties.

Updates

3.2

Many Data methods now work asynchronously, added parameter Func – function called on finish.

Added OnLoadError event, GetCaption method.

3.3

Added ChangeStyle, GetSelRows methods

3.5

Added ShowCol, HideCol methods

3.7

Added GetXmlData and GetRowById methods

Re-added event OnMoveToGrid and method MoveRowsToGrid

3.8

Added many data events.

Added OnDblClick event.

4.0

Added event OnExpand

Added event OnRightClick

Added function ShowMenu

Added function Clear

Added function GetClick

Updated events OnClick, OnDblClick

Updated functions ShowDialog, SetScrollBars

Added global property CookieExpires

4.0.3

Added events OnResultMask, OnStartEdit, OnEndEdit, OnAfterValueChanged

Added GetPageNum method

Added events OnRenderPageStart, OnRenderPageFinish and updated OnRenderFinish

Updated function Focus and event OnFocus

Added function ExpandParents

Added grid property Loading

Added event OnLinkClick

Updated Rendering property

Added DeleteRow function and update DeleteRowT

Updated RowCount property

Added sections TCol and TRow.

Added TRow attribute Fixed

4.1

Added Grids.NoTryActiveX property

Added AddCol and DelCol functions

4.2

Added AddPage method

Added OnCfgChanged and OnColumnsChanged events

Added GetPrintable and UpdatePrintable methods.

Added OnPrint method

Updated method GenerateId

Added OnSetRowId and OnGenerateId events

Added Communicate2 method

Added AddDataFromServer method

Updated event OnEndEdit

Added events OnGetSortValue, OnGetFilterValue, OnGetCopyValue

4.3

Added OnRowCopy event

Added OnGetDefaultColor event

Updated events OnClick, OnDblClick and OnRightClick

Added HasChanges method

Updated OnButtonClick event

Added OnGetInputValue and OnSetInputValue events

Added OnGetDefaults event

4.4

Added SelectRange method

Added OnCalculate and OnRecalculate events

Added OnSortFinish and OnFilterFinish events

Added OnShowDetail and OnShowDetailFinish events

Added functions ShowDetail and RefreshDetail

Added Grids.CharCodes property

Added CheckForUpdates method

4.4.2

Added row attribute ARow

4.5

Added events OnGroup, OnGroupFinish and method DoGrouping

Added OnColResize, OnColMove and OnResizeMain events

Added OnPrintFinish event

Added function SetEvent

Added XPager and XGroup properties

Added event OnGetExportValue

4.5.4

Added OnContextMenu event

Added OnGoToPage event

Added OnCanReload event

4.5.6

Updated MoveCol function

Added ChangeColsVisbility and ChangeColsPositions methods

4.5.9

Added LoadCache and SaveCache functions

4.5.10

Updated OnPrintFinish event

4.5.11

Added OnCanEditDate event

4.6

Added Grids.CookieParam property

Added OnGetGroupDef event