JavaScript API Reference

TreeGrid v5.9

TreeGrid documentation index

 

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 (Enum is Array from 1, CalcOrder, SortCols, SortTypes, GroupCols, GroupTypes are Arrays from 0, Formula and Action are functions). 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 (if any) to read or change row’s attribute values instead of accessing them directly.

Also use these properties as read only if possible. 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, grouping and filtering strings you can define this array.

                                               If this array is defined, all strings before sorting, grouping or filtering are modified by this array. Defining this array can slow down sorting, grouping and 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, grouping and filtering.

                                               Use rather <C CharCodes/>.

 

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.

                ! For events that return by default another value than false or null (OnRowFilter, OnGetClass) you have to define default event handler for all grids by calling it with null id.

void AddEvent (string name, string id, function func)                            Adds TreeGrid event handler for grid with given id. If id is missing, adds it for all grids.

                With this function you can have more handlers for one event and you can add and delete them dynamically

                Must not be used with SetEvent function. Must not be used with standard event assignment by Grids[name]

                Calling order of attached events is expected to be random.

                The return value for event is the first non null return value from some handler.

                This function slightly slows event execution.

void DelEvent (string name, string id, function func)                              Removes TreeGrid event handler added by AddEvent function.

                It removes only event added by AddEvent with all three parameters the same as when calling DelEvent.

 

           

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.

string OnGetEnumKeys (TGrid grid, TRow row, string col, string enumkeys)   Called for getting EnumKeys string for enum cell. Returns new enum array or enumkeys.

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 string (it is first character separated array in string).

type OnGetHtmlValue (TGrid grid, TRow row, string col, type val)                      Called to get formatted cell value to display. val is unformatted cell value.

                Returns formatted value. 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.

void OnRenderRow (TGrid grid, TRow row, string col)            Called whenever the row or its cell is being rendered or refreshed.

                Use this event to create or update some custom HTML code in the row cells,

for example when using dynamic objects via plugins like Flash, SilverLight, external JavaScript charts and so on.

                Use the GetCell method to get the cell object. Do not expect the exact cell structure, always search for your custom tags like “object”.

                col is set to column name when only this cell is being refreshed, otherwise is set to null and you need to update all your custom cells in the row.

void OnDisplaceRow (TGrid grid, TRow row, string col)                         Called when the row or its cell has been physically moved inside HTML table.

                When row is moved, this event is called also for every row’s rendered child (even not actually visible).

                Use this event to update some external objects like dynamic Flash or SilverLight that need to be updated when their parent is moved by DOM.

col is set to column name when only this cell is being moved (when moving column), otherwise is set to null and you need to update all your custom cells in the row.

This event is also called after mouse click to the cell in Firefox when NoFFDrag is not set.

void OnDisplayRow (TGrid grid, TRow row)               Called when the row has been displayed => changed its state from display:none.

                Called when the row is shown but it is not rendered. Usually when the row is shown due filtering or by parent row expand.

Use this event to update some external objects like dynamic Flash or SilverLight that need to be updated when their parent state is changed from display:none.

void OnScrollRow (TGrid grid, TRow row)  Called when the row is scrolled into visible area.

                Use this event to update some problematic external object like dynamic Flash in Firefox that cannot be displayed into invisible area due overflow

void OnScrollCol (TGrid grid, string col)                    Called when the column is scrolled into visible area.

                Use this event to update some problematic external object like dynamic Flash in Firefox that cannot be displayed into invisible area due overflow

 

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 – don’t save value and stop edit, 3 – 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.

bool OnStartDrag (TGrid grid, TRow row, string col, bool more)          Called before the row is being dragged. Return true to suppress default behavior.

                row is the caught row, col is column where the row is caught, more is true when more selected rows will be dragged together.

int OnEndDrag (TGrid grid, TRow row, TGrid togrid, TRow torow, int type, int X, int Y)                Called after the dragged row is dropped. It is called for any drop.

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

                X, Y – mouse cursor position on screen (related to browser window)

                togrid is never null, it is the last grid under mouse cursor. torow is null when no row is under mouse cursor.

