Editing cells

FastGrid documentation

Editing

If permitted editing cells in the grid.
-1 - complete no editing, no cell can be edited or its link changed. Hides List, Date and Filter icons and the List (except Popup toolbar button), Date and Filter dialogs cannot be shown.
0 - no editing, sets cell with NoEdit = 0 to 1. Hides List, Date and Filter icons and the List (except Popup toolbar button), Date and Filter dialogs cannot be shown.
1 - permitted editing, does not change anything.
2 - read only, sets cell with NoEdit = 0 to 4. Permits List / Date / Filter icons and the List, Date and Filter dialogs can be shown, but cannot change the cell value or filter.
If the cell is editable. Affects standard editing cell, changing Bool cell, changing Check icon and showing List, Date and Filter dialogs.
Not editable cells hide List, Date and Filter icons and the List (except Popup toolbar button), Date and Filter dialogs cannot be shown.
Options 0, 1, -1 can be changed by action SetNoEdit.

0	edit, mark, lock	cell is editable and marked editable, but is further affected by Editing / Lock. Can be locked by SetNoEdit.
1	noedit, mark, locked 0	cell is not editable and marked as not editable. Used as locked option 0 and can be unlocked by SetNoEdit.
2	noedit, mark	cell is not editable and marked as not editable.
3	noedit	cell is not editable and not marked as not editable.
4	readonly, mark	cell is read only and marked as read only. Permits List / Date / Filter icons and the List, Date and Filter dialogs can be shown, but cannot change the cell value or filter.
-1	edit, mark, unlocked 0	cell is always editable and marked editable and not affected by Editing / Lock. Used as unlocked option 0 and can be locked by SetNoEdit.
-2	edit, mark	cell is always editable and marked editable and not affected by Editing / Lock.
-3	edit	cell is always editable and not marked editable and not affected by Editing / Lock.

Default value is 0 for normal cell, -3 for normal toolbar cell, 3 for toolbar icons and special rows, -2 for filter rows.
Options for editing, bit array:
1. bit &1 = 0 - always edits the value, 1 - edits the JavaScript formula result, if the cell has set JavaScript formula.
If and how the cell accepts entering LF by Enter key.
0 - Any Enter always finishes (accepts) the editing.
1 - Enter / Shift+Enter inserts LF. To finish editing press Ctrl+Enter / Alt+Enter.
2 - Ctrl+Enter / Alt+Enter inserts LF. To finish editing press Enter / Shift+Enter.
3 - Any Enter inserts LF. To finish editing use mouse.
&4 - Enter+Shift behaves the same as Ctrl+Enter / Alt+Enter.
To permit multiline text the cell must have set also 3.bit (&4) in Wrap!
How Enter key can start and finish editing. Used only in Actions code in Defaults.js

0	Start / finish editing	During editing Enter accepts and finished editing according to AcceptEnters. If pressed in normal mode it starts editing focused cell.
1	Vertical tab	During editing Enter accepts and finished editing according to AcceptEnters and moves focus down. If pressed in normal mode it moves focus down and does not start editing. If focused last row it focuses cell in the next column in the first row. Shift + Enter moves focus up. On the first row it moves focus to previous column in the last row.
2	Add row below	Like 1, but if focused last row it adds new row below and focuses its cell in the same column.
3	Add row above	Like 2, but on Shift+Enter if focused first row it adds new row above and focuses its cell in the same column.

