Focus and hover cells

FastGrid documentation

Focus cell and cell ranges

Focused cell is the cell that receives key events.
Focused row is the row containing focused cell.
Focused column is the column containing focused cell.
First focused range is cell rectangular range that contains focused cell, it is used by actions taking focused cells.
Next focused ranges are cell rectangular ranges that don't contain focused cell, they are used by actions taking focused cells.
Focused ranges are defined as [row1,col1,row2,col2]. The rows or columns can be missing in the definition to focus the whole columns or rows.

Default focus and select behavior is for grid - focus single cell and independent row and column selection.
For sheet focus and select behavior set Cfg: { Focus:51, SelectRows:0, SelectCols:0 } - focus cell ranges and manipulate them.
Focused cell(s) on grid start. It can be set as array of strings or comma separated string.
First pair is focused row and focused column, next quaternions are focused cell ranges, the first quaternion can contain the focused cell to be used as the first focused cell range.
It can be set also as cell names and cell name range like in editable formulas.
For example:
Focused: [2,"E",1,"D",3,"G",5,"A",7,"C",9,"B",11,"G",13,null,14,null,null,"H",null,"I",4,"A",null,null] - items by ids
Focused: "2,E,1,D,3,G,5,A,7,C,9,B,11,G,13,,14,,,H,,I,4,A,," - items by ids
Focused: ["E2","D1:G3","A5:C7","B9:G11","13:14","H:I","A4"] - items by indexes, can add auto rows / columns
Focused: "E2,D1:G3,A5:C7,B9:G11,13:14,H:I,A4" - items by indexes, can add auto rows / columns
Focused cell is "E2", first focused range is "D1:G3".
If set, ignores Focused attribute on start. Ignores also focus and selection settings in xlsx.
If and how the table cells can be focused.
0 - no cell focus, 1 - single cell focus, 2 - cell range focus, 3 - more cell ranges focus.
1. bit &1 - if shows bottom right corner in focused cell range for auto fill. Applicable only for Focus = 2 or 3.
2. bit &2 - if permits moving and copying focused cell range by dragging its edge.
Used instead of FocusActions on touch screen. If and how the whole row will be highligted for focused cell.
0 - no, only the focused cell will be highlighted, 1 - the row in the same columns section will be highlighted, 2 - the whole row will be highlighted.
List of ColPart ids that will be focused when focusing this part and Cfg FocusRow = 1.
If both ColPart and RowPart have set FocusRow, the ColPart attribute is preferred.
If and how the whole column will be highligted for focused cell.
0 - no, only the focused cell will be highlighted, 1 - the column in the same rows section will be highlighted, 2 - the whole column will be highlighted.
List of RowPart ids that will be focused when focusing this part and Cfg FocusCol = 1.
If both ColPart and RowPart have set FocusCol, the RowPart attribute is preferred.
If the toolbar cells can be focused.
If the focus cursor will be cleared when the grid loses focus.
0 - no, the focused cell(s) will be still focused, although the focus in grid cannot be changed by keys.
1 - clears the focus when the grid loses focus.
2 - clears the focus also when clicked to empty area in the grid or to not focusable cells.
How the focused cell will be aligned in grid, bit array:

1.,2.bit	&3	vertical align, 0 - top, 1 - bottom, 2 - middle, 3 - inside - minimal scroll
3.,4.bit	&12	horizontal align, 0 - left, 4 - right, 8 - center, 12 - inside - minimal scroll

How the focused cell will be aligned in grid on start, bit array:

1.,2.bit	&3	vertical align, 0 - top, 1 - bottom, 2 - middle, 3 - inside - minimal scroll, usually bottom
3.,4.bit	&12	horizontal align, 0 - left, 4 - right, 8 - center, 12 - inside - minimal scroll, usually right

If cell focus is restricted, bit array:

1.bit	&1	the cell cannot be set as the focused cell, but still can be included in focused cell range.
2.bit	&2	does not highlight the whole focused row
3.bit	&4	does not highlight the whole focused column (highlight of whole column is disabled when defined more column sets).

The not focused cell can be still edited, to restrict editing cell set NoEdit=1.
&1 - if toolbar cell focus by mouse / touch is restricted.
&2 - if toolbar cell focus by arrow keys is restricted.
0 - does not display focus and hover border in edge cells, because it cannot be shown outside the part.
1 - displays focus and hover border also in edge cells, inside them.
If set to 1, shows cursor for the whole rows / column for whole spanned range instead of top left cell.
If set to 2, shows cursor for the whole rows / column also for the whole focused range instead of top left cell.
If set, the grid does not catch key events, to control the grid keys from its parent grid or other component. Used for Suggest menu.
Width in pixels of focus cursor edge for mouse hover.
Focuses actual cell.
action is the same as in SetFocus.
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.
Focuses next cell(s) in given direction dir = 0 - down, 1 - up, 2 - right, 3 - left.