Return new type or type. Remember, you must return the given type to permit dropping unchanged.

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 dropped. 

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

Return new type or type. Remember, you must return the given type to permit dropping unchanged.

This event controls dropping. To control which rows can be dragged (caught), set the row attribute CanDrag or set <Cfg Dragging> for whole grid or use OnStartDrag event.

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 delete row, 2 delete row because its parent is deleted. If row is removed by DelRow ( ), event is not fired !

void OnRowUndelete (TGrid grid, TRow row)             Called before undeleting every row – if row is unmarked as deleted. Fires for every row being undeleted, even for its children.

int OnCanRowDelete (TGrid grid, TRow row, int type)            Called before row is deleted or undeleted. 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 OnDeleteAll (TGrid grid, int type)        Called before all selected rows are deleted or undeleted by click to header panel button. Return true to suppress the action.

                type = 0 undelete, 1 delete, 2 remove. Remember, this event can be called more times, depending on Actions settings for event ClickHeaderDelete.

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.

void OnRemoveCollapsed (TGrid grid, TRow row)                   Called when the row is collapsed and its children are deleted, only if set <Cfg RemoveCollapsed=’3’/>

string[2] OnPrint (TGrid grid, Window window)                        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.

window is new window created for printing and should be closed when OnPrint returns true.

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.

void OnScroll (TGrid grid, int hpos, int vpos, int oldhpos, int oldvpos)               Called after body was scrolled

hpos is new scrollLeft, vpos is new scrollTop, oldhpos is original scrollLeft, oldvpos is original scrollTop, all in pixels.

void OnDisable (TGrid grid)            Called before grid is disabled (and modal message is shown). Can be called also for already disabled grid.

void OnEnable (TGrid grid)             Called after grid is enabled (and modal message is hidden)

void OnShowMessage (TGrid grid, HTMLElement message)   Called when any grid informational message is displayed. message is the tag showing the text.

void OnShowDialog (TGrid grid, TRow row, string col, HTMLElement Tag)       Called after the dialog or menu for the cell is displayed, Tag is HTML element with the dialog.

bool OnEvent.... (TGrid grid, TRow row, string col)                   Called when this event raised before any its action is called. Return true to suppress processing event actions.

                The name of the handler consists of the full event name including prefix and target.

                This handler is not called for parent events if they are called.

                row, col is cell that the event is related to. For the key events it is focused cell, for mouse events it is the actual cell.

                For example Grid.OnEventClickDefaults = function(G,row,col){ if(!Get(row,col+”Defaults”)) { alert(“The cell has no defaults !”); return true; } }

bool OnSetStyle (TGrid grid, string stylename)          Called before the grid style is set to stylename. Return true to suppress changing style.

void OnAfterSetStyle (TGrid grid, string stylename)                Called after the grid style is set to stylename.

               

Function events – filter, sort, search, group, 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 and searching, val is predefined value, returns val or new value.

 

bool OnSearch (TGrid grid, string Action, bool Show)             Called when searching in grid starts after user action. Return true to suppress default searching.

                                                                                                              Action can be Filter, Select, Mark, Find, Clear, Help, Refresh.

void OnSearchFinish (TGrid grid, string Action, bool Show) Called after search in grid finished, all changes are already visible.

int OnRowSearch (TGrid grid, TRow row, string col, bool found, function func, type userdata)   Called when searching in row.

col is column cell when is searching if set searching in cells - 1.bit of SearchType to 1, otherwise it is null

found is the search result. Must return new found value. 1 – found, 0 – not found, -1 not applicable (it will not be selected but also not be hidden by filter)

if set col (searching in cells), the OnRowSearch can also return column name as the cell found

func is caller function for searching row that resulted found. it has prototype func (TRow row, string col,  type userdata)