When the editing starts.
0 - only on double click cell.
1 - on double click cell or click to focused cell.
2 - on double click or click to focused or not focusable cell.
3 - on click to cell.
&4 = 4 starts editing focused cell on any character key press, 0 - only on press of F2 and Enter.
&8 = 8 if the grid is in edit mode and is focused next cell (Enter/Tab/KeyUp/KeyDown), it starts editing the next cell.
Position of caret on start editing.
&3 = 0 - select whole text, 1 place caret on end, 2 - place caret on start.
&4 = 4 - on mouse click places the caret on the mouse position in the text, 0 - uses the value 0/1/2 also for mouse click.
&8 = 8 - on touch places the caret on the touch position in the text, 0 - uses the value 0/1/2 also for touch.
How the input is resized during editing according to its entered text.
&3 - If the input can resize according to its text width and overlay the next and previous cells: 0 never, 1 according to original cell text overlay, 2 - according to Overlay, 3 - always.
&4 - Increases column width if it has set Width = null.
&8 - Shrinks column width if it has set Width = null.
&1 - Vertical overlay of multi line to the below cells (only if set Wrap), regardless on values in the next cells.
&2 - Vertical overlay of single line to the below cells (except if set Wrap), regardless on values in the next cells.
&4 - Increases row height if it has set Height = null.
&8 - Shrinks row height if it has set Height = null.
&16 - Never shows vertical scrollbar if the text is higher than textarea.
For how many pixels can be reduced padding bottom during editing to not exceed the edited cell height.
It is applied only if the reduced edit height does not exceed the cell height.
It is used to not overwrite bottom cell border just for a few pixels or for EditResizeHeight&3 to not exceed to next cell just because of a few pixels.
If set as floating point less than 1, it is multiplied by line height and rounded. The default 0.2 means 3px for default 16px line height.
Background color shown when editing the cell. Use especially for non Html cells.
Text color used when editing the cell. Used only for non Html editing.
Predefined value that is set to cell by action SetNoEdit.
The default value 166 for sheet is because default FormulaNoEdit is -1 instead of null in sheet.
If set, shows cancel edit button on right side in the edited cell. By default set to 1 on tablet. Minimal width of input during editing, in pixels.
If the available width for the input is less than this value, the cell horizontal margin and padding is reduced.
Used only if EditResizeWidth&3<=1 and cell Overlay&1 = 0.
id of the toolbar cell that will be used as ExternalEdit like the expression cell in MS Excel. There can be only one ExternalEdit cell in grid.
The ExternalEdit edit cell mirrors the focused cell value and permits editing it in more space.
There is predefined default Toolbar "Edit" with cell "ExternalEdit" that can be used like in MS Excel.
If set, enables permanent editing to show IME editor also on the first character entered to start editing, for Japanese, Korean and Chinese languages.
Ignored on tablet because it would show the virtual keyboard forever. Sets the ime to IME.
Starts editing actual or focused cell. Fails if the cell is already edited.
For empty = 1 starts editing the cell with empty value instead of original value.
Focuses actual cell. If the cell is already focused cell, starts editing it.
For empty = 1 starts editing the cell with empty value instead of original value.
action is the same as in SetFocus.
Finishes editing. For save = 1 saves edited value to the cell, for 0 discards the change.
Sets editing permission on the actual cell or on all focused cells.
Sets only value -1, 0, 1, if cell NoEdit / NoEditStyle / FormulaNoEdit has another value, the change is not done.
value &3 - changes NoEdit; 0 - no change, 1 sets attribute to -1, 2 clears the value or if row / col has NoEdit, sets cell attribute to 0, 3 - sets attribute to 1.
value &12 - changes FormulaNoEdit; 0 - no change, 4 sets attribute to -1, 8 clears the value or if row / col has FormulaNoEdit, sets cell attribute to 0, 12 - sets attribute to 1.
value &48 - changes NoEditStyle; 0 - no change, 16 sets attribute to -1, 32 clears the value or if row / col has NoEditStyle, sets cell attribute to 0, 48 - sets attribute to 1.
value &192 - changes NoEditLink; 0 - no change, 64 sets attribute to -1, 128 clears the value or if row / col has NoEditLink, sets cell attribute to 0, 192 - sets attribute to 1.
JSON event handler (JavaScript code in string) called after the cell value is changed by a user - by editing the cell or changing it from the list or menu.
The Event object contains special property Value as original cell value before change, Formula as original cell editable formula, if any, before change and List set to 1 if changed from list or menu.
If the code is defined in string, the special variable Value contains actual value. For example OnChange:"if(!Event.List&&Value>10&&Event.Value<5) Grid.SetValue(Row,Col,Value-10);" conditionally decreases the entered value by 10.
For editing it is called only if the entered value is different from cell value or the cell value is calculated by JavaScript formula. For setting from List it is called also if chosen the same value as the cell already has. Starts editing given cell. Fails if the cell is already edited.
For empty = 1 starts editing the cell with empty value instead of original value.
Finishes editing. For save = 1 saves edited value to the cell, for 0 discards the change.
If set noevent does not call API events: &1 - OnEndEdit, &2 - OnEndedEdit, &4 - OnValidate.
Called before editing in cell row, col is started.
value is the string that will set for editing.
If set test, it is called just for testing if the editing can be started.
Return true to not start editing. Or return string to edit different value.
Called after editing of the cell row, col started and the input / textarea is created and shown.
Here is possible to call GetEdit to get edit input / textarea and assign own event handlers for custom editing.
Called when editing finished, before the entered value was set to the cell row, col.
save is 1 if the value will be saved to the cell and 0 if the editing was canceled.
Return true to continue editing. Return -1 to always cancel editing and discard the value.
Return string to set it to the cell instead of value, only if set save.

For example to display confirmation message about saving the value:
FGrid.OnEndEdit = function(G,row,col,value,save){
if(!save) return;
G.ShowMessage( { Text:"Save the value '"+value+"' to cell "+col.id+row.id+"?", Buttons:"Ok,Cancel" }, null, function(but,idx){ if(idx==0) { G.EndEdit(1,1); G.Paint(); } });
return true;
} Called after the entered value was set to the cell row, col on save = 1 or the original cell value was restored on save = 0, but before the grid was painted.

During editing