options specifies various settings, bit array:

1.bit	&1	extend	1 - extends actual focused rectangle in given direction. 0 - moves the focused cell.
2.bit	&2	page	moves or extends the focus by the whole page.
3.bit	&3	editable	moves or extends the focus only to editable cell.

If set tab and the focused cell is the last one in given direction, moves focus to the next row / column and on the opposite edge of grid or focused range.
If there is focused range, the tab values more control the behavior: 1 - iterates spanned cell only once on the first row / column, 2 - iterates the spanned cell on every row / column, 3 - clears focused range and tabs only one focused cell.
Focuses the whole actual row.
action is the same as in SetFocus.
Focuses the whole actual column.
action is the same as in SetFocus.
Focuses the whole grid, all columns and rows.
If set range and only one cell is focused, it extends focus to the nearest surrounding range of cells.
Focuses cells by mouse dragging.
type = 0 cells range, 1 - whole rows range, 2 - whole columns range.
action 0 set focus, 1 - add focus, 2 - remove focus, 3 - add or remove focus, 4 - extend and auto fill rows or columns, 5 - extend and auto fill rows and columns, 6 - move focused cells.
autofilltype is used for action = 4 / 5 auto fill, if not set, AutoFillType is used.

Sets focused cell and range and updates next focused ranges.
row can be row or toolbar to focus. It can be null to focus the whole column.
col can be column or toolbar cell to focus. It can be null to focus the whole row.
If row and col are null, removes the focus from the grid.
range is array as [row1,col1,row2,col2] to focus as range or null to focus single cell.
If cell row, col is outside range, it adds the range to the next focused ranges if permitted by action or ignores it.

action specifies the focus action. It is used only if set Focus&3 = 3 otherwise 0 (set) is used.

0	set	sets focused cell to row and col and focused range to range and clears other focused ranges.
1	add	adds actual focused range (or focused cell if actual focused range is null) to next focused ranges and sets focused cell to row and col and focused range to range.
2	remove	removed the cells in the range (or the cell row, col if range is null) from all focused ranges. If the removed cells removed also focused cell and focused range, uses the last range from the next ranges as focused cell / range.
3	add or remove	it chooses 2 if cell row, col is focused, otherwise 1.
array	set all	action can contain array of rects to be exactly set as the next focused rectangles. It always clears the previous focus and does not check if the focused area changed.

options specifies various settings, bit array:

1. bit

&1

show

show the cell - expand parent rows and columns, show hidden row and column.

scroll specifies if and how the focused cell will be scrolled into view, value the same as AlignFocus or -1 as no scroll.

Returns false if no change in focus was done, null if the focus cannot be changes.
For focus change returns positive number with more information as bit array: &1 - scrolled vertically, &2 - scrolled horizontally, &4 - Paint called, &8 - Paint needed, &16 - always set.

Paint is needed only if modified next focused ranges, by action > 0.
If not set options&8 it calls Paint if there are some pending changes in the part.
Variant of SetFocus method that focuses given cells by their indexes like SetFocus("A3;A2:B6;C6;C8:E10"). Only if set RowIndex and ColIndex.
If the cells do not exist, it creates enough rows in rowpart and cols in colpart to create the indexed cell.
The cells can contain also defined name containing cell reference.
The first item in cells can be a reference to single cell that is contained in the second cells range to specify main focused cell in the first focused rectangle.
If the cells contain cells from another sheet, it switches to the first sheet in cells and focuses the cells here.
action, scroll, options and return value are the same as default SetFocus method.
Returns actually focused cells in one dimensional array.
First two items are focused row, focused column.
Next four items is focused range as top row, left col, bottom row, right col.
Next quaternions are next focused ranges, if any.
If there are focused whole rows or columns, the returned array never includes nulls, but includes the first and last column / row in grid and contains also attribute Full as array of integers for every focused rect as 1 - whole rows, 2 - whole columns.
If no cell is focused, returns empty array.
If set str, returns string as range of focused cells (like "A2;A1:C3;7:10"). For str&1 includes focused cell, for str&2 includes focused range, for str&4 includes other selected ranges.
Returns actually focused row or null.
Returns actually focused column or null.
Returns positive number if the cell is focused. Returns 1 if it is focused cell, 2 if it is in focused range or 3 if it is in next focused ranges.
The row or col can be null to check the whole row or column contains some focused cell.
Iterates all focused cell and for every cell calls func(row,col).
If the func returns true, the IterFocus ends.
The func is called only once for every the focused cell, even if the focused ranges overlap.
As the first cell it always gets focused row / focused column.
If set visible, iterates only visible rows and columns.
Scrolls the part to make the row and / or col visible.
If set range as [row1,col1,row2,col2] makes the whole range visible. row1, col1 must be top left corner. In this case the row, col is used only if the range bigger than the view.
scroll specifies how the focused cell will be scrolled into view, value the same as AlignFocus.