func returns -1 if cannot search, 0 if not found or 1 if found when searching in row or column name if found when searching in cells

The func and userdata parameters can be used for searching in other rows then actual. Remember from the func is called the OnRowSearch event

userdata is null in default call, use it to mark custom calling to avoid recursion cycle. Example using func and userdata:

Grids.OnRowSearch = function (G,row,col,found,F,type){ // This function searches in children to mark/unmark parent row

if(type) return found;             // to avoid recursion cycle

if(!row.firstChild) return -1;                               // not applicable for children

for (var r=row.firstChild;r;r=r.nextSibling) if(F(r,col,1)>0) return 1;

// Searches in children, if at least one found, parent is marked as found

return 0; }

 

int OnSort (TGrid grid, string col)                                                 Called when sorting grid after user action.

Return -1 to suppress default sorting completely, return 1 to suppress sorting only and let change sort icon.

col can be null if was called from control panel. Here you can call ChangeSort to modify sorting (in this case you have to return -1).

For example this code always sorts according to column named ‘B’ as second column:

Grids.OnSort = function (G,col){

var type = G.SortCols[0]==col?!G.SortTypes[0]:0;

if(!col) { col = G.SortCols[0]; type = G.SortTypes[0]; }

if(col!='B') { G.ChangeSort(col+",B",(type-0)+",0"); return -1; }

}

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, bool group)              Called to get value for sorting and grouping, val is predefined value, returns val or new value.

                desc is true for descending sorting, group is true when called for grouping

void OnSetPageName (TGrid grid, TRow page)         Called when are being generated page names for right side pager after sorting or grouping.

                page is given page, read and set its properties page.Name (HTML, page name displayed in pager) and page.Title (text, tooltip for page item on pager).

string OnGetPageNameValue (TGrid grid, TRow row, string col, string val)     Called to get value used for creating page names in right side pager val is predefined value, returns val or new value.

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

                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, string def)      Called to get default row for the group when grouping according to column

                col is column name, def is predefined name of default. Return new name of default or def.

 

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, bool show, TRow row, string col)           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 and Recalculate methods.

                If row is set, it is called to calculate only row’s children after loading of page. If col is set, it is a called after some cell changed to recalculate appropriate formulas.

                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.

type OnCalculateCell (TGrid grid, TRow row, string col, type val, bool show)   Called before cell value is calculated.

                The val is new calculated value that will be set to the cell. Returns changed val to set to the cell or null to use val.

bool OnPaste (TGrid grid, TRow[] rows, string[] cols, int startcol, string pastedtext)        Called before cell values are pasted by Ctrl+V from clipboard.

Return true to suppress default action.

                rows are rows to paste values into, cols are affected cols in that order, start is first column from cols where to start pasting (columns before are ignored),

pastedtext is string being pasted, rows are separated by CRLF, CR or LF, cells are separated by tabulator (\t, 09 ASCII).

The rows do not contain rows that will be added if Focused has set 8 or 12.

It is possible to change rows and cols array to paste the values to other cells.

If any array is modified by this function, it must be continuous without null values a must have correct length.

void OnPasteFinish (TGrid grid, TRow[] rows, string[] cols, int startcol)              Called after cell values are pasted from clipboard, parameters see OnPaste event.

bool OnExport (TGrid grid, string data)      Called after the export is created and before it is sent to server. data is the created export. Return true to suppress the export.

bool OnAutoFill (TGrid grid, TRow r1, string c1, TRow r2, string c2, rdir, cdir)                Called after cell range is selected by used in action FillCells/Row/Col, before the standard filling is done.

                r1,c1,r2,c2 is the selected cell range. r1,c1 is always the firstly clicked cell.

rdir is 0 when r2 is under r1 and 1 if r2 is above r1. cdir is 0 when c2 is right from c1 and 1 when c2 is left from c1.

                This function can be used to do to any operation in cell range created by dragging.

                Return true to suppress default behavior.