Controlling entering text to cell in input or textarea. Returns positive value if edit is running, otherwise returns 0.
It returns &1 - if edit is running, &2 - if edit is multiline (in textarea, Wrap is set), &4 - if edit is html (in contenteditable div, for Type="Html" or "Auto" with AutoHtml). If editing is running returns array as [editrow,editcol,edittag]. Otherwise returns null.
editrow and editcol is actually edited cell, edittag is HTMLTag input, textarea or div with contenteditable.
Selects text or moves caret in the edit input.
start and end is selection position or can be set as negative: -1 = end, -2 actual position of the bound, -3 actual position of the other bound.
Selects text or moves caret in the edit input.
start and end is selection position or can be set as negative: -1 = end, -2 actual position of the bound, -3 actual position of the other bound.
Inserts given text to caret position in the input. Removes the selected text.
If set select, selects the inserted text, otherwise places caret after the text.
Returns actually edited text.
Sets given text to the edited value.
Called after edit input value changed by pressing some key or inserting text.
value is actual new value in the input, oldvalue is original value in the input.
correct is set if change passed EditMask and SuggestComplete.
Return true to cancel the change.
Return -1 to permit change even if correct is false.
Return -2 to permit change even if correct is false and animate the input like an error.
The event handler can change the input value by SetEditValue and SelectEdit and return negative value to accept the change.
To control entering characters in Number and Date types by API first define some EditMask to disable internal validation for these types.

Validation and errors

Validation of entered values in cells and marking cells with incorrect values.

Standard JavaScript RegExp string to validate the entered text during editing to cancel unsuitable changes. The RegExp string is searched in the input text and if it is found, the input text is valid.
In the RegExp string are the backslashed doubled, like "^\\w+$" permits only letters and numbers and underscore.
If the validation fails, the input shortly blinks and the input text change is not permitted.
Do not set the EditMask too restrictive to not complicate editing, do exact checking rather in ResultMask.
To more control the entering text during editing use OnEditChange event.
Standard JavaScript RegExp string to validate the entered text on save to the cell value to restrict unsuitable values.
The RegExp string is searched in the text and if it is found, the text is valid.
In the RegExp string are the backslashed doubled, like "^\\w+$" permits only letters and numbers and underscore.
If the validation fails, the input shortly blinks, the save is not done and editing continues.
To more control the entering text on save use OnEndEdit event.
If set and edited text violates the ResultMask, it permits saving the incorrect value, but the cell gets the ResultError as Error.
If defined ResultMessage, it gets "ResultError" default message to ask to save or not.
Message shown when the ResultMask validation failed. It can be string or JSON message like ShowMessage.
If it has not set D attribute, it uses default message "Result" or "ResultError" (if set ResultError).
It can be set to "$Result" (inform) or "$ResultError" (inform and ask) to show predefined texts.
If and how permits validation of changes before saving them to server.

&3	What will be validated: 0 - no validation, 1 - only added rows / columns, 2 - added rows / columns and all changed cells, 3 - all cells
&4	If set, iterates all suitable cells and sets the invalid cells as error and colors them red. If not set, stops validation after the first invalid cell.
&8	If set, removes error from all the cells that passed the validation.
&16	If set, shows on validation error the ResultMessage if defined for the cell.
&32	If set, starts editing the first invalid cell, if possible.

Message shown when the ResultMask validation failed and Validate has not set &4 or no ResultMessage is defined for the cell. It can be string or JSON message like ShowMessage.
It uses default message "Result" if it has not set D attribute.
If set, the row / column / toolbar is not tested during validation by Validate.
By default it is 1 for all special rows and columns and for all toolbars and 0 for data rows.
Validates the grid data according to the Validate settings.
Iterates all the specified cells. For every cell tests ResultMask, if any, and calls OnValidate, if defined.
If the cell validation fails, the cell is focused, ValidateMessage is shown and the Validate action returns false.
Called after checking ResultMask to validate the result.
If set edit = 1, it is called on save edited value to the cell, for 0 it is called during grid validation by Validate.
value is value to save to the cell, error is set if the value violates ResultMask, if any.
Return 1 to accept the change, -1 to reject the change and blink error, -2 to reject the change and not blink error, or null to continue according to the error.
Array or first character separated string of error cells. Every error cell is defined by three values as row id, column id, error value.
Possible formats: "|row1|col1|error1|row2|col2|error2|..." or ["row1","col1","error1","row2","col2","error2",...] or [["row1","col1","error1"],["row2","col2","error2"],...]
If Errors are defined more times in the input data, they are joined together, except if the first item is "-".

Cell error can be automatically set or cleared by Validate and it is automatically cleared if the cell value is changed.
Returns an error for given cell.
Sets the error for given cell. If the error is null, clears error for given cell.
Returns error cells in standard two dimensional array as [[row1,col1,error1],[row2,col2,error2],...].
It is slow, because it creates the array.
Returns count of error cells.
Clears all errors in grid.