Returns 0 if no change in scroll was done or positive number as bit array: &1 - scrolled vertically, &2 - scrolled horizontally, &4 - Paint called.
It calls Paint if there are some pending changes in the part.
Assigns key focus to this grid. Only one control on page can have key focus.
If the previous grid with key focus has set ClearFocus, removes also its focus cursor.
Returns true if the focused grid was changed. Removes key focus from this grid. If set ClearFocus, removes also focus cursor from the grid.
Returns true if the focused grid was changed. Called before the focused cell(s) is changed to row, col and rect.
rect is set [top_row,left_col,bottom_row,right_col,whole], where whole can be 1 when focused whole rows, 2 whole columns or 3 all.
action is like the action in SetFocus.
drag is set when calling the OnFocus during dragging focus. After the focus is dragged, the OnFocus is always called again with drag as null.
test is set when just testing focus possibility, in this case the function should not do any action.
Called after the focused cell(s) has been changed.
drag is set when calling the OnFocused during dragging focus. After the focus is dragged, the OnFocused is always called again with drag as null.

Mouse hover cells

If the table cells are hovered = highlighted under mouse cursor.
If and how the whole row will be highligted for hovered cell.
0 - no, only the hovered cell will be highlighted, 1 - the row in the same columns section will be highlighted, 2 - the whole row will be highlighted.
List of ColPart ids that will be hovered when hovering this part and Cfg HoverRow = 1.
If both ColPart and RowPart have set HoverRow, the ColPart attribute is preferred.
If and how the whole column will be highligted for hovered cell.
0 - no, only the hovered cell will be highlighted, 1 - the column in the same rows section will be highlighted, 2 - the whole column will be highlighted.
List of RowPart ids that will be hovered when hovering this part and Cfg HoverCol = 1.
If both ColPart and RowPart have set HoverCol, the RowPart attribute is preferred.
If the toolbar cells are hovered.
If the floating images are hovered.
If set to -1, the images are not hovered and HoverImage option is not displayed in Settings menu.
If set, updates hover cursor position during scrolling (may slightly slow down the scrolling). If not set, hides cursor during scrolling.
If highlighting the cell under mouse is restricted, bit array:

1.bit	&1	does not highlight the individual cell.
2.bit	&2	does not highlight the whole row
3.bit	&4	does not highlight the whole column (highlight of whole column is disabled when defined more column sets).

If highlighting the toolbar cell under mouse is restricted.
0 - does not display focus and hover border in edge cells, because it cannot be shown outside the part.
1 - displays focus and hover border also in edge cells, inside them.
If set to 1, shows cursor for the whole rows / column for whole spanned range instead of top left cell.
If set to 2, shows cursor for the whole rows / column also for the whole focused range instead of top left cell.
If set, animates the hover cursor on click to toolbar cell for given count of milliseconds. On tablet it shows the hover cursor for this time too.
Default value is 200 for desktop and 400 for tablet.
Returns object with actual cell under mouse as { Row:row, Col:col, X:x, Y:y }.
Row, Col is the actual cell, can be null if there is no cell under mouse.
X, Y is the mouse position inside the cell.
Returns null if the grid is not under mouse.
Sets HoverImage to the value and updates the view. If value is null, changes it as -1 => -1, 0 => 1, 1 => 0.
If set always, sets the updates the view even if the value is the same as HoverImage.

Highlight cells, rows and columns

List of cells to highlight as {hl1:[rowid1,colid1,color1,rowid2,colid2,color2,...], hl2:[rowid1,colid1,color1,rowid2,colid2,color2,...], hl3:...}.
The hlX can be any string or number as highlight id.
The rowidX can be: a) any row or toolbar id, b) null to highlight whole column(s), c) RowPart id to highlight the whole column in this part.
The colidX can be: a) any column or toolbar cell id, b) null to highlight whole row(s), c) ColPart id to highlight the whole row in this part.
The colorX can be any FastGrid color name or html color. It can contain also rgba() for transparent highlight.
The colorX can be null or empty to highlight range of cells / columns like [rowid1_1,colid1_1,,rowid1_2,colid1_2,color1,...] highlights cell range row1,col1:row2,col2 in color. The range must be in one part.
If the part will be highlighted for whole rows or columns in Highlight.