type OnAutoFillValue (TGrid grid, TRow row, string col, TRow orow, string ocol, type val, type prevval, int rowpos, int colpos)        Called when auto filling cell values by dragging by action FillCells/Row/Col, like in Excel.

                row, col is cell to fill; orow, ocol is base cell (the first cell dragged); val is predefined value to be filled.

                prevval is previously filled (returned) value, for the base cell is null.

rowpos, colpos is distance from the actual cell from the base cell = base cell has 0,0. rowpos is negative when filling up and colpos when filling left.

Returns new value or val.

For example: Grids.OnAutoFillValue=function(G,row,col,orow,ocol,val,old,ri,ci){return val+ri+ci;} – fills with increased values right down and decreased top left.

 

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 click to cell.

row==grid.XHeader for header, col==”Panel” for panel. row and col are never null.

                x, y is cursor position relative to the cell, handled is always false since V5.5 and should be ignored.

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

Returns true to suppress default Click action; The AfterClick action is called regardless on this returned value. This event is called after BeforeClick action.

                This event has been changed since V5.5. Now it is called always before any predefined click action and returned true suppresses every defined Click action!

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

row==grid.XHeader for header, col==”Panel” for panel. row or col can be null for double click outside the cells.

                x,y is cursor position relative to the cell. event is standard MouseEvent

Returns true to suppress default DblClick action; The AfterDblClick action is called regardless on this returned value. This event is called after BeforeDblClick action.

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

row==grid.XHeader for header, col==”Panel” for panel. row or col can be null for right click outside the cells.

x,y is cursor position relative to the cell. event is standard MouseEvent

Returns true to suppress default RightClick action; The AfterRightClick action is called regardless on this returned value. This event is called after BeforeRightClick action.

You can use it for example to display your custom 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 OnMouseDown (TGrid grid, TRow row, string col, int x, int y, Event event)                             Called after mouse button is pushed down above grid.

bool OnMouseUp (TGrid grid, TRow row, string col, int x, int y, Event event)                                   Called after mouse button is poped up above grid.

bool OnMouseMove (TGrid grid, TRow row, string col, int x, int y, Event event)                             Called whenewer is mouse moved above grid. Use only very short code here to not slow down the grid.

 

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 (select), 1 (unselect), 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 OnSelectAll (TGrid grid)         Called before all rows are selected or unselected by click to header panel button. Return true to suppress the action.

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

type OnCustomStartEdit (TGrid grid, TRow row, string col, string val, HTMLElement cell, int width)         Called before starting editing to display custom editing control

                val is formatted string to be displayed in edit control, cell is cell object that should be used as parent of the custom editing control, width is inner width of the cell

                when displayed custom editing control, return any nonull value – this value will be passed to OnCustomEndEdit event.

string OnCustomEndEdit(TGrid grid, TRow row, string col, bool save, type custom)      Called to finish editing by custom edit control returned by OnCustomStartEdit.

                save is 1 when value will be changed (user accepted editing), otherwise it will be ignored. custom is object returned by OnCustomStartEdit.

                returns new value to save or null to not save even if save parameter is 1.

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

                To change edited value you should rather use event OnValueChanged. Also see OnAfterValueChanged event.

                To return 1 or 2 you must handle the event, set EditMode to 0 and refresh / recolor the cell.

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, int 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.

string OnTip (TGrid grid, TRow row, string col, string tip, int clientX, int clientY, int X, int Y)      Called when tooltip is being displayed. Return new string to display or tip. Return null to not display the tip.

                clientX, clientY are mouse coordinates in browser window. X, Y are mouse coordinates in the cell row, col.

string OnHint (TGrid grid, TRow row, string col, string hint)  Called when hint is being displayed. Return new string to display or hint. hint is by default cell html content.

 

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 OnDataErrorDebug (TGrid grid, int code, string mess, string html)           Called when got server response with error code in AJAX communication.

                Called independently on Debug attribute value, html is message returned from server

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.

void OnAfterSave (TGrid grid, int result)     Called after save is done, the server response was received and changes accepted. Only for AJAX communication. result is negative for error. Called also for 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, bool cancel)      Called when reload is requested (when reloading or server side sorting/filtering/grouping),

called instead of confirming message to user. returns false to cancel action.

changed = &1 – grid contains changed rows, &2 – grid contains selected rows.

cancel is true if changes should be canceled, true if changes should be saved (when server side sorting/filtering/grouping). To save changes call Save function from this event.

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.

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

                                                                              Return true to cancel rendering

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.

int OnValidateError (TGrid grid, TRow[] rows, string[] cols) Called on validation error when saving. When set Validate attribute.

Return 0 for default behavior, 1 to cancel saving, 2 to continue saving

rows and cols are invalid cells that do not match their ResultMask.

bool OnGanttStart (TGrid grid)                      Called when Gantt chart is created for first time. Returns true to not create the Gantt chart (useful when it is already called RefreshGantt)

 

Toolbar 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, 16 Export

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>".

                This event is listed only for backward compatibility, you should display your custom code in Html type toolbar cell.

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 OnShowCfg (TGrid grid, HTMLElement Tag)                    Called after configuration menu is displayed, Tag is HTML element with the menu.

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 OnShowColumns (TGrid grid, HTMLElement Tag)          Called after menu for columns visibility is displayed, Tag is HTML element with the menu.

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 accessible by their names. 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> with variable rows <I>, in Internal format.

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

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

HTMLElement XS                              <Solid> node. This contains all solid space rows <I>, <Group>, <Search>,<SimplePager>,<Toolbar>, in Internal format.

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

HTMLElement XGroup                    <I Kind=”Group”> node. This represents grouping row, node is in Internal format. Obsolete, you should access the rows by GetRowById method.

HTMLElement XPager                     <I Kind=”Pager”> node. This represents grouping row, node is in Internal format. Obsolete, you should access the rows by GetRowById method.

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 ChangeColsPositions (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[] Show, string[] Hide, bool prefer=0)            Changes visibility of given columns

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

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

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

                Remember, if you call this function when grid is disabled (is displaying message) you have to call SetScrollBars function after enabling grid.

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

TRow GetPage (int num)                 Returns page object by page index

TRow 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.

TRow 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.

TRow 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.

TRow 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.

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

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

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

TRow 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.

                Only variable row can be added.

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).

                Only variable row can be deleted.

                Remember, deleted row cannot be used in any API function, especially take care in loops, you cannot use GetNext / GetPrev functions with delete row.

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, int copy = 1)                     Moves or copies row to another (or the same) grid.

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

                If copy is 1, row is not deleted from source grid. If copy is 2, copies only row, without its children. 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.

TRow CopyRow (TRow row, TRow parent, TRow next, TGrid grid, bool deep, bool empty)           Copies the row to parent before next (like Add), G can be grid to that is row copied

                If deep is true, copies include children, only visible (not filtered, not deleted). Does not test if copying is possible, does not show changes

Before use is better to set AutoUpdate to false. Returns the row copy.

void  CopyRows (TRow[] rows, TRow parent, TRow next, TGrid grid, bool deep, bool empty)      Copies the row to parent before next (like Add), G can be grid to that is row copied

                Copies all rows in rows array to parent before row next (like Add), G can be grid to that is row copied.

                If deep is true, copies include children, only visible (not filtered, not deleted).

                Shows all changes.

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.

Since TreeGrid 4.7, every row can be displayed, including solid and fixed rows.

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.

Since TreeGrid 4.7, every row can be hidden, including solid and fixed rows.

 

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, int type=0, int maxrender=500)                              Expands all rows.

maxtime is time in milliseconds to wait for finish. After that time function stops and returns.

type is ExpandAllType. maxrender is maximum rows that will be rendered when expanding. It this limit is exceeded, expanding stops.

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

so be careful in setting the parameter values too high.

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

void ChangeDef(TRow row, string def, bool show = true)       Changes Def attribute of the row to default named def. If show=true it refreshes row and shows the changes.

                It does not update row values, so cell types should not be changed by switching to the new default or must be updated externaly.

 

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

void UpdateRowHeight (TRow row)             Updates height of all row sections to be the same, use when set VarHeight=’1’.

 

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 [row,col].

If row represents a page set pagepos to expected row’s position (index) at this page (when server paging used and page is not loaded yet).

 

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.

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

This function sets only column Width attribute, does not resize the column.

 

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.

int GetScrollLeft ( )                                                         Returns actual horizontal scroll of body, in pixels

int GetScrollTop ( )                                                          Returns actual vertical scroll of body, in pixels

 

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.

void ShowTip (int x, int y, string tip, string class)     Displays custom tooltip on the (window) location. tip is the HTML to display, class is its css class.

void HideTip ( )                                                                 Hides the actually displayed tooltip

void ShowHint (TRow row, string col)                          Shows the cell value as hint tip, but only if it does not fit into the cell.

void HideHint ( )                                                               Hides the actually displayed hint tip

void Prompt (string text, string default, function func, int width)           Replacement for standard JavaScript window.prompt function. It is asynchronous.

                text is message text, default is default value, with is optional width in pixels of the message box.

                function func(val) is called after user enters the value. The val is entered text or null when user clicked to Cancel.

 

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.

int GetEnumIndex (TRow row, string col, string val)               Returns index to enum array as Enum value. Searches also in EnumKeys if set.

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)          Makes custom AJAX call, for sending and receiving requests independent on TreeGrid.

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 or newly created Object.

DataIO must have set DataIO.Url and optionally DataIO.Param string array for sending parameters and DataIO.Data for sending Data parameter.

! The server response must be in XML, with root tag named <Grid>, for example “<Grid>my data</Grid>”.

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.

Example:

function myfunc ( ){

var T = new Object; T.Url = "Myurl.jsp"; T.Param = new Object; T.Param["Myparam"] = "Myvalue"; T.Data = "Data";

Grids[0].Communicate(T,"Mydata",myfuncfinish);  

// On server you will get HTTP POST request like submitted form with Myparam=Myvalue&Data=Mydata

// The server must return XML string <Grid>... any data or tags ...</Grid>

}

function myfuncfinish(err,xml) {

if(err<0) { alert("Error"); return; }  

alert(xml.xml); //... parse the received xml document here and do action you want

}

void Communicate2 (object DataIO, string Data, function Func)        Makes AJAX call, for receiving changes from server and adding them automatically.

Sends Data to the server and adds its response XML to grid. The server response should return changes in <Grid><Changes>...</Changes></Grid>.

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

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.

                Basically, it calls Communicate2 function with grid configuration as request in Data parameter.

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.

! The Data.Data source can contain only variable rows, all other definitions like columns, fixed rows and so on must be Data.Layout.

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.

                To reload grid just call it without parameters: grid.Reload();

                To reload grid from different url just specify the url in actual TDataIO: grid.Data.Data.Url = “NewUrl”; grid.Reload();

                ! Remember, after calling this function, the old grid is deleted and new one is not yet created, because this function is asynchronous.

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 Dispose ( )                   Completely removes the grid. Calls Clear(1) and removes the Grid from Grids under its id.

                It does not remove the grid from Grids under its index, because there can be pending asynchronous actions (like data loading or rendering) attached to the index!

                New grids should not be added under already used indexes unless you are sure there are no pending actions.

                To remove all grids from page you can use such code:  for(var i=0;i<Grids.length;i++) if(Grids[i]) Grids[i].Dispose(); Grids.length = 0;

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. Asynchronous, 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 SetSession(string Session)       Sets grid Session attribute that identifies it in server requests. Usable especially to clear it when wanted to start new session with new data.

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. To get page object by index use GetPage method.

void GoToNextPage ()     Scrolls or moves to next page.

If you call this function from external button onclick, you should cancel the event by adding CancelEvent(event) to your handler or use StaticCursor=’1’ to preserve grid from loosing focus.

void GoToPrevPage (int cnt)         Scrolls or moves to previous page.

If you call this function from external button onclick, you should cancel the event by adding CancelEvent(event) to your handler or use StaticCursor=’1’ to preserve grid from loosing focus.

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.

void CreatePages ( )          Re-creates pages. After call must be called Render to re-render the grid. Useful when page length was changed.

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.

                ! It maybe required to call SetScrollBars after the page is added.

void RefreshPage (TRow page, bool always = 0)                      Re-renders page or row’s children. For always = 1 re-renders the page also if it is not visible due scroll or expand state.

void ReloadPage (TRow page)       Clears page data and reloads them from server, only when set server paging. Can be used also to reload row’s children, only when used server child paging.

 

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.

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 RefreshGantt (int show = 1, string col = null)                    Recalculates Gantt chart(s).

Also shrinks chart to show only used date range

                For show = 0 does not display changes, re-render will be needed.

                When col set, recalculates only chart in this column, otherwise recalculates all charts in grid.

void RefreshGanttDependencies (int show = 1, string col = null)          Recalculates and redraws Gantt chart dependencies, useful when some rows show / hide.

object GetGanttXY (TRow row, string col, int x, int y)            Returns gantt objects on given position. x, y is the position inside the cell.

                The object has set these properties when given tag is on the given position:

                               HTMLElement Main – the main tag chart (specified by Start and End date), for incomplete task it is the one part on the given position (completed or not complete).

                               HTMLElement Main2 – the second main tag chart for incomplete tasks – the one that is not on the given position

                               int MainPos – position of the Main tag – 0 alone, 1 left side, 2 – right side

                int MainType - type of the Main chart tag, can be null (complete is null), 0 (not started tag), 10 (not yet completed part), 90 (already completed part), 100 (completed tag), Milestone

                               int MainX – the X position inside the Main chart tag.

                               HTMLElement Flow – the flow tag on given position

                int FlowIndex – index (from 0) of the Flow tag when the flow is not continuous and more flow tags exists in the cell

int FlowX – the X position inside the Flow tag

                               HTMLElement Flag – the flag tag on given position

                               int FlagIndex – index (from 0) of the Flag tag when the cell contains more flags

                               string DependencyStartLeft – list of ids of all rows that are connected from this left side. The ids are separated by Lang.ValueSeparator (‘;’ by default)

                               string DependencyStartRight - list of ids of all rows that are connected from this right side.

                               string DependencyEndLeft - list of ids of all rows that are connected to this left side.

                               string DependencyEndRight - list of ids of all rows that are connected to this right side.

void ChangeSort (string cols, string types, bool nosort)          Sorts grid according to given columns. cols and types are comma separated values or JavaScript arrays.

If nosort is 1, does change SortCols and SortTypes and sort icons but does sort the grid.

If it is called from OnSort event, the event handler must return -1 to proper sort.

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

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 ChangeFilter (string cols, string values, string operators bool nofilter)     Filters grid according to given columns. Sets only the first filter row if there are more.

cols, values and operators are comma separated values or JavaScript arrays. All must have the same length.

cols are column names, values are values for given filter cells and operators are filter operator numbers 0 - 12, see cell attribute Filter.

                If nofilter is 1, does change the filter cells but does not filter grid.

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 FilterTextRange (string col, string val)              Creates new filter and applies it to grid. Shows all rows containing any item from range val in their range value in column col

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 SearchRows (string action, bool noshow)          Calls DoSearch asynchronously, for server paging reloads grid

void DoSearch (string action, bool noshow)               Runs specified searching action in grid. action can be standard search action “Filter”, “Select”, “Mark”, “Find” or can be

                “Refresh” – runs actual action (SearchAction) again. ”Clear” – clears actual action and restores original state. “Help” – shows help

bool DoAction (TRow row, string col)           Runs cell Action script, if any. Returns true if cell contains Action attribute.

 

bool SetStyle (string StyleName, bool repaint = 0)     Changes TreeGrid style. It chooses from predefined styles in <Styles> tag. Switches to style named StyleName.

                Returns true if style name exists in <Styles> otherwise returns false. If set repaint, re-renders grid to choose changes.

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”

                Obsolete, use SetStyle instead.

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)                        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.

                To use this function as expected, set <Cfg PrintRows=’0’/> - to behave synchronously.

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

void ChangeAction (string name, string action)        Changes grid action in Actions. name is action name, action is function code.

 

Class TToolbar

This object is obsolete. Use toolbar actions instead.

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

 

5.0

Added OnDataErrorDebug event

Updated OnSort event

Added ChangeSort and ChangeFilter methods

Updated OnRenderStart event

Added Toolbar methods GetChecked and Check

Updated ExpandAll method

Added OnSearch, OnSearchFinish and OnRowSearch events

Updated ShowRow and HideRow

Added DoSearch, SearchRows and DoAction methods

Removed properties XGroup, XPager

Corrected events OnRowDelete, OnSelect, OnGetDefaults, OnGetGroupDef

Corrected event OnCalculate and removed OnRecalculate (it was never called)

Updated OnGetSortValue and OnGetFilterValue events

 

5.0.3

Updated GoToNextPage and GoToPrevPage

Added AddEvent and DelEvent functions

 

5.0.4

Added GetScrollLeft and GetScrollTop methods

 

5.0.5

Added OnScroll event

 

5.0.6

Added OnPaste and OnPasteFinish events

Added RefreshPage and ReloadPage methods

Added GetPage method

Added OnEnable and OnDisable events

Modified GetPrintable method

 

5.0.10

Added OnShowDialog, OnShowCfg and OnShowColumns events

 

5.0.11

Added OnSelectAll and OnDeleteAll events

Updated description for Communicate, Communicate2 and DownloadData methods

Added OnExport event

 

5.1

Added CopyRow and CopyRows methods.

Updated OnPaste event

Added SetSession method

Added UpdateRowHeight method

 

5.5

Added OnStartDrag event

Added OnSetPageName and OnGetPageNameValue events

Addec ChangeAction method

Marked obsolete – TToolbar, OnGetUserPanel

Added OnAutoFill and OnAutoFillValue events

Added SetStyle method and marked ChangeStyle obsolete

Added OnEvent... handler

Updated OnClick, OnDblClick and OnRightClick. OnClick changed its functionality!

 

5.5.4

Added OnEndDrag event

Added OnSetStyle and OnAfterSetStyle events

 

5.5.5

Added OnRemoveCollapsed event

 

5.6

Corrected information about return values 2,3 of OnResultMask

Updated OnDeleteAll event, added parameter type

Added OnRowUndelete event and updated OnRowDelete event

Added OnAfterSave event

Added OnGetHtmlValue event

Updated OnPrint event

Added methods ShowTip, HideTip, ShowHint, HideHint

Added event OnTip

 

5.6.4

Added OnGetEnumKeys

Added GetEnumIndex method

 

5.6.5

Removed OnCanShowPanelItem event

 

5.6.8

Added OnHint event

 

5.6.9

Added OnShowMessage event

 

5.7

Added RefreshGantt method

 

5.8

Added OnRenderRow event

Added OnDisplaceRow event

Added OnDisplayRow event

Added OnScrollRow and OnScrollCol events

Added OnCalculateCell event

 

5.9

Added OnMouseDown, OnMouseUp, OnMouseMove events

Added GetGanttXY method

Added Prompt method

Added OnGanttStart event

Added parameter group to OnGetSortValue

Added RefreshGanttDependencies method

Added FilterTextRange method

Added ChangeDef method

Added Dispose method

Added CreatePages method

 

5.9.2

Added OnCustomStartEdit and OnCustomEndEdit