Documentation – User Guide

Java: Autofill Options

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs creates an AutofillOption popup after a successful autofill drag from the selection corner. The popup contains four actions: Copy Cell, Fill Series, Fill Formatting Only, and Fill Without Formatting. During the first drag release, the sheet runs data.autofill(selector.arange, 'all', ...), stores the original target cells in data.autofillCellInfo.history, and stores the autofill result in data.autofillCellInfo.series.

How to use

Select the source cell or source range in GridJs.
Drag the small selection corner to extend the autofill area. The selector code supports extending the target area to the left, top, right, or bottom of the current selection.
Release the mouse. When the sheet is not in read mode and the target range passes the paste validation check, GridJs runs data.autofill(selector.arange, 'all', ...), redraws the table, and shows the Autofill Options button next to the filled area.

Click the Autofill Options button to open the menu.
Click Copy Cell to rewrite each target cell by repeating cells from the source range. The code calculates the source cell with row and column modulo offsets.
Click Fill Series to keep the autofill result that was generated during the drag operation.
Click Fill Formatting Only to restore each target cell from the saved history and then apply the autofill result style when a style exists in the generated series cell.
Click Fill Without Formatting to keep the generated autofill content and restore the original target style from history. If the original target cell does not have a style, GridJs creates a left-aligned style before writing the cell back.

JavaScript API

import { CellRange } from './core/cell_range';

const xs = x_spreadsheet('#gridjs-demo-uid', options);
const data = xs.sheet.data;
const targetRange = new CellRange(0, 1, 4, 1);

const ok = data.autofill(targetRange, 'all', msg => {
  console.log(msg);
});

if (ok) {
  xs.sheet.table.render();
}

// Internal option values used by the Autofill Options popup:
const autofillTypes = ['copyCell', 'series', 'format', 'withoutFormat'];

Relevant functions

Function	Description	Parameters	Returns
`sheet.data.autofill(cellRange, what, error)`	Validates the target range, runs the autofill copy path, and records `history` and `series` data for later option changes.	`cellRange`: destination `CellRange`; `what`: paste mode such as `'all'`; `error`: callback for validation errors	`boolean`
`autofillOption.change(autofillType)`	Rewrites the autofilled cells according to the selected Autofill Options menu item.	`autofillType`: `'copyCell'`, `'series'`, `'format'`, or `'withoutFormat'`	`void`

In the inspected UI flow, the sheet always starts autofill with what === 'all'. The option popup then changes the written cells by reading data.autofillCellInfo.history, data.autofillCellInfo.series, and data.autofillCellInfo.srcCellRange.

Common Questions

Q: When does the Autofill Options button appear? A: The button is shown only after dragging from the selection corner, completing data.autofill(...) successfully, and rendering the filled range. The code skips this flow when the sheet mode is read.

Q: Which directions can the autofill target area extend? A: The selector code creates an autofill range only when the drag extends outside the current selection to the left, top, right, or bottom.

Q: What does Fill Formatting Only change? A: The handler starts from the saved target cell in history, then replaces only its style with the generated series cell style when that style exists.

Q: What does Fill Without Formatting change? A: The handler keeps the generated autofill cell content, restores the original target style from history, and creates a left-aligned style when the original target cell has no style.

Java: How to add switch rename and delete worksheets

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs manages worksheets through the bottom bar. In edit mode, the bottom bar shows an add button, lets you click a tab to switch sheets, lets you double-click a tab to rename it inline, and provides a tab context menu with Delete Sheet. The worksheet actions are blocked when the workbook is protected, and adding a sheet is also blocked for .csv, .tsv, and workbooks that already have 50 sheet names in the bottom bar.

How to use

Open GridJs in edit mode if you want to add, rename, or delete worksheets. In read mode, the bottom bar still supports clicking tabs to switch sheets, but the add button and edit-only tab events are not attached.

Click the add button in the bottom bar to create a worksheet. If no name is supplied by the caller, GridJs generates the first unused name in the Sheet1, Sheet2, Sheet3 sequence.
Click a worksheet tab to switch to that sheet. GridJs triggers sheet-selected, switches the sheet page, resets the active sheet data, resets pagination, moves the vertical scrollbar to the top, and reapplies the target sheet zoom level.
If the target sheet uses lazy loading and a lazy-loading URL is configured, GridJs loads that sheet first and then switches to it.

Double-click a worksheet tab to rename it. GridJs replaces the tab text with an inline input and commits the rename when the input loses focus.
Use a valid worksheet name when you rename a tab. The code rejects names longer than 31 characters, duplicate worksheet names, and names that contain any of these characters: :, \, /, ?, *, [, ].

Right-click a worksheet tab and choose Delete Sheet to remove it. The delete action runs only when more than one worksheet tab exists.

If you delete the active sheet, GridJs activates the first remaining worksheet tab and resets the sheet view to that sheet.

JavaScript API

const xs = x_spreadsheet('#gridjs-demo-uid', options);

// Add a worksheet and make it active.
const summarySheet = xs.addSheet('Summary', true, '#dbeafe', '#1e3a8a');

// Switch to a worksheet by tab name.
xs.setActiveSheetByName('Summary');

// Rename the worksheet at index 0.
xs.renameSheet(0, 'Input');

// Delete the current sheet.
xs.deleteSheet();

// The implementation also accepts a sheet name.
xs.deleteSheet('Summary');

Relevant functions

Function	Description	Parameters	Returns
`addSheet(name, active = true, tabcolor, fontcolor)`	Creates a new `DataProxy`, adds a new bottom-bar tab, and sends an `op: 'add'` request when the workbook is not in the initial loading path.	`name`: worksheet name or `null`; `active`: whether the new tab is active; `tabcolor`: tab background color; `fontcolor`: tab text color	`DataProxy`
`setActiveSheetByName(sheetname)`	Finds the matching bottom-bar tab and switches to it through the same tab-click flow used by the UI.	`sheetname`: worksheet name	`Spreadsheet`
`renameSheet(index, value)`	Replaces the worksheet name in `datas[index]` and sends an `op: 'rename'` request.	`index`: worksheet index; `value`: new worksheet name	`void`
`deleteSheet(sheetname)`	Removes a worksheet tab, sends an `op: 'del'` request for the removed sheet, and resets the active sheet when needed.	`sheetname`: optional worksheet name; when omitted, the current tab context target is used	`void`

The inspected index.d.ts file declares deleteSheet(): void. The index.js implementation also includes addSheet(...), setActiveSheetByName(...), renameSheet(index, value), and an optional sheetname parameter for deleteSheet(sheetname).

Common Questions

Q: Can I add, rename, or delete worksheets when the workbook is protected? A: No. The add, rename, and delete handlers check wprotected and stop with an error toast when workbook protection is active.

Q: Can I add worksheets to a CSV or TSV file? A: No. The add-button handler stops immediately and shows a warning when uniqueid ends with .csv or .tsv.

Q: What name validation does GridJs apply when I rename a worksheet tab? A: The rename code rejects names longer than 31 characters, duplicate names, and names that contain :, \, /, ?, *, [, or ].

Q: What happens when I delete the active worksheet tab? A: If more than one tab exists, GridJs removes the tab, selects the first remaining tab, and resets the sheet data to that remaining worksheet.

Java: How to batch insert Rows and Columns

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs supports two batch insertion paths. The first path is context-menu batch input for rows/columns (Insert rows above/below, Insert columns left/right). The second path is the bottom Row Appender toolbar for batch appending rows. Both paths use the same row insertion pipeline (sheet.insertRows(...)) and update sheet layout/rendering.

How to use

Method 1: Context menu batch insert (rows and columns).

Select a range, a row header, or a column header.
Right-click and open Insert… in the context menu.
Choose one action:
- Insert rows above
- Insert rows below
- Insert columns to left
- Insert columns to right
Enter the count in the number box and click Insert.
- The input is configured with min=1 and max=300.
- The insert submenu pre-fills the number input with 10 when opened.

Method 2: Row Appender batch insert (rows only). In edit mode, scroll near the bottom until the Row Appender appears, enter row count, then click Add.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Insert 5 rows starting at row index 3.
xs.sheet.insertRows(3, 5);

// Insert 4 columns starting at column index 2.
xs.sheet.insertColumns(2, 4);

// Row Appender equivalent: append rows to the end.
const n = 20;
xs.sheet.insertRows(xs.sheet.data.rows.len, n);

// Optional: listen to insert events.
xs.on('rows-inserted', (start, count) => {
  console.log('rows inserted:', start, count);
});

xs.on('columns-inserted', (start, count) => {
  console.log('columns inserted:', start, count);
});

// Optional: enable/disable bottom Row Appender toolbar.
const xsWithAppender = x_spreadsheet('#gridjs-demo-uid-2', {
  showRowAppenderToolbar: true,
});

Relevant functions

Function	Description	Parameters	Returns
`sheet.insertRows(start, n, raiseServerOpr = true)`	Batch inserts rows at the given start row index.	`start` (row index), `n` (count), `raiseServerOpr` (optional boolean)	`void`
`sheet.insertColumns(start, n, raiseServerOpr = true)`	Batch inserts columns at the given start column index.	`start` (column index), `n` (count), `raiseServerOpr` (optional boolean)	`void`
`data.insert('row' \| 'column', n, raiseServerOpr)`	Internal insert operation used by sheet insert flow; updates data structures and triggers insert events.	`type`, `n`, `raiseServerOpr`	`void`
`showRowAppenderToolbar` (option)	Controls whether the bottom Row Appender toolbar is created (default enabled).	`true` / `false`	N/A
`xs.on(eventName, handler)`	Binds event handler; insert flow triggers `rows-inserted` and `columns-inserted`.	`eventName`, `handler`	`xs`

Context menu mapping for batch insert:

insert-rows-above -> sheet.insertRows(sri, n)
insert-rows-below -> sheet.insertRows(eri + 1, n)
insert-columns-left -> sheet.insertColumns(sci, n)
insert-columns-right -> sheet.insertColumns(eci + 1, n)

Common Questions

Q: Why do I only see row-related or column-related insert options in some cases? A: Context menu mode switches by selection type. In row/column header mode, submenu items are filtered to matching row or column operations.

Q: Why does batch insert do nothing on a protected sheet? A: Insert is blocked when the sheet is locked.

Q: Why is Row Appender not visible? A: It is hidden in read mode, when showRowAppenderToolbar is false, or for chart-type sheets.

Q: Can I use batch insert in read mode? A: No. In read mode, the context menu is reduced to copy-only behavior.

Q: Where is the insertion anchor for above/below/left/right? A: It uses the current selected range: sri/eri for rows and sci/eci for columns, with below/right using +1 as insertion start.

Java: How to Download

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs adds file export entries to the File menu through the Download menu item class. The File menu contains Download Original, Download As XLSX, Download As PDF, and Download As HTML. When the locale is not ru and not zh, the same File menu also adds Save To Google Drive and Save To Dropbox entries.

How to use

Open GridJs and use the File menu.
Select Download Original to route the menu action as download_Original and call the download flow with save type Original.
Select Download As XLSX, Download As PDF, or Download As HTML to route the menu action as download_XLSX, download_PDF, or download_HTML. GridJs changes the exported file name suffix to .xlsx, .pdf, or .html before starting the download flow.

If the current locale is neither ru nor zh, use Save To Google Drive or Save To Dropbox. Both entries export the original file type and pass the device value as GoogleDrive or Dropbox.

If beforeSaveFunc is configured, GridJs calls it before starting the export. If it returns a false value, the export stops.
If fileDownloadCallFunc is configured, GridJs calls that function with the target file name, export type, and device value. If no custom callback is configured, GridJs sends a POST request to fileDownloadUrl.
When the POST response is JSON or text, GridJs treats the response as a file URL and downloads that URL as a blob. For other response content types, GridJs downloads the response blob directly.

The File menu has a generic download handler that opens ModalDownload, but the new Download() entry without a suffix is commented out in the inspected File menu code. The active File menu entries use the direct typed handlers listed above.

JavaScript API

Configure the built-in download request URL with setFileDownloadInfo(url).

const xs = x_spreadsheet('#gridjs-demo-uid', options);

xs.setFileDownloadInfo('/GridJs2/Download');

Use setFileDownloadCallFunction(fileDownloadCallFunc) when you want to handle the export action yourself instead of using the built-in POST request.

const xs = x_spreadsheet('#gridjs-demo-uid', options);

xs.setFileDownloadCallFunction((toFileName, type, device) => {
  // toFileName is the final file name selected by GridJs.
  // type is one of: 'Original', 'XLSX', 'PDF', or 'HTML'.
  // device is 'Device', 'GoogleDrive', or 'Dropbox'.
});

Use setBeforeSaveFunction(beforeSaveFunc) to run a guard before export starts.

xs.setBeforeSaveFunction(() => {
  return true;
});

Relevant functions

Function / Location	Description	Parameters	Returns
`Download(suffix)` (`component/toolbar/download.js`)	Builds a download menu item tag as `download_<suffix>` and uses the download icon, or the save-to-cloud icon for `GOOGLE` and `DROPBOX`.	`suffix`: export suffix such as `Original`, `XLSX`, `PDF`, `HTML`, `GOOGLE`, or `DROPBOX`	`Download` instance
`Menubar(data, widthFn, isHide, showPartToolbar, local)` (`component/menubar.js`)	Adds `Download("Original")`, `Download("XLSX")`, `Download("PDF")`, and `Download("HTML")` to the File menu, and conditionally adds cloud entries when `local !== 'ru' && local !== 'zh'`.	`data`, `widthFn`, `isHide`, `showPartToolbar`, `local`	`Menubar` instance
`toolbarChange(type, value)` (`component/sheet.js`)	Dispatches `download_Original`, `download_XLSX`, `download_PDF`, `download_HTML`, `download_GOOGLE`, and `download_DROPBOX` to `fileDownloadByType`.	`type`: menu tag; `value`: optional value	`void`
`fileDownloadByType(type, device = 'Device')` (`component/sheet.js`)	Runs `beforeSaveFunc`, builds the target file name, and either calls `downloadFile` or `fileDownloadCallFunc`.	`type`: save type; `device`: destination string	`void`
`downloadFile(toFileName, saveType)` (`component/sheet.js`)	Posts sheet state and requested output type to `fileDownloadUrl`, then downloads the returned file URL or response blob.	`toFileName`: target file name; `saveType`: output type	`Promise<void>`
`fileLinkToStreamDownload(url, fileName, authToken)` (`component/sheet.js`)	Downloads a returned file URL with `XMLHttpRequest` and forwards the blob to `downloadExportFile`.	`url`, `fileName`, `authToken`	`void`
`downloadExportFile(blob, tagFileName)` (`component/sheet.js`)	Creates an anchor element, sets `href` and `download`, clicks it, and revokes the object URL for non-string blobs.	`blob`: Blob or string URL; `tagFileName`: download name	`void`
`setFileDownloadInfo(url)` (`index.js`)	Stores the built-in download request URL on `this.sheet.fileDownloadUrl`.	`url`: download endpoint URL	`void`
`setFileDownloadCallFunction(fileDownloadCallFunc)` (`index.js`)	Stores a custom export callback on `this.sheet.fileDownloadCallFunc`.	`fileDownloadCallFunc`: function called with `(toFileName, type, device)`	`void`
`setBeforeSaveFunction(beforeSaveFunc)` (`index.js`)	Stores a guard callback on `this.sheet.beforeSaveFunc`.	`beforeSaveFunc`: function returning a truthy value to continue	`void`

The inspected index.d.ts file does not declare setFileDownloadInfo, setFileDownloadCallFunction, or setBeforeSaveFunction, but the index.js implementation exposes these methods directly.

Common Questions

Q: Which export entries are active in the File menu? A: The inspected File menu code adds Download Original, Download As XLSX, Download As PDF, and Download As HTML.

Q: When are Google Drive and Dropbox entries shown? A: They are added when the local value is not ru and not zh.

Q: How does GridJs choose the exported file extension? A: For non-Original export types, GridJs replaces the current file name suffix with the lowercase export type, such as .xlsx, .pdf, or .html.

Q: Can application code intercept the File menu export? A: Yes. If fileDownloadCallFunc is configured, GridJs calls it instead of the built-in downloadFile request.

Java: How to hide and unhide rows and columns in GridJS

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJS exposes Hide and Unhide in the context menu, using the row/column context mode rather than the normal cell-range menu. When you select row headers or column headers, the context menu switches to whole-row or whole-column mode, and the Hide / Unhide commands operate on that selected range. GridJS also wires an unhide callback to the row and column resizers, so the header area can show a dedicated unhide hover target near hidden lines. In read mode, the context menu is reduced to Copy, so the UI hide/unhide commands are not available there.

How to use

Select entire rows or entire columns. Use the row headers on the left or the column headers at the top so GridJS enters row/column context mode.
Hide the selected rows or columns. Right-click the selected headers and choose Hide. In the current implementation, Hide works only when the selection covers whole rows or whole columns.
Unhide from the context menu. Select the row-header range or column-header range where you want hidden items to be restored, right-click, and choose Unhide.
Review the updated sheet. After hide or unhide runs, GridJS resets the sheet view. Row and column image positions are also updated together with the hide state.

JavaScript API

Based on the current source code, the sheet instance exposes direct methods for hiding and unhiding row and column ranges. These methods call the shared hide/unhide workflow internally, so you do not need an extra table.render() call in this flow.

const xs = x_spreadsheet('#gridjs-demo-uid', option);

// Hide rows 3 through 5.
xs.sheet.hideRows(3, 5);

// Hide columns 2 through 4.
xs.sheet.hideColumns(2, 4);

// Unhide the same rows.
xs.sheet.unhideRows(3, 5);

// Unhide the same columns.
xs.sheet.unhideColumns(2, 4);

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.hideRows(sri, eri)`	Hides the row range by routing to the shared hide/unhide handler with `type = 'row'` and `isunhiden = false`.	`sri:number`, `eri:number`	`void`
`xs.sheet.unhideRows(sri, eri)`	Unhides the row range through the same shared handler.	`sri:number`, `eri:number`	`void`
`xs.sheet.hideColumns(sci, eci)`	Hides the column range by routing to the shared hide/unhide handler with `type = 'col'` and `isunhiden = false`.	`sci:number`, `eci:number`	`void`
`xs.sheet.unhideColumns(sci, eci)`	Unhides the column range through the same shared handler.	`sci:number`, `eci:number`	`void`

Common Questions

Q: Can I hide a normal cell range from the context menu? A: No. The current context-menu hide flow checks for whole-row or whole-column selection.

Q: Where do the Hide and Unhide menu items come from? A: They are defined in the GridJS context menu as contextmenu.hide and contextmenu.unhide.

Q: Why can I not see Hide or Unhide in read mode? A: In read mode, the context menu is reduced to a single Copy item.

Q: Is there a JavaScript API for this feature? A: Yes. The current sheet instance exposes hideRows, unhideRows, hideColumns, and unhideColumns.

Java: How to input Formula

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs supports formula input in both the cell editor and the formula bar. When input starts with =, formula suggestion and formula tip UI are used during editing. You can also insert a function template from the Functions toolbar dropdown, which writes a formula skeleton into the selected cell.

How to use

Select a target cell.
Type a formula that starts with = in the cell editor or in the formula bar (for example, =SUM(A1:A3)).
While typing after =, formula suggestions are shown; choose a function to insert it quickly.
To insert a function template directly, click Functions on the toolbar and pick a function. The selected cell receives =FUNCTION().
Press Enter in the formula bar to commit and move selection down. Use Shift+Enter to move up, Tab to move right, and Shift+Tab to move left.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Set a formula text directly (ri/ci are zero-based indexes).
xs.cellText(0, 0, '=SUM(A1:A3)');
xs.reRender();

// Insert a formula template into the current selected cell.
xs.sheet.data.setSelectedCellAttr('formula', 'SUM');
xs.reRender();

Relevant functions

Function	Description	Parameters	Returns
`xs.cellText(ri, ci, text, sheetIndex)`	Sets cell text on a sheet. A formula can be passed as text beginning with `=`.	`ri` (number), `ci` (number), `text` (string), `sheetIndex` (number, optional)	`xs`
`xs.reRender()`	Re-renders the sheet after data changes so formula input results are visible.	None	`xs`
`xs.sheet.data.setSelectedCellAttr('formula', value)`	Writes a formula template to the current selection. For a single cell it becomes `=value()`.	`value` (function key, such as `SUM`)	`void`

xs.cellText(...) writes formula text through the same cell-text pipeline used by editing. setSelectedCellAttr('formula', ...) is the function-template path used by the toolbar Functions dropdown.

Common Questions

Q: Why can I not input formulas in some sheets? A: Input is blocked in read mode and also blocked when the sheet is locked.

Q: When does formula suggestion appear? A: Suggestion appears when input starts with = and formula text is being edited.

Q: What happens when I pick a function from the Functions dropdown? A: For a single selected cell, GridJs inserts a formula skeleton like =SUM() and places the editor cursor inside ().

Q: Why does the formula bar show formula text instead of displayed value? A: If the selected cell has a formula field (f), the formula bar shows f first.

Java: How to paste values only and paste format only

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs adds a Paste Special submenu to the context menu. That submenu contains Paste values only and Paste format only, and the sheet component routes them to paste('text') and paste('format'). Both actions stop immediately when the sheet is in read mode or the current sheet is locked.

How to use

Select the source cell or range in GridJs.
Copy or cut the selection inside GridJs.
Select the target cell or range.
Right-click the selection and open Paste Special.
Click Paste values only when you want the handler to use the text paste branch.
Click Paste format only when you want the handler to use the format paste branch.

If the current sheet is read-only or locked, GridJs does not run the paste action.

JavaScript API

const xs = x_spreadsheet('#gridjs-demo-uid', options);

// Paste only the internal GridJs clipboard text branch.
const valuesPasted = await xs.sheet.data.pasteFromInternal('text', msg => {
  console.log(msg);
});

// Paste only the internal GridJs clipboard format branch.
const formatsPasted = await xs.sheet.data.pasteFromInternal('format', msg => {
  console.log(msg);
});

// Paste plain text into the current selection.
xs.sheet.data.pasteFromText('A\tB\r\n1\t2', msg => {
  console.log(msg);
});

// Paste styled HTML cells into the current selection.
xs.sheet.data.pasteFromHTML(htmlString, msg => {
  console.log(msg);
});

Relevant functions

Function	Description	Parameters	Returns
`sheet.data.pasteFromInternal(what, error)`	Pastes from the internal GridJs copy/cut clipboard.	`what`: `'all'`, `'text'`, or `'format'`; `error`: callback for paste errors	`Promise<boolean>`
`sheet.data.pasteFromText(txt, error)`	Splits plain text by `\r\n` and `\t`, expands the target range, and writes text cells.	`txt`: plain text; `error`: callback for paste errors	`void`
`sheet.data.pasteFromHTML(html, error)`	Parses styled cells from HTML and applies them to the current selection.	`html`: HTML string; `error`: callback for paste errors	`void`

For internal copy and paste, the row model uses what === 'text' to write destination text only, and what === 'format' to write destination style and copied merge metadata.

Common Questions

Q: What does Paste values only do in this code? A: The context menu action calls paste('text'), and the row model’s text branch writes only the destination cell text.

Q: What does Paste format only do in this code? A: The context menu action calls paste('format'), and the row model’s format branch writes the destination cell style. When the copied cell includes merge metadata, that merge metadata is copied in the same branch.

Q: Does the Paste Special menu have a separate external clipboard fallback for formats? A: No separate external format-only fallback was found in the menu handler. When internal copy/cut is unavailable, the code reads the browser clipboard and handles text/plain through pasteFromText, or image/png through image upload.

Q: What happens when the target intersects merged cells? A: Paste is allowed only when the target is exactly one complete merged area and the source is a single cell, or when the merged target size is an integer multiple of the source range. For a multi-cell source pasted into one complete merged area, the code unmerges the target area before applying the paste.

Q: Do Ctrl+Shift+V and Ctrl+Alt+V have dedicated keyboard handling? A: The submenu items display those labels, but in the inspected sheet.js code only Ctrl+V has a dedicated keyboard branch. No separate key handling branch was found for the two Paste Special combinations.

Java: How to Protect a Sheet and Workbook

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs provides a Protect menu with separate actions for Protect Sheet and Protect Workbook. Protect Sheet opens a password dialog that can also collect worksheet permission options such as selecting locked cells, sorting, or using AutoFilter. Protect Workbook applies workbook-structure protection, and the code blocks sheet add, delete, and rename actions while workbook protection is active.

How to use

Open the Protect menu in the toolbar, then choose Protect Sheet or Protect Workbook.
To protect a sheet, enter a password in the Protect Sheet dialog. Leave Protect worksheet and contents of locked cells checked if you want locked cells to stay protected, then choose any allowed actions such as Select locked cells, Select unlocked cells, Format cells, Insert rows, Sort, or Use AutoFilter.
Reenter the same password in the confirmation dialog. If the two passwords do not match, GridJs shows an error and asks again.
To protect the workbook structure, choose Protect Workbook, enter a password, and confirm it. This dialog only asks for the password and confirmation.
To remove protection, open the same Protect menu item again. GridJs asks for the password to unprotect the sheet or workbook, and it shows an Incorrect password error if the password is wrong.
After protection is applied, workbook protection blocks sheet structure changes such as adding, deleting, or renaming worksheets, and sheet protection blocks changes to locked cells or other protected areas.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Protect the current sheet and allow a few actions.
xs.sheet.data.protectSheetOpr('secret', {
  canselectlocked: true,
  canselectunlocked: true,
  allowSort: true,
  allowFilter: true,
  allowFormatCell: false,
  allowInsertRow: false,
});

// Remove sheet protection.
xs.sheet.data.unprotectSheetOpr('secret');

// Protect workbook structure.
xs.sheet.data.protectWorkbookOpr('secret');

// Remove workbook structure protection.
xs.sheet.data.unprotectWorkbookOpr('secret');

Relevant functions

Function	Description	Parameters	Returns
`sheet.data.protectSheetOpr(password, protection)`	Sends a `protectsheet` operation for the current sheet and can include worksheet permission flags.	`password` (string), `protection` (object, optional)	`void`
`sheet.data.unprotectSheetOpr(password)`	Sends an `unprotectsheet` operation for the current sheet.	`password` (string, optional)	`void`
`sheet.data.protectWorkbookOpr(password)`	Sends a `protectworkbook` operation for workbook structure protection.	`password` (string)	`void`
`sheet.data.unprotectWorkbookOpr(password)`	Sends an `unprotectworkbook` operation for workbook structure protection.	`password` (string, optional)	`void`

The protection object used by protectSheetOpr can include keys exposed in the dialog, including canselectlocked, canselectunlocked, allowFormatCell, allowFormatCol, allowFormatRow, allowInsertCol, allowInsertRow, allowInsertLink, allowDeleteCol, allowDeleteRow, allowEditObject, allowEditScenario, allowSort, allowFilter, and allowUsePivot.

Common Questions

Q: What is the difference between Protect Sheet and Protect Workbook? A: Protect Sheet applies password-based protection to the current worksheet and can include per-action permissions. Protect Workbook applies workbook structure protection and blocks sheet add, delete, and rename actions.

Q: What happens if I enter the wrong password when unprotecting? A: GridJs shows an Incorrect password error and prompts again for the password.

Q: Which actions can stay available on a protected sheet? A: The sheet protection dialog exposes options including selecting locked or unlocked cells, formatting cells, columns, or rows, inserting rows, columns, or hyperlinks, deleting rows or columns, editing objects or scenarios, sorting, using AutoFilter, and using PivotTable or PivotChart.

Q: What happens to locked cells after sheet protection is turned on? A: Changes to locked cells are blocked, and the code checks the sheet protection state together with each cell’s locked or unlocked style.

Java: How to Send By Email

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs adds Send By Email to the File menu through the Email menu item. Selecting this item opens an email modal with a Receiver input and a File Type selector. The modal passes the receiver value and selected file type to setEmailSendCallFunction when the user clicks OK and a callback has been configured.

How to use

Open GridJs and use the File menu.
Select Send By Email. GridJs routes the menu item tag email through the menu change handler and opens the email modal.

Enter a receiver address in the Receiver field. The field placeholder is example@mail.com.
Choose one file type from the File Type selector. The code defines three values: xlsx, pdf, and html.
Click OK. If the receiver input has been marked with a red border by the input handler, the modal shakes the receiver field and does not call the send callback.
When the receiver input is not marked red and emailSendCallFunc has been configured, GridJs calls the send callback with an object containing receiver and type, shows a Sending Email mask, and then shows a success toast with the returned message. If the callback throws, GridJs shows an error toast and closes the mask.
Click Cancel to close the modal without calling the send callback.

JavaScript API

Use setEmailSendCallFunction(emailSendCallFunc) on the top-level spreadsheet instance to provide the email send callback.

const xs = x_spreadsheet('#gridjs-demo-uid', options);

xs.setEmailSendCallFunction(async (mailObj) => {
  // mailObj.receiver comes from the Receiver input.
  // mailObj.type is one of: 'xlsx', 'pdf', or 'html'.
  return 'Email sent';
});

Relevant functions

Function / Location	Description	Parameters	Returns
`new Email()` (`component/toolbar/email.js`)	Creates an icon menu item with the tag `email`.	None	`Email` instance
`Menubar(data, widthFn, isHide, showPartToolbar, local)` (`component/menubar.js`)	Adds `new Email()` to the File menu after the download entries.	`data`, `widthFn`, `isHide`, `showPartToolbar`, `local`	`Menubar` instance
`toolbarChange(type, value)` (`component/sheet.js`)	Opens `modalEmail` when `type === 'email'`.	`type`: menu or toolbar tag; `value`: optional item value	`void`
`ModalEmail` (`component/modal_email.js`)	Builds the Receiver input, File Type selector, OK button, and Cancel button.	None	`ModalEmail` instance
`setEmailSendCallFunction(emailSendCallFunc)` (`index.js`)	Stores the callback on `this.sheet.emailSendCallFunc`.	`emailSendCallFunc`: function called with `{ receiver, type }`	`void`
`modalEmail.change(action, mailObj)` (`component/sheet.js`)	Calls `emailSendCallFunc(mailObj)` when `action === 'ok'`, shows a sending mask, and reports success or error with a toast.	`action`: modal action; `mailObj`: `{ receiver, type }`	`Promise<void>`

The inspected index.d.ts file does not declare setEmailSendCallFunction, but the index.js implementation exposes the method directly.

Common Questions

Q: Where does the Send By Email command appear? A: It is added to the File menu after the download-related menu entries.

Q: Which file types are available in the email modal? A: The modal defines xlsx, pdf, and html as selectable file type values.

Q: What object is passed to the send callback? A: GridJs passes an object with receiver from the Receiver input and type from the File Type selector.

Q: Is Send By Email blocked when the sheet is protected? A: No. The email operation is included in protectSheetAllowOperations.

Java: How to set cell link in GridJS

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJS provides a Link entry in the Insert menu and in the cell context menu. The link dialog supports three target types: Web Page, This Document, and E-mail Address. When adding a cell link, GridJS stores link objects in data.hyperlinks, applies hyperlink style (underline: true, color: #0000ff), and updates clickable link positions on the sheet. For web links, the dialog auto-adds http:// when protocol is missing, and accepts only http or https URLs.

How to use

Select the target cell or range.
Open the link dialog. Use either:

Insert menu: Link
Right-click menu: Link

Choose Link To type and fill fields.

Web Page: set Address.
This Document: set Document Place and Cell Reference (for example Sheet2!A1).
E-mail Address: set E-mail Address and Subject.

Click OK.

For a new range, GridJS adds a link object with area, type, address (and keeps cell text in text), then refreshes hyperlink style and hit-testing.

Open, edit, or remove the link.

If the selected cell has a link, the context menu switches from Link to Edit Link, Open Link, and Remove Link.
Clicking a linked cell opens the link (non-right-click path).
Remove Link removes the link from data.hyperlinks and clears hyperlink style for that range.

JavaScript API

You can set links through sheet data and reload it, because hyperlinks is part of getData() / loadData() payload.

const xs = x_spreadsheet('#gridjs-demo', options);

const data = xs.getData();
const sheet = data[0];

sheet.hyperlinks = sheet.hyperlinks || [];
sheet.hyperlinks.push({
  area: 'B2:B2',
  type: 0, // 0=web, 2=email, 3=this document
  address: 'https://example.com',
  text: 'Example',
});

xs.loadData(data);

For runtime updates on the current sheet without rebuilding all data, you can mutate xs.sheet.data.hyperlinks and refresh link style/positions:

const link = {
  area: 'C3:C3',
  type: 3,
  address: 'Sheet2!A1',
  text: 'Jump to Sheet2',
};

xs.sheet.data.hyperlinks.push(link);
xs.sheet.hyperlink.setHyperlinkStyleByArea(link.area, xs.sheet, true);
xs.sheet.hyperlink.loadLinkPosition(xs.sheet);
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.getData()`	Gets workbook data including each sheet’s `hyperlinks`.	none	`Array<sheetData>`
`xs.loadData(data)`	Loads workbook data; `hyperlinks` in payload is applied through data proxy.	`data:Array\|Object`	`xs`
`xs.sheet.hyperlink.getSelectArea(range)`	Converts current range to `A1:B2` area string.	`range:{sri,sci,eri,eci}`	`string`
`xs.sheet.hyperlink.setHyperlinkStyleByArea(area, sheet, type)`	Applies or clears hyperlink style for all cells in area.	`area:string`, `sheet:Sheet`, `type:boolean`	`void`
`xs.sheet.hyperlink.loadLinkPosition(sheet)`	Rebuilds clickable hyperlink hit regions after data changes.	`sheet:Sheet`	`void`
`xs.sheet.hyperlink.access(hyperlink)`	Opens a hyperlink by type (`web/email` opens URL, `this document` jumps to sheet/cell).	`hyperlink:{type,address,...}`	`null\|undefined`

Common Questions

Q: Why is my web link rejected? A: The dialog only accepts http:// or https:// URLs. If protocol is missing, GridJS first normalizes it to http://....

Q: Why do I see Edit Link / Open Link / Remove Link instead of Link? A: Context menu visibility is switched by whether the selected cell already has a hyperlink.

Q: Why can’t I add links on a locked sheet from context menu? A: In locked mode, context-menu actions are hidden except copy-related actions and Open Link.

Q: How does This Document link navigate? A: GridJS stores address as SheetName!CellRef; on open, it activates target sheet and then activates the target cell.

Java: How to set Data Validations settings in GridJS

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJS provides Data Validation entry points from both the top menu and the context menu, labeled Data Validation and Data Validations. The Data Validation dialog contains three tabs: Setting, Input Message, and Error Alert. In the Setting tab, you can configure AnyValue / WholeNumber / Decimal / List / Date / Time / TextLength / Custom, and the Value1/Value2 (or Source) inputs are shown dynamically based on the selected Allow and Data options. When Allow is set to Date or Time, the selected cells are also formatted as date/time after submission.

How to use

Select the target cell or range where you want to apply validation.
Open the Data Validation dialog. Use either the context menu item Data Validations or the toolbar item Data Validation.
Configure rules in the Setting tab. Set Allow, Data, and Value1/Value2; if Allow = List, enter the source in Source, and optionally enable Allow multiple selection.
Configure the Input Message tab. Enable Show input message when cell is selected, then set the title and message.
Configure the Error Alert tab. Enable Show error alert after invalid data is entered, then set Style (Stop/Warning/Information), title, and message.
Click Submit to save, then test input values in the target range.

JavaScript API

Based on the current source code, you can apply validation rules programmatically through xs.sheet.modalDataValidation.change(index, validation).

xs = x_spreadsheet('#gridjs-demo-uid', option);

(async () => {
  // Select B2:B10 (0-based indexes)
  xs.sheet.selector.set(1, 1);
  xs.sheet.selector.setEnd(9, 1);

  await xs.sheet.modalDataValidation.change(-1, {
    allowtype: 'List',
    operatorfull: 'Between',
    ignoreblank: true,
    value1: '=D2:D6',
    value2: '',
    f1: '=D2:D6',
    f2: '',
    showinput: true,
    inputtitle: 'Allowed values',
    inputmessage: 'Please pick from the list, comma-separated for multiple values',
    showerror: true,
    alertstyle: 'warning',
    errortitle: 'Invalid input',
    errormessage: 'The value is not in the allowed list',
    ismultiple: true,
  });

  xs.sheet.table.render();
})();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.selector.set(ri, ci, indexesUpdated)`	Sets the selection start cell.	`ri:number`, `ci:number`, `indexesUpdated?:boolean`	`void`
`xs.sheet.selector.setEnd(ri, ci, moving)`	Sets the selection end cell to form the target range.	`ri:number`, `ci:number`, `moving?:boolean`	`void`
`xs.sheet.modalDataValidation.change(index, validation)`	Applies or updates Data Validation settings for the current selection.	`index:number` (use `-1` for new settings), `validation:object`	`Promise<void>`
`xs.sheet.data.checkValidation(ri, ci)`	Triggers server-side validation (used when formulas/custom conditions are involved).	`ri:number`, `ci:number`	`Promise<boolean>`
`xs.sheet.table.render()`	Re-renders the sheet view.	none	`void`

Common Questions

Q: Why is no input message shown when I select a validated cell? A: showinput must be enabled, and both inputtitle and inputmessage must be non-empty.

Q: How does multiple selection work for List validation? A: Enable Allow multiple selection; values are comma-separated and each item is validated against the list.

Q: What is the behavior difference among error alert styles? A: stop shows Retry; warning shows Yes/No; information shows OK.

Q: Why does the cell display format change after choosing Date or Time? A: Current implementation sets selected cell format to date or time when the validation is submitted.

Java: How to use Border settings

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs includes a Format Cells dialog with a Border tab. In that tab, you can choose one of the built-in line styles, pick a border color, use preset actions such as none, outline, and inside, or click individual border buttons around the preview area. The dialog keeps these changes in local border actions and applies them to the current selection only after you click Ok.

How to use

Select the cell or range that you want to format.
Open the context menu and click Format Cells.
In the dialog, open the Border tab.
In the style section, choose one of the available line styles: thin, medium, thick, dashed, or dotted.
In the color section, pick the border color that you want to apply.
Use the preset buttons to remove all borders (none), apply an outer outline (outline), or apply inside borders (inside). When the current selection is a single cell, the inside preset is disabled.
If you need more control, use the preview buttons to toggle top, bottom, left, right, all, horizontal, vertical, or inside for the current selection.
Review the preview area. The preview uses up to a 2 x 2 layout from the current selection and highlights the border buttons that are currently active.
Click Ok. GridJs sends each recorded border action to the selected range and redraws the sheet with the new borders.

JavaScript API

const xs = x_spreadsheet('#gridjs-demo-uid', options);

// Apply an outside border to the current selection.
xs.sheet.data.setSelectedCellAttr('border', {
  mode: 'outside',
  style: 'thin',
  color: '#000000',
});

// Add inside borders to the current selection.
xs.sheet.data.setSelectedCellAttr('border', {
  mode: 'inside',
  style: 'dashed',
  color: '#ff0000',
});

// Read the resulting border object from a cell.
const border = xs.cellStyle(0, 0, 0).border;

Relevant functions

Function	Description	Parameters	Returns
`sheet.data.setSelectedCellAttr(property, value)`	Applies a border action to the current selection immediately.	`property`: `'border'`; `value`: `{ mode, style, color }`	`void`
`sheet.data.setRangeAttr(range, property, value)`	Applies a border action to a specific range. The Format Cells dialog uses this path when you click Ok.	`range`: selected range; `property`: `'border'`; `value`: `{ mode, style, color }`	`void`
`cellStyle(rowIndex, colIndex, sheetIndex)`	Returns the cell style object for a cell.	`rowIndex`, `colIndex`, `sheetIndex`	`CellStyle`

For border actions, the code handles these modes: none, all, inside, outside, horizontal, vertical, top, bottom, left, and right. The Border tab exposes these line styles in the UI: thin, medium, thick, dashed, and dotted.

The resulting border data is stored in CellStyle.border, where each side uses the shape top?: [style, color], right?: [style, color], bottom?: [style, color], and left?: [style, color].

Common Questions

Q: When are border changes actually written to the sheet from the Border tab? A: The Border tab records actions while you click in the dialog. The code applies those actions to the selected range only when you click Ok.

Q: Can I use the inside preset on a single cell? A: No. The dialog disables the inside preset for a 1 x 1 selection, and the border handler also skips inside, horizontal, and vertical when the selection is not multiple.

Q: How does GridJs store a border after it is applied? A: The cell style keeps a border object. Each visible side is stored as a [style, color] pair under top, right, bottom, or left.

Q: What happens when I reopen Border settings on a range that already has borders? A: The dialog scans the selected range and only preloads borders that are consistent for the whole matching edge or inner line. If the selected cells do not share the same border on that side, that side is not preselected in the preview.

Java: How to use Freeze

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Freeze is a toolbar toggle (Freeze cell) that locks the top rows and left columns relative to the current selected cell. When enabled, GridJs stores freeze coordinates in sheet data and resets scroll to the freeze origin. When disabled, freeze is cleared by setting coordinates to (0, 0).

How to use

Select a cell where both row index and column index are greater than zero (for example, C3).
Click Freeze cell on the toolbar.
Scroll the sheet and verify that rows above and columns to the left of the freeze position stay fixed.
Click Freeze cell again to unfreeze.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Freeze by row/column index (zero-based): freeze top 2 rows and left 2 columns.
xs.sheet.freeze(2, 2);

// Unfreeze.
xs.sheet.freeze(0, 0);

// Persist freeze through sheet data (A1-style reference).
const data = xs.getData();
data[0].freeze = 'C3';
xs.loadData(data);

Relevant functions

Function	Description	Parameters	Returns
`sheet.freeze(ri, ci, raiseServerOpr = true)`	Applies or clears freeze on the current sheet. Internally updates freeze data and triggers sheet reset/render.	`ri` (row index), `ci` (column index), `raiseServerOpr` (optional boolean)	`sheet`
`data.setFreeze(ri, ci)`	Sets freeze coordinates in data and resets scroll state.	`ri` (row index), `ci` (column index)	`void`
`data.freezeIsActive()`	Checks whether freeze is active.	None	`boolean`
`xs.loadData(data)`	Loads sheet data; `freeze` supports A1-style value (for example `C3`).	`data` (sheet array/object)	`xs`

sheet.freeze(...) is the same freeze path used by the toolbar toggle. A freeze state is active only when ri > 0 or ci > 0.

Common Questions

Q: Why did clicking Freeze not create a frozen pane when A1 is selected? A: Freeze is active only when row index or column index is greater than zero. Selecting A1 maps to (0, 0).

Q: How do I unfreeze? A: Toggle the Freeze button again, or call sheet.freeze(0, 0).

Q: Does toolbar state follow the current freeze status? A: Yes. Toolbar reset reads data.freezeIsActive() and updates the Freeze button active state.

Q: Can I freeze on a protected sheet? A: No. Freeze is blocked by the protected-sheet operation guard in the toolbar change flow.

Java: How to use Insert Controls

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Insert Controls provides a toolbar dropdown for adding form-like controls to the grid. The available options are Text Box, Combo Box, Check Box, Spin Button, and Option Button. Each option opens a dialog with the required fields for that control, and the control is inserted at the current selection after you confirm.

How to use

Select a target cell, then click Insert Controls on the toolbar.
Choose a control type from the dropdown.
Text Box: adds a Text Box control at the selected cell.
Label text: required input for creating the control (placeholder: “Please enter text”).
Combo Box: adds a Combo Box control at the selected cell with values from a range.
Cell Reference: linked cell updated when the selection changes.
Cell Range: source range for dropdown options (for example, B1:B10).
Check Box: adds a Check Box control at the selected cell.
Cell Reference: linked cell updated with TRUE or FALSE when toggled.
Label text: shown next to the checkbox.
Option Button: adds an Option Button (Radio Button) control at the selected cell.
Cell Reference: linked cell updated when the option is selected.
Label text: shown next to the option button.
Spin Button: adds a Spin Button control at the selected cell.
Cell Reference: linked cell updated with the current value.
Minimum value: lower bound for the value.
Maximum value: upper bound for the value.
Current value: initial value.
Incremental change: step size for each click.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Open the Insert Controls dialog for a specific type.
xs.sheet.modelControl.show('TextBox');
xs.sheet.modelControl.show('ComboBox');
xs.sheet.modelControl.show('CheckBox');
xs.sheet.modelControl.show('SpinButton');
xs.sheet.modelControl.show('RadioButton');

Relevant functions

Function	Description	Parameters	Returns
sheet.modelControl.show(type)	Show the Insert Controls dialog for the given control type.	type (‘TextBox’, ‘ComboBox’, ‘CheckBox’, ‘SpinButton’, ‘RadioButton’)	void
sheet.modelControl.hide()	Close the Insert Controls dialog.	None	void

sheet.modelControl.show(type) displays the control dialog configured for the requested type. sheet.modelControl.hide() closes the dialog without inserting a control.

Common Questions

Q: What control types are available in Insert Controls? A: Text Box, Combo Box, Check Box, Spin Button, and Option Button.

Q: What inputs are required for Combo Box? A: Cell Reference and Cell Range. The range uses a spreadsheet reference like B1:B10.

Q: Why does the dialog reject my values for Spin Button? A: The dialog validates Minimum value, Maximum value, Current value, and Incremental change. If the values are out of range (for example, Current value outside min/max), the dialog blocks submission.

Java: How to use Number Formats and Format Cells tabs in GridJS

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJS provides two related formatting entry points for cells. The format dropdown offers built-in formats such as Normal, Plain Text, Number, Percent, RMB, USD, EUR, Date, Time, Date time, and Duration. For more detailed formatting, GridJS opens the Format Cells dialog from the More Number Formats dropdown entry, the context-menu item Format Cells, or the Ctrl+1 shortcut. In the current source code, this dialog contains five tabs: Number, Alignment, Font, Border, and Fill. The dialog does not submit everything through one identical path: number, alignment, font, and fill settings are collected into a style object, while merge and border actions are sent separately.

How to use

Select the target cell or range. Both the quick format dropdown and the Format Cells dialog apply to the current selection.
Open Format Cells. Use one of these entry points: the More Number Formats item in the format dropdown, the context-menu item Format Cells, or Ctrl+1.
Use the Number tab. The Category dropdown chooses the active number-format group. The read-only Sample box previews the current format result for the selected cell value. Decimal places is a numeric input limited to 0 through 99, and changing it refreshes the sample. Use 1000 Separator is shown for the Number category and toggles the generated custom format between grouped and ungrouped thousands. Symbol is shown for Currency and Accounting and changes the currency symbol used by the generated format. Type changes by category: for Number and Currency, it selects the negative-number pattern; for Date and Time, it selects one of the predefined date/time display patterns; for Custom, it becomes editable so you can type or select a custom format string. General and Text do not show format pickers; they display explanatory text instead.
Use the Alignment tab. Horizontal selects General, Left, Center, or Right. Vertical selects Top, Center, or Bottom. Indent is a numeric input limited to 0 through 250; when it becomes greater than 0, the dialog forces horizontal alignment to Left unless the current alignment is already Left or Right. Wrap text toggles the stored textwrap state. Merge cells toggles the merge state for the selected range and is submitted separately from the style object. The orientation area has three interactive parts: the vertical-text button with stacked Text letters switches the dialog into vertical-text mode; the angle diagram lets you drag the pointer or click near snap points; the degrees input accepts values from -90 through 90.
Use the Font tab. The Font list selects the font family from baseFonts. The Font style list switches between Regular, Italic, Bold, and Bold Italic. The Size list changes the font size. The color button opens the font color palette; selecting a color updates the stored font color and refreshes the preview. The Underline dropdown supports None, Single, Double, Single Accounting, and Double Accounting. The Strikethrough, Superscript, and Subscript checkboxes toggle those effects; Superscript and Subscript are mutually exclusive in the current implementation. The preview box redraws AaBbYyZz each time these controls change.
Use the Border tab. The line-style list chooses the border stroke style such as thin, medium, thick, dashed, or dotted. The border color palette changes the color used for the next border action. The preset buttons work as follows: none removes all borders, outline applies borders to the outside of the selection, inside applies borders to the inside edges of a multi-cell selection. The preview action buttons around the sample grid apply specific modes: top, left, right, and bottom apply one side; all applies all sides; vertical applies internal vertical borders; horizontal applies internal horizontal borders; inside applies both internal directions. The sample preview updates immediately so you can see the active border state before pressing Ok.
Use the Fill tab. The NO COLOR button clears the stored background color by setting it to the special NO_COLOR state. The background color palette sets the base fill color. The Pattern Color dropdown chooses the color used to draw the selected pattern. Each pattern box in the pattern grid selects one pattern style such as Solid, Gray75, Gray50, stripe patterns, and crosshatch patterns. The sample preview canvas redraws after every fill change. When the selected pattern is Solid, the pattern color becomes the final visible fill color; otherwise the preview combines background color, pattern color, and pattern style.
Click Ok to apply the changes. Ok collects the Number, Alignment, Font, and Fill settings into one style object, then applies merge and border actions separately. Cancel restores the original number-format state from currentStyle, clears temporary dialog state, and closes the dialog.

JavaScript API

Based on the current source code, you can use a quick built-in format through setSelectedCellAttr('format', ...), or open the full dialog and apply the same tab-level updates programmatically. For Number, Alignment, Font, and Fill, GridJS uses formatUpdate. For merge and borders, it uses separate range updates.

const xs = x_spreadsheet('#gridjs-demo-uid', option);

// Select B2:D4.
xs.sheet.selector.set(1, 1);
xs.sheet.selector.setEnd(3, 3);

// Apply a built-in quick format.
xs.sheet.data.setSelectedCellAttr('format', 'number');

// Open the full dialog.
xs.sheet.modalMoreNumberFormats.show(1, 1);

// Open the Font tab.
const fontTabIndex = xs.sheet.modalMoreNumberFormats.tabComponent.tabs.findIndex(
  tab => tab.id === 'tabFont'
);
if (fontTabIndex >= 0) {
  xs.sheet.modalMoreNumberFormats.tabComponent.openTab(fontTabIndex);
}

// Apply Number / Alignment / Font / Fill style data.
xs.sheet.data.setRangeAttr(xs.sheet.data.selector.range, 'formatUpdate', {
  custom: '#,##0.00',
  align: 'right',
  valign: 'middle',
  textwrap: true,
  angle: 0,
  font: {
    name: 'Arial',
    size: 12,
    bold: true,
    italic: false,
  },
  color: '#c00000',
  underline: 'Single',
  strike: false,
  bgcolor: '#fff2cc',
});

// Apply merge from the Alignment tab.
xs.sheet.data.setRangeAttr(xs.sheet.data.selector.range, 'merge', true);

// Apply border actions from the Border tab.
xs.sheet.data.setRangeAttr(xs.sheet.data.selector.range, 'border', {
  mode: 'outside',
  style: 'thin',
  color: '#000000',
});

xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setSelectedCellAttr('format', value)`	Applies one of the built-in format keys handled by the quick format workflow.	`value: 'normal' \| 'text' \| 'number' \| 'percent' \| 'rmb' \| 'usd' \| 'eur' \| 'date' \| 'time' \| 'datetime' \| 'duration'`	`void`
`xs.sheet.modalMoreNumberFormats.show(ri, ci, onFormatApplyCallback?)`	Opens the `Format Cells` dialog for the selected cell.	`ri?: number`, `ci?: number`, `onFormatApplyCallback?: function`	`void`
`xs.sheet.modalMoreNumberFormats.tabComponent.openTab(index)`	Switches the dialog to a specific tab after it is opened.	`index: number`	`void`
`xs.sheet.data.setRangeAttr(range, 'formatUpdate', style)`	Applies the style data used by the Number, Alignment, Font, and Fill tabs. The current implementation checks fields such as `custom`, `number`, `font`, `bgcolor`, `align`, `valign`, `pattern`, `pbgcolor`, `angle`, `textwrap`, `indent`, `color`, `strike`, and `underline`.	`range: CellRange`, `style: object`	`void`
`xs.sheet.data.setRangeAttr(range, 'merge', value)`	Applies the merge toggle used by the `Merge cells` checkbox in the Alignment tab.	`range: CellRange`, `value: boolean`	`void`
`xs.sheet.data.setRangeAttr(range, 'border', action)`	Applies one border action such as `outside`, `inside`, `top`, `bottom`, `left`, `right`, `all`, `horizontal`, `vertical`, or `none`.	`range: CellRange`, `action: { mode: string, style: string, color: string }`	`void`

Common Questions

Q: What is the difference between Format and More Number Formats? A: Format applies a built-in format key such as number, usd, date, or time. More Number Formats opens the full Format Cells dialog and can submit richer tab-based changes.

Q: How can I open the full format dialog quickly? A: The current code supports three entry points: the format dropdown item More Number Formats, the context-menu item Format Cells, and Ctrl+1.

Q: How many tabs does Format Cells currently have? A: The current dialog contains five tabs: Number, Alignment, Font, Border, and Fill.

Q: Are border changes stored in the same style object as the other tabs? A: No. In the current implementation, border actions are applied separately through setRangeAttr(range, 'border', action).

Q: Which categories are available in the Number tab? A: The current category list is General, Number, Currency, Accounting, Date, Time, Text, Percentage, Scientific, and Custom.

Java: How to use Paint format

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs includes a Paint format toolbar button for copying formatting from the current selection and applying it to another target. When the button is turned on, the current selection is copied to the internal clipboard. After you click a target cell or range, GridJs performs a format-only paste, clears the clipboard, and turns the Paint format button off.

How to use

Select the source cell or range that already has the formatting you want to reuse.
Click Paint format on the toolbar to turn it on.
Click the target cell or drag to the target range in the sheet. GridJs applies only the copied formatting to that selection.
After the format is applied once, the Paint format button is turned off automatically.
If you want to cancel before applying the format, click Paint format again to turn it off. GridJs clears the internal clipboard when the button is turned off.
Format paste does not run in read mode, and it also stops when the current target is locked.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Copy the current selection into the internal clipboard.
xs.sheet.data.copy();

// Paste only the copied formatting into the current target selection.
await xs.sheet.data.pasteFromInternal('format');

// Toggle the toolbar button state if needed.
xs.sheet.toolbar.paintformatToggle();

Relevant functions

Function	Description	Parameters	Returns
`sheet.data.copy()`	Copies the current selection into the internal clipboard.	None	`void`
`sheet.data.pasteFromInternal(what)`	Pastes from the internal clipboard into the current selection. The Paint format flow uses `format` so only formatting is pasted.	`what` (`'format'`, `'all'`, or other supported paste mode)	`Promise<boolean>`
`sheet.toolbar.paintformatActive()`	Returns whether the Paint format button is currently active.	None	`boolean`
`sheet.toolbar.paintformatToggle()`	Toggles the Paint format button state.	None	`void`

The toolbar handler for Paint format first copies the current selection, and the next target selection triggers paste('format'), which internally calls sheet.data.pasteFromInternal('format').

Common Questions

Q: Does Paint format copy cell values too? A: No. The Paint format flow calls a format-only paste, so it applies formatting without using the normal all-content paste path.

Q: How many times does Paint format stay active? A: The code turns the Paint format button off after one format-only paste and clears the clipboard immediately after that paste finishes.

Q: Can I cancel Paint format before applying it? A: Yes. Clicking the Paint format button again turns it off and clears the internal clipboard.

Q: When will Paint format not apply? A: The paste handler returns immediately in read mode, and it also stops when the current target is locked.

Java: How to use Show Formulas

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

Show Formulas is a toolbar toggle that switches worksheet display between normal cell output and formula text. When it is on, a formula cell displays its formula expression in the cell. When it is off, the cell returns to normal rendered value/text display. If showFormulas is not set in settings, the toolbar state is initialized as off.

How to use

Open a worksheet with the toolbar visible.
Click Show Formulas in the toolbar.
Formula cells now display formula text in the grid.
Click Show Formulas again to switch back to normal display.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Enable formula text display.
xs.sheet.data.settings.showFormulas = true;
xs.reRender();
xs.sheet.toolbar.reset();

// Disable formula text display.
xs.sheet.data.settings.showFormulas = false;
xs.reRender();
xs.sheet.toolbar.reset();

Relevant functions

Function	Description	Parameters	Returns
`x_spreadsheet(selector, option)`	Creates the spreadsheet instance.	`selector` (string), `option` (object)	Spreadsheet instance (`xs`)
`xs.reRender()`	Re-renders the sheet after changing display settings.	None	`xs`
`xs.sheet.toolbar.reset()`	Refreshes toolbar button states from current sheet settings.	None	`void`

xs.reRender() updates table/canvas rendering so the Show Formulas effect is visible. xs.sheet.toolbar.reset() syncs the toolbar toggle state with data.settings.showFormulas.

Common Questions

Q: Why can I not toggle Show Formulas on a protected sheet? A: The toolbar change handler blocks this action when the sheet is locked.

Q: Why is the default state off? A: When data.settings.showFormulas is undefined, toolbar reset sets the Show Formulas toggle state to false.

Q: What happens to rich text when Show Formulas is enabled? A: Rich text rendering is skipped while Show Formulas is on.

Java: Read-only Mode and Edit Mode

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs mode is configured by options.mode, with two values: 'edit' and 'read'. The default mode is 'edit' in defaultSettings. In read mode, GridJs keeps navigation-related interactions, but blocks data-editing paths such as editor input, cell text write, and paste workflows.

How to use

Initialize GridJs in edit mode when users need full editing features.
Initialize GridJs in read mode when users should browse data without changing cell content.
In read mode, these editing-related features are disabled by code:
- Formula bar input and hidden key-input area are set to disabled.
- Opening the in-cell editor is blocked.
- Writing cell text is blocked.
- Paste handlers return immediately in read mode (both regular paste and outer-document paste path).
- Autofill by drag does not run .
- GridInput keydown/composition/paste bindings are attached only when mode is not ‘read’.
In read mode, sheet-tab management is reduced:
- The bottom-bar add button is not rendered.
- Sheet-tab context-menu and double-click rename handlers are not bound.
- Tab click for sheet switching is still bound.
In read mode, the selector is created as readonly (mode !== 'edit'), so the selection corner UI is hidden.

JavaScript API

// Edit mode (default behavior)
const xsEdit = x_spreadsheet('#gridjs-edit', {
  mode: 'edit',
});

// Read-only mode
const xsRead = x_spreadsheet('#gridjs-read', {
  mode: 'read',
});

Relevant functions

Function / Location	Description	Parameters	Returns
`Options.mode` (`index.d.ts`)	Declares supported mode values: `'edit' \| 'read'`.	`mode`: `'edit'` or `'read'`	n/a
`defaultSettings.mode` (`core/data_proxy.js`)	Sets default mode to `'edit'`.	none	n/a
`editorSet(...)` (`component/sheet.js`)	Stops in-cell editing when `data.settings.mode === 'read'`.	`focus`: optional boolean	`void`
`dataSetCellText(...)` (`component/sheet.js`)	Stops cell text write in read mode.	`text`, `state`	`void`
`ContextMenu.setMode(...)` (`component/contextmenu.js`)	Shrinks menu items in read mode to a minimal copy-first set.	`mode`: row/column/range context	`void`
`Bottombar.setItemEvent(...)` (`component/bottombar.js`)	Binds rename/context-menu handlers only in edit mode.	`item`: tab element	`void`

No public runtime API for switching mode after initialization was found in index.d.ts or the inspected Spreadsheet public methods in index.js.

Common Questions

Q: What mode is used if I do not pass options.mode? A: GridJs uses mode: 'edit' from defaultSettings.

Q: What is the simplest way to make GridJs read-only? A: Initialize with { mode: 'read' }.

Q: In read mode, can users still switch worksheets? A: Yes. Sheet-tab click is still bound; only add/rename/context-menu management handlers are removed.

Q: In read mode, why can users not type or paste into cells? A: Multiple edit paths explicitly return early when data.settings.mode === 'read', including editor opening, text writing, and paste handlers.

Java: Zoom Levels

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

GridJs provides a toolbar item with tag zoom-size and label Zoom. The dropdown contains seven preset levels: 50%, 75%, 100%, 125%, 150%, 175%, and 200%. Selecting one preset sends the selected object (for example { text: "150%", number: 1.5 }) through the toolbar change pipeline and calls sheet.setzoom(value.number). On touch devices, GridJs also handles pinch gestures and clamps pinch zoom to the range 0.5 to 2 before calling setzoom.

How to use

Open GridJs and locate the Zoom control in the toolbar.

Click the Zoom dropdown and select one preset value from 50%, 75%, 100%, 125%, 150%, 175%, or 200%.
After selection, GridJs routes the toolbar event as type === 'zoom-size' and applies this.setzoom(value.number).
If you are using a touch device, use a pinch gesture on the sheet area. GridJs reads evt.zoom, clamps values above 2 down to 2, clamps values below 0.5 up to 0.5, and then applies setzoom.
In protected-sheet mode, zoom is still allowed because zoom-size is included in protectSheetAllowOperations.

JavaScript API

const xs = x_spreadsheet('#gridjs-demo-uid', options);

// Programmatically apply zoom.
xs.setZoomLevel(1.25);

// You can also restore normal scale.
xs.setZoomLevel(1);

Relevant functions

Function	Description	Parameters	Returns
`setZoomLevel(v)`	Public Spreadsheet method that forwards zoom changes to `sheet.setzoom(v)`.	`v`: zoom factor (for example `0.5`, `1`, `1.25`, `2`)	`void`
`sheet.setzoom(v)`	Applies zoom to table/data state, updates overlay sizing for zoom `< 1` on non-mobile, calls canvas zoom, re-renders via `sheetReset`, and updates conditional-image zoom.	`v`: zoom factor	`void`
`pinch(evt)`	Touch gesture handler that clamps `evt.zoom` into `[0.5, 2]` before calling `setzoom`.	`evt.zoom`: gesture zoom factor	`void`

The inspected index.d.ts file in this repository does not declare setZoomLevel, but the index.js implementation exposes and uses this method directly.

Common Questions

Q: What zoom presets are available in the toolbar? A: The dropdown defines exactly seven presets: 50%, 75%, 100%, 125%, 150%, 175%, and 200%.

Q: What is the default zoom level when data is initialized? A: DataProxy initializes zoomlevel to 1.

Q: Does pinch zoom have limits? A: Yes. The pinch handler clamps zoom values to a minimum of 0.5 and a maximum of 2.

Q: Is zoom blocked when the sheet is protected? A: No. zoom-size is explicitly included in the allowed operations list for protected sheets.

Java: Set Text Wrap

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Turning on text wrap makes long text automatically break onto new lines inside a cell, keeping all content visible without widening the column. For example, you can wrap a product description so it stays inside a narrow column while still being fully readable.

How to use

Step-by-Step Instructions

Step 1: Select the cells

Action: Click and drag the mouse over the cells you want to align.

You’ll see: The selected range is highlighted with a blue border.

Step 2: Enable Wrap Text

Action: Click the Wrap Text button in the toolbar (icon looks like a curved arrow around lines).

You’ll see: The selected cells now display wrapped text, breaking long lines into multiple lines within each cell.

Method B: Format Cells dialog (full control)

Step 1: Select the cells you want to wrap

Action: Click and drag to highlight the cell(s) that contain the long text.

You’ll see: The selected cells are outlined with a blue border.

Step 2: Open the Format Cells dialog

Action: Right‑click the highlighted cells and choose Format Cells… from the context menu

You’ll see: A modal window titled “Format Cells” appears with several tabs (Number, Alignment, Font, Border, Fill).

Step 3: Go to the Alignment tab

Action: Click the Alignment tab inside the dialog.

You’ll see: Options for Horizontal, Vertical, and a “Text control” section appear.

Step 4: Enable Wrap Text

Action: Check the Wrap text checkbox in the “Text control” section.

You’ll see: A check‑mark appears next to “Wrap text”.

Step 5: Confirm the change

Action: Click the OK button at the bottom of the dialog.

You’ll see: The dialog closes and the selected cells now display wrapped text (multiple lines within the same cell).

For Developers: JavaScript API

Quick Example

// xs is the GridJs instance
// Set text wrap for the currently selected range
xs.sheet.data.setRangeAttr(
  xs.sheet.data.selector.range,   // the range you have selected
  'textwrap',                    // property name
  true                           // enable wrap
);

API Reference

Method	Parameters	Description
`setRangeAttr`	`range: Range`, `property: string`, `value: any`	Updates a visual attribute of the given cell range. Use property ‘textwrap’ with value true to turn wrapping on (or false to turn it off).

Common Questions

Q: Does Wrap text work for merged cells?
A: Yes, but the merged cell must have enough height; otherwise the text will be clipped.

Q: I want to turn off Wrap text for many cells at once.
A: Select the whole range, open the Format Cells dialog, uncheck Wrap text, and click OK. You can also use the API: setRangeAttr(..., 'textwrap', false).

Q: Is Wrap text saved when I export the sheet?
A: The wrap setting is stored in the sheet’s style data, so it persists in exported formats that support cell styling (e.g., XLSX, CSV with formatting).

Java: Text Alignment

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Changing text alignment decides where the content sits inside a cell – left, center, right for horizontal positioning, and top, middle, bottom for vertical positioning. This helps make reports easier to read and gives a professional look.
For example, you can align column headings to the center while keeping data rows left‑aligned.

How to use

Step-by-Step Instructions

Step 1: Select the cells

Action: Click and drag the mouse over the cells you want to align.

You’ll see: The selected range is highlighted with a blue border.

Action: Click the Horizontal Align button in the toolbar (icon shows three horizontal lines).

You’ll see: A small dropdown appears with options Left, Center, Right.

Step 3: Choose a horizontal option

Action: Click Center (or Left / Right as needed).

You’ll see: The text inside the selected cells moves to the chosen horizontal position.

Action: Click the Vertical Align button in the toolbar (icon shows three vertical bars).

You’ll see: A dropdown with options Top, Middle, Bottom.

Step 5: Choose a vertical option

Action: Click Middle (or Top / Bottom as needed).

You’ll see: The text shifts vertically inside each cell to the selected position.

Method B: Format Cells dialog (full control)

Step-by-Step Instructions

Step 1: Select the cells

Action: Click and drag to highlight the range you want to format.

You’ll see: The cells are surrounded by a blue outline.

Step 2: Open the Format Cells dialog

Action: Right‑click the selection and choose Format Cells… from the context menu, or press Ctrl + 1.

You’ll see: A modal window titled Format Cells with several tabs.

Step 3: Switch to the Alignment tab

Action: Click the Alignment tab at the top of the dialog.

You’ll see: Sections for Horizontal, Vertical, and additional text‑control options.

Step 4: Set horizontal alignment

Action: In the Horizontal: dropdown, pick Center (or Left / Right / General).

You’ll see: The dropdown shows the chosen value.

Step 5: Set vertical alignment

Action: In the Vertical: dropdown, pick Middle (or Top / Bottom).

You’ll see: The dropdown updates to the selected vertical option.

Step 6: Apply the changes

Action: Click the OK button at the bottom of the dialog.

You’ll see: The selected cells instantly reflect the new alignment settings.

💡 Tips & Shortcuts

Quick tip: Press Alt + H then A to jump straight to the Horizontal Align toolbar dropdown.
Quick tip: Press Alt + H then V for the Vertical Align toolbar dropdown.
Watch out: Alignment changes only affect the view; they do not alter the underlying data.
Pro move: Use the Format Cells dialog if you also need to adjust text rotation or wrap settings at the same time.

For Developers: JavaScript API

You can change alignment programmatically with GridJs’s public API.

Quick Example

// xs is the GridJs instance already attached to the sheet
// Align the currently selected range to center horizontally and middle vertically

// Horizontal alignment
xs.sheet.data.setRangeAttr(
  xs.sheet.data.selector.range,   // the range that is currently selected
  'align',                        // property name for horizontal alignment
  'center'                        // possible values: 'left', 'center', 'right'
);

// Vertical alignment
xs.sheet.data.setRangeAttr(
  xs.sheet.data.selector.range,
  'valign',                       // property name for vertical alignment
  'middle'                        // possible values: 'top', 'middle', 'bottom'
);

API Reference

Method	Parameters	Description
`setRangeAttr(range, property, value)`	`range: object` – the cell range (e.g., `xs.sheet.data.selector.range`) `property: string` – `'align'` or `'valign'` `value: string` – alignment value (`'left'`, `'center'`, `'right'`, `'top'`, `'middle'`, `'bottom'`)	Sets the specified alignment attribute for the given cell range.
`xs.sheet.data.selector.range`	none	Returns the currently selected cell range object used in `setRangeAttr`.

Note: The API works on any selected range, not just a single cell.

Common Questions

Q: My text isn’t aligning the way I selected. Why?
A: Make sure the cells are still selected when you click the alignment button or OK in the dialog. Changing the selection clears the pending alignment command.

Q: Can I align text diagonally or at a custom angle?
A: The built‑in alignment options cover only horizontal (left/center/right) and vertical (top/middle/bottom). Diagonal or custom angles are not supported in this version.

Q: Will alignment affect printing?
A: Yes. Alignment settings are preserved in the printed output, just like they appear on the screen.

Q: I want to align a whole column quickly. Is there a shortcut?
A: Click the column header to select the entire column, then use the toolbar alignment buttons or the Format Cells dialog as described above.

Q: How do I reset a cell to the default alignment?
A: Open the Format Cells dialog → Alignment tab → set Horizontal to General and Vertical to Bottom, then click OK. Or programmatically set 'align' to 'general' and 'valign' to 'bottom'.

Java: How to Merge and Unmerge

Mon, 01 Jan 0001 00:00:00 +0000

Cell Merge and Unmerge lets you combine a rectangular range of cells into a single larger cell or split a previously merged cell back into its original grid. This is useful for titles, section headers, summary rows, or any layout where a value should span multiple columns or rows.

1. Feature Overview

Merging creates one visual cell that spans several columns and/or rows while preserving the value and style of the top‑left cell in the selected range. Un‑merging restores the original individual cells, keeping the data that was stored in the top‑left cell.

When to use

Add a heading that stretches across the worksheet width.
Combine cells for a total row that should be visually distinct.
Split a merged area when the layout needs to change.

2. Client‑side Usage

2.1 UI Operations

Follow these steps directly in the GridJs spreadsheet UI.

Select a rectangular range – click the first cell, drag to the last cell.
Click “Merge” icon in the toolbar – when the icon is clicked, it toggles to “Un‑merge” if the selection is already merged.
Click the “Merge” icon to un‑merge – if the selected range is merged, clicking the icon again will restore the individual cells.

The spreadsheet automatically redraws the affected area, showing a single merged cell or the restored individual cells.

2.2 JavaScript API

Below is a complete GridJs initialization followed by the exact calls you need to merge or unmerge cells programmatically.

// ------------------------------------------------------------
// 1️⃣ Initialize the x‑spreadsheet instance
// ------------------------------------------------------------
xs = x_spreadsheet('#gridjs-demo-uid', option);

function mergeRange(range) {
    // Apply the merge
    xs.sheet.data.setRangeAttr(range, 'merge', true);
    // Refresh the grid to show changes
    xs.sheet.table.render();
}

function unmergeRange(range) {
    xs.sheet.data.setRangeAttr(range, 'merge', false);
    xs.sheet.table.render();
}

// ------------------------------------------------------------
// Example usage
// ------------------------------------------------------------
// Merge cells A1:B2
mergeRange({sri:0, sci:0, eri:1, eci:1});

// Later, un‑merge the same area
unmergeRange({sri:0, sci:0, eri:1, eci:1});

API Reference

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For merging, set `attr` to `'merge'` and `value` to `true` (merge) or `false` (un‑merge).	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row and column). `attr` – string (`'merge'` only). `value` – boolean (`true` to merge, `false` to un‑merge).	`undefined` (grid refreshes automatically).

Tip – The merge icon is toggleable. If the selected range is already merged, clicking it will un‑merge the cells.
For live demos and more examples, visit: https://github.com/aspose-cells/Aspose.Cells.Grid-for-Java/tree/master/Examples.GridJs

Java: How to Print

Mon, 01 Jan 0001 00:00:00 +0000

GridJs provides a built-in Print Settings modal that allows users to customize the layout and appearance of the worksheet before sending it to the printer or saving it as a PDF. This ensures that large datasets are presented readably on standard paper sizes.

Introduction

Spreadsheets often contain data that exceeds the dimensions of a standard sheet of paper. To produce a professional‑looking document, it is essential to control how the grid data flows across pages, how it is scaled, and what elements are included.

The Print Settings feature allows you to configure:

Page Orientation: Switch between Portrait and Landscape.
Paper Size: Support for standard ISO sizes (A3, A4, etc.).
Scaling: Options to fit content to a specific page count.
Page Order: Control the sequence in which pages are numbered and printed.
Content Visibility: Toggle images and shapes.

Accessing Print Settings

To access the print settings:

Click the Print icon on the toolbar (or select Print from the menu).
The Settings modal window will appear, presenting various configuration options.
After adjusting settings, click OK to generate a preview and open the system print dialog.

Configuration Options

The ModalPrint class provides the following configurable parameters. Below is a detailed explanation of each option:

1. Page Orientation

Determines the layout direction of the paper.

Landscape: (Default) Orients the paper horizontally. Best for spreadsheets with many columns.
Portrait: Orients the paper vertically. Best for spreadsheets with many rows but fewer columns.

2. Paper Size

Select the physical paper size for the output. The available options correspond to standard ISO paper sizes:

A4: (Default) The standard paper size used worldwide (210 × 297 mm).
A3: Larger size, suitable for extensive tables.
A5: Smaller size.
B4, B5: Additional standard sizes.

3. Scale

Scaling is critical for fitting spreadsheet data onto physical pages.

No Scaling: (Default) Prints the data at 100 % size. Data that doesn’t fit will spill over to subsequent pages.
Fit Sheet on One Page: Shrinks the entire worksheet (width and height) to fit on a single sheet of paper. Note: For very large datasets, this may make the text unreadably small.
Fit All Columns on One Page: Scales the width of the data to fit the page width. Rows will spill over to subsequent pages as needed. This is the most common setting for wide tables.
Fit All Rows on One Page: Scales the height of the data to fit the page height. Columns will spill over to horizontal pages.

4. Page Order

When a worksheet is too large to fit on a single page (and scaling is not set to fit on one page), it is split into multiple pages. The Order setting determines the sequence in which these pages are printed.

Down, then over: (Default) Prints pages from top to bottom first, then moves to the right to print the remaining columns (N‑pattern).
Over, then down: Prints pages from left to right first, then moves down to print the remaining rows (Z‑pattern).

5. Images/Shapes

Controls the visibility of floating objects like charts, inserted images, and shapes during printing.

Show: (Default) All images and shapes are included in the print output.
Hide: Images and shapes are excluded, printing only the cell data and grid styles. This is useful for saving ink or producing data‑only reports.

How it Works

When the user confirms the settings in the ModalPrint dialog, the following internal process occurs:

Configuration Capture: The selected options (Orientation, Size, Scale, Order, ImageShow) are captured from the UI form fields.
Preview Generation: The application calculates the page breaks based on the selected Paper Size and Scale.
Rendering:
- If Scale is set to fitsheet, fitcolumns, or fitrows, a transformation matrix is applied to the canvas to reduce the content size.
- If Images/Shapes is set to hide, the rendering loop skips drawing the fabObjects (fabric.js objects) on the canvas.
System Print: The component triggers the browser’s native window.print() method or opens a new window with the generated canvas image, allowing the user to select their physical printer or “Save as PDF”.

Java: Cell Background Color Settings

Mon, 01 Jan 0001 00:00:00 +0000

The GridJS component applies background‑color changes instantly on the client. No additional confirmation step is required unless you open the More Number Formats modal, where you can preview the fill before committing.

Overview

Cell background colour (fill) enhances readability and visual grouping in a spreadsheet. GridJS provides several entry points—including a toolbar split‑button, context‑menu items, a dedicated modal, and a status‑bar indicator—to let users pick a colour or pattern and see the result immediately.

UI Operations

How to start – Click the Background Color (bgcolor) icon on the toolbar. The icon’s bottom border always shows the currently active fill colour (default #ffff00 yellow). Steps

Click the icon to expand the split‑button dropdown anchored to the toolbar.
Choose a colour swatch (theme palette, recent custom colour, or No Color).
The selected cells are filled instantly and the icon border updates to the new colour.

2. Table selection area

How to start – Select a cell or drag to highlight a range (merged cells count as a single unit).

Steps

Click or drag to create the selection rectangle.
With the range selected, press the Background Color toolbar button again (or use the shortcut).
Pick a colour from the same palette; the entire selection, including any merged region, receives the colour immediately.

How to start –
a right‑click context menu

choose Formats Cells and then the Fill tab.

Steps

The modal displays two colour pickers: Background Color and, when a pattern other than Solid is chosen, Pattern Color.
Select the desired background colour (and pattern colour if applicable).
A live preview canvas updates in real time to show the combined effect.
Click OK (or Apply) to commit the fill style to the currently selected cells and close the modal.

5. Other entry points

Area	Path to colour picker
Menubar	Format → Fill → Background Color (opens the same dropdown as the toolbar)
Context menu (right‑click on a cell)	Fill → Background Color (shows the palette at the cursor)
Toggle	No dedicated toggle; colour changes are applied immediately upon selection.
Programmatic	See the JavaScript API section.

Options & Alerts

Immediate application – All UI actions (toolbar, modal OK, status‑bar click) update the cell style instantly on the client.
Pattern fills – When a pattern other than Solid is chosen in the modal, you can also set a Pattern Color to define the secondary colour of the fill.
No colour – Selecting No Color removes any existing background fill from the target cells.

JavaScript API

background colour changes can be achieved by setting the bgcolor attribute on a cell or range using the setRangeAttr method of the data object. After updating the attribute, call the render method to apply the changes visually.

// Assume xs is your x_spreadsheet instance
xs = x_spreadsheet('#gridjs-demo-uid', option);
const range = {"sri":2,"sci":2,"eri":2,"eci":2}; // Define the cell range (row/col indices)
// Set the background color of a specific cell or range
xs.sheet.data.setRangeAttr(range, 'bgcolor', "red");
// Render the changes to update the UI
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For background color, set `attr` to `'bgcolor'` and `value` to `red` (color name) or `#FF0000` (hex code).	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row/column). `attr` – string (`'bgcolor'` only). `value` – string (color name or hex code).	`undefined` (grid refreshes automatically).
`xs.sheet.table.render()`	Re-renders the table UI to reflect any data or style changes.	None.	`undefined`.

Tips & Best Practices

Consistent palette – Use the toolbar colour picker for quick, consistent fills across the sheet; the modal is ideal when you need pattern fills or want to preview the effect first.
Batch updates – When applying the same colour to many separate ranges, select each range and use the toolbar picker; the component batches style updates to reduce rendering overhead.
Performance – The getStylePreview call involves a server round‑trip. Use it sparingly (e.g., only when a modal preview is required) to avoid unnecessary latency.
Merged cells – Selecting any part of a merged region will apply the fill to the whole merged block. Ensure the intended area is selected before picking a colour.

Java: Change Font Family

Mon, 01 Jan 0001 00:00:00 +0000

The GridJs component ships with a Font dropdown in the default toolbar. Selecting a font from this list updates the font‑family of the currently selected cells in the browser.

Overview

Changing the font family improves readability and lets you align the spreadsheet’s visual style with your application’s design language. This guide covers both the interactive UI workflow and the JavaScript API that can be used to set fonts from code.

UI Operations

Open the Toolbar – The toolbar is displayed at the top of the spreadsheet by default.
Locate the Font dropdown – It is shows the current font name.
Click the dropdown to reveal the list of available fonts.
Select a font from the list. The selected font is applied immediately to any cells that are highlighted in the grid.
Verify the change – The cells should now display text in the chosen font family.

Options & Alerts

Supported Fonts – Only fonts recognized by the browser’s CSS engine are listed. If a desired font does not appear, ensure it is loaded on the page.
Multiple Selection – When multiple cells are selected, the dropdown shows the font of the first cell in the range. Changing the font updates all selected cells.
Resetting Font – Choose the default (usually “Arial”) to revert cells to the component’s base font.

JavaScript API

text font family changes can be achieved by setting the font-name attribute on a cell or range using the setRangeAttr method of the data object. After updating the attribute, call the render method to apply the changes visually.

xs = x_spreadsheet('#gridjs-demo-uid', option);
const range = {"sri":2,"sci":2,"eri":2,"eci":2}; // Define the cell range (row/col indices)
// Set the text font name of a specific cell or range
xs.sheet.data.setRangeAttr(range, 'font-name', "Arial");
// Render the changes to update the UI
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For font name, set `attr` to `'font-name'` and `value` to the desired font family (e.g., `"Arial"`).	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row/column). `attr` – string (`'font-name'` only). `value` – string (font family name).	`undefined` (grid refreshes automatically).
`xs.sheet.table.render()`	Re-renders the table UI to reflect any data or style changes.	None.	`undefined`.

Internal Logic

The method updates the cell’s data proxy, which subsequently triggers a re‑render of the cell with the new CSS font-family.
If the provided font name is unavailable, the browser falls back to its default font.

Tips & Best Practices

Batch Styling – For large ranges, loop over cells and call setCellStyle once per cell, or extend the API with a helper that applies the same style to a range.
Refresh After Styling – In rare cases where the UI does not immediately reflect the change, call render() to force a redraw.
Consistency – Keep the font list in sync with your design system to avoid mixing unsupported fonts.

Java: font bold setting

Mon, 01 Jan 0001 00:00:00 +0000

The Bold button toggles the font.bold attribute of the currently selected cell(s). It is accessible via the toolbar, menubar, context‑menu, status bar and the Ctrl + B keyboard shortcut. All UI elements stay synchronized automatically.

Overview

Bold formatting makes the text in a cell appear thicker. In GridJs the bold state is represented by the font.bold property of a cell’s style. Users can toggle this property through several entry points; developers can also control it programmatically via the public JavaScript API.

UI Operations

Hover over the B icon on the toolbar. A tooltip Bold appears.

Click the B icon (or press Ctrl + B) to toggle bold on the selected cell(s).

The button shows a pressed state while bold is active and returns to normal when it is not.
Selecting a different cell or range automatically updates the button’s appearance to match the cell’s font.bold value.

Menubar

Open Format → Text → Font Bold (or use Ctrl + B).
The same toggle logic runs as the toolbar button, updating the cell style and the toolbar’s bold button state.

JavaScript API

font colour changes can be achieved by setting the font-bold attribute on a cell or range using the setRangeAttr method of the data object. After updating the attribute, call the render method to apply the changes visually.

// Assume xs is your x_spreadsheet instance
xs = x_spreadsheet('#gridjs-demo-uid', option);
const range = {"sri":2,"sci":2,"eri":2,"eci":2}; // Define the cell range (row/col indices)
// Set the font color of a specific cell or range
xs.sheet.data.setRangeAttr(range, 'font-bold', true);
// Render the changes to update the UI
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For font bold, set `attr` to `'font-bold'` and `value` to `true` or `false`.	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row/column). `attr` – string (`'font-bold'` only). `value` – boolean (`true` or `false`).	`undefined` (grid refreshes automatically).
`xs.sheet.table.render()`	Re-renders the table UI to reflect any data or style changes.	None.	`undefined`.

Java: Set Font Size

Mon, 01 Jan 0001 00:00:00 +0000

The Set Font Size feature lets end‑users change the text size of the selected cells directly in the browser. The component’s toolbar and menubar expose a ready‑made dropdown that lists common point sizes (e.g., 8 pt, 9 pt, 10 pt …). Selecting a size instantly updates the style of the active cell range.

Overview

Changing font size is a core formatting operation. GridJs provides a Font Size dropdown in both the Toolbar (quick access) and the Text menu of the Menubar (menu‑driven access). The UI reflects the current cell’s font size, so the dropdown title always shows the active size.

UI Operations

Locate the Font Size dropdown in the toolbar – it displays the current size (e.g., 11 pt).
Click the dropdown arrow to reveal the list of predefined sizes.
Click the desired size (e.g., 14 pt).
The selected size is applied immediately to the currently selected cell or range, and the dropdown title updates to the new size.

Using the Menubar

Open the Text menu on the menubar.
Choose Font Size from the submenu – this opens the same size list as the toolbar dropdown.
Pick the required size.
The change is applied instantly, and the menubar entry shows the new size.

Synchronisation with Cell Selection

When you move the selection to a different cell, the dropdown’s title automatically changes to reflect that cell’s font size.
If the selected range contains mixed sizes, the title shows a placeholder (e.g., Multiple), indicating that applying a new size will override the existing values.

JavaScript API

text font changes can be achieved by setting the font-size attribute on a cell or range using the setRangeAttr method of the data object. After updating the attribute, call the render method to apply the changes visually.

xs = x_spreadsheet('#gridjs-demo-uid', option);
const range = {"sri":2,"sci":2,"eri":2,"eci":2}; // Define the cell range (row/col indices)
// Set the text font size of a specific cell or range
xs.sheet.data.setRangeAttr(range, 'font-size', "14");
// Render the changes to update the UI
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For font size, set `attr` to `'font-size'` and `value` to the desired size in points (e.g., `"14"`).	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row/column). `attr` – string (`'font-size'` only). `value` – string (size in points).	`undefined` (grid refreshes automatically).
`xs.sheet.table.render()`	Re-renders the table UI to reflect any data or style changes.	None.	`undefined`.

Tips

Consistent Formatting – Choose sizes from the dropdown to keep formatting uniform across the workbook.
Batch Apply – Select multiple cells before choosing a size to apply the same font size to the entire range in one step.
Responsive Rendering – The component automatically converts the selected point size to pixels, ensuring that the visual appearance matches the printed output.

Java: Text Rotate Setting

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Aspose.Cells GridJs provides a Text Rotate button on the toolbar. Through its dropdown you can choose common rotation styles or specify a custom angle. The chosen rotation is applied immediately to the currently selected cell or range.

UI Operations

Open the rotation menu
Click the Text Rotate button on the toolbar. The dropdown opens, showing a list of rotation options.
Select a predefined rotation
Choose one of the following options:
- Vertical Text
- Angle‑Clockwise
- Angle‑Counter‑Clockwise
- Rotate Text Up
- Rotate Text Down
  The dropdown title updates to reflect the selection and then closes. The rotation is applied to the selected cells.
Apply a custom angle
Choose Other Angle. A modal dialog appears where you can type any angle between ‑90° and 90°. Click OK to apply or Cancel to dismiss.

Options & Alerts

Predefined angles give quick access to the most common orientations.
Custom angle lets you fine‑tune the rotation; entering a value outside the ‑90 → 90 range will be rejected by the UI.
The selected rotation remains active in the toolbar dropdown, so subsequent cell selections will use the same orientation until you change it again.

JavaScript API

text rotation changes can be achieved by setting the textRotate attribute on a cell or range using the setRangeAttr method of the data object. After updating the attribute, call the render method to apply the changes visually.

// Assume xs is your x_spreadsheet instance
xs = x_spreadsheet('#gridjs-demo-uid', option);
const range = {"sri":2,"sci":2,"eri":2,"eci":2}; // Define the cell range (row/col indices)
// Set the text rotation of a specific cell or range
xs.sheet.data.setRangeAttr(range, 'textRotate', "45");
// Render the changes to update the UI
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For text rotation, set `attr` to `'textRotate'` and `value` to the desired angle in degrees (e.g., `"45"`).	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row/column). `attr` – string (`'textRotate'` only). `value` – string (angle in degrees).	`undefined` (grid refreshes automatically).
`xs.sheet.table.render()`	Re-renders the table UI to reflect any data or style changes.	None.	`undefined`.

Tips

Select cells first – Rotation always applies to the active cell or range, so make your selection before opening the dropdown.
Keep the dropdown open – After applying a rotation, the dropdown stays in the chosen state, allowing rapid changes across multiple selections.

Java: Font Color Settings

Mon, 01 Jan 0001 00:00:00 +0000

The GridJs spreadsheet component provides a Font Color button on the toolbar that lets users apply preset or custom colours instantly to the selected cells. Changes are applied immediately without an extra “apply” step.

Overview

Font colour determines the colour of the text displayed in a cell. GridJs implements this feature exclusively through a toolbar button with an attached colour‑picker dropdown. The button reflects the colour of the current selection, and the last used colour is remembered for quick re‑use.

Accessing Font Color

Locate the toolbar at the top of the spreadsheet.
Find the Font‑Color button – an A character with a coloured bottom border indicating the active colour.
Hover the mouse to see the tooltip “Font Color”.

UI Operations

Apply the last used colour

Select one or more cells.
Click the coloured Font‑Color button.
The stored colour is instantly written to the selected cell(s).

Open the colour‑picker

Click the small ▼ arrow next to the Font‑Color button.
The colour‑palette dropdown appears below the button.

Choose a preset swatch

In the opened palette, click any colour swatch or the Automatic entry.
The button’s border updates to the chosen hue.
The colour is applied immediately to the current selection.
The palette closes automatically.

Options & Behaviour

Automatic – restores the default colour (usually black) defined by the spreadsheet theme.
Preset swatches – a set of frequently used colours displayed as square tiles.
Last used colour – remembered across toolbar re‑renders; clicking the main button re‑applies this colour without opening the palette.
Immediate application – no “OK” button is required; the colour is applied as soon as a swatch or custom colour is chosen.

JavaScript API

font colour changes can be achieved by setting the color attribute on a cell or range using the setRangeAttr method of the data object. After updating the attribute, call the render method to apply the changes visually.

// Assume xs is your x_spreadsheet instance
xs = x_spreadsheet('#gridjs-demo-uid', option);
const range = {"sri":2,"sci":2,"eri":2,"eci":2}; // Define the cell range (row/col indices)
// Set the font color of a specific cell or range
xs.sheet.data.setRangeAttr(range, 'color', "red");
// Render the changes to update the UI
xs.sheet.table.render();

Relevant functions

Function	Description	Parameters	Returns
`xs.sheet.data.setRangeAttr(range, attr, value)`	Modifies an attribute of the currently selected range. For font color, set `attr` to `'color'` and `value` to `red` (color name) or `#FF0000` (hex code).	`range` – object (contains `sri`, `sci`, `eri`, `eci` for start/end row/column). `attr` – string (`'color'` only). `value` – string (color name or hex code).	`undefined` (grid refreshes automatically).
`xs.sheet.table.render()`	Re-renders the table UI to reflect any data or style changes.	None.	`undefined`.

Tips & Best Practices

Quick reuse: After selecting a custom colour, the button’s border updates, allowing you to re‑apply the same colour with a single click.
Consistent UI updates: Switching cells automatically refreshes the toolbar state, ensuring you always see the correct current colour.
Protected ranges: When the selection includes read‑only cells, the button is disabled – attempt to change colour only on writable cells.
Performance: Colour changes are sent to the back‑end as part of a generic style‑update request, so they are lightweight and do not require a separate “apply” action.
Accessibility: The tooltip “Font Color” remains visible even when the button is disabled, helping users understand the purpose of the control.

Java: Insert Image

Mon, 01 Jan 0001 00:00:00 +0000

Overview

You can place a picture inside any cell so that your data looks richer and easier to understand.
For example, you can insert a product photo next to its price or add a company logo to the header row.

How to use

Step-by-Step Instructions

Step 1: Open the Insert Image menu
Action: Click the Insert Image dropdown button (it looks like a small picture icon) on the Toolbar.
You’ll see: A small menu appears with options such as Upload Image and From URL.

Step 2: Choose the source
Action: Select From Local to pick a file from your computer or select From URL to paste a web address.
You’ll see:

For From Local – a file‑picker dialog opens.
For From URL – a small Insert Image URL modal appears.

Step 3: Provide the image

From Local: In the file‑picker, navigate to the picture file, click Open.
From URL: In the modal, paste the image URL into the text field.
You’ll see: The selected file name or the entered URL displayed in the dialog.

Step 4: Confirm insertion
Action: Click Insert (or OK) in the dialog.
You’ll see: The image appears inside the currently selected cell, scaled to fit the cell size.

💡 Tips & Shortcuts

Quick tip: After inserting, drag the cell’s corner to resize the image together with the cell.
Watch out: Only direct image URLs (ending with .png, .jpg, .gif, etc.) work in the From URL option.
Pro move: Use Upload Image for high‑resolution pictures; the sheet automatically compresses them for faster loading.

Common Questions

Q: My picture looks stretched inside the cell.
A: The image scales to fit the cell dimensions. Resize the cell (drag the column/row borders) to adjust the picture’s aspect ratio.

Q: Why does the image disappear after I save and reopen the file?
A: Images are stored as embedded data. Ensure you save the workbook using the Save button; the picture will be retained.

Q: Is there a limit to the image size?
A: Images larger than 5 MB may be loading by long time. Resize large pictures before uploading.

Q: Where can I find the Insert Image button if I don’t see it?
A: It’s on the main Toolbar near the Fill Color and Border icons. If the toolbar is collapsed, click the ≫ arrow to expand it.

Java: Validation Input Settings

Mon, 01 Jan 0001 00:00:00 +0000

Data validation helps ensure that users enter only allowed values in cells. GridJs provides a full‑featured modal dialog where you can define the rule type, specify the target range, and customize helpful messages and error alerts.

Overview

The Validation Input Settings feature is accessed entirely in the browser. A dedicated Data Validation button on the toolbar (or the context/menubar) opens a modal dialog with three tabs:

Criteria – Choose the rule type and define the allowed values/ranges.
Input Message – Optional tip shown when the cell is selected.
Error Alert – Message displayed when a user tries to enter an invalid value.

All configuration is stored in the sheet model, and the component validates edits automatically.

UI Operations

Opening the Validation Dialog

right‑click a cell (or a selected range) and choose Data Validation…, or use Data → Validation from the menubar.

Criteria Tab

In the Allow dropdown, select the rule type (e.g., Whole Number, Decimal, List, Date, etc.).
Based on the chosen type, the dialog shows the relevant fields:
- Value1 and Value2 inputs (each ~70 % width).
- Operator dropdown (e.g., between, equal to).
- For List, toggle In‑cell dropdown to display a drop‑down list directly in the grid.
To define the target cell range, click the range‑select icon next to Value2.

Range‑Selection Page

The spreadsheet UI (sheet tabs, footer, context menu) is temporarily hidden and the background is masked.
The validation modal moves to the top‑right corner.
An input box shows the current range (e.g., A1:B10). Edit it manually or click cells in the grid to pick a range.
Click the Return (back‑arrow) button to confirm the selection or cancel to keep the previous range.

Input Message Tab

Switch Show Input Message on/off.
Fill Title and Message fields with the text you want users to see when the cell becomes active.
Choose an icon (Stop, Warning, Information) that appears alongside the message.

Error Alert Tab

Switch Show Error Alert on/off.
Pick an Alert Style:
- Stop – red “X” (blocks the entry).
- Warning – yellow “!” (allows entry after confirmation).
- Information – blue “i” (informational only).
Provide Title and Error Text that will be displayed when a user violates the rule.
Click Apply to save the rule, or Cancel to discard changes.

Saving & Applying

Press Apply on any tab to commit the validation rule to the selected range.
The rule is now active; any subsequent edit to cells in that range triggers automatic validation.

Tips & Best Practices

Choose the narrowest rule needed. Using Whole Number with a between operator reduces the chance of accidental invalid entries.
Enable In‑cell dropdowns for list‑type rules to give users a visual selection list.
Provide a helpful Input Message – it appears before the user types, reducing validation errors.
Select the appropriate Error Alert style:
- Stop for critical data (e.g., IDs).
- Warning when you want to allow the entry after user confirmation.

Java:

Mon, 01 Jan 0001 00:00:00 +0000

——— title: How to use Comment description: Add, edit, remove, and navigate cell comments, with a marker on the cell and a hover tip showing the note. keywords: Comment, Edit comment, Remove comment, Previous comment, Next comment, insertComment, newComment, comments type: docs weight: 1 url: /java/aspose-cells-gridjs/user-guide/how-to-comment/ aliases:

/java/aspose-cells-gridjs/how-to-use-comment
/java/aspose-cells-gridjs/how-to-add-comment
/java/aspose-cells-gridjs/how-to-edit-comment
/java/aspose-cells-gridjs/how-to-remove-comment
/java/aspose-cells-gridjs/how-to-navigate-comments ———

Introduction

Comments are stored per cell and rendered as an indicator on the cell’s top-right corner. Hovering a commented cell shows a comment tip with the note content, and opening Comment displays an inline editor prefilled with the existing note. Previous/Next comment moves to the nearest earlier or later comment by row and column order. In collaborative mode, comment changes are sent to the server.

How to use

Select a cell, right-click to open the context menu, then choose Comment.
Or open the Insert menu and click Comment to start editing the selected cell.
Enter text in the editor (placeholder: “Please enter text”), then click outside the editor to save. The cell shows a comment marker after saving.
Open the Review menu to use Edit comment, Remove comment, Previous comment, or Next comment.
Hover a commented cell to display the comment tip.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Add or update a comment. xs.sheet.setComment(ri, ci, ‘Aspose’, ‘Comment text’);

// Remove a comment. xs.sheet.removeComment(ri, ci);

Relevant functions

Function	Description	Parameters	Returns
sheet.setComment(ri, ci, author, note)	Add or update a comment on the target cell. If note is empty (or empty HTML), the comment is removed. If note is non-empty and not wrapped in a tag, the note is sanitized and wrapped with a default font style.	ri (row index), ci (column index), author (string), note (HTML string)	void
sheet.removeComment(ri, ci)	Remove the comment from the target cell.	ri (row index), ci (column index)	void

sheet.setComment(…) updates the comment entry for the target cell, and removes it when the note is empty. sheet.removeComment(…) clears the comment for the target cell.

Common Questions

Q: Why did my comment disappear after saving? A: If the note is empty or considered empty HTML, the comment is removed.

Q: How do Previous comment and Next comment choose the target? A: Comments are sorted by row and column; Previous chooses the nearest earlier comment and Next chooses the nearest later comment.

Q: Where do comments show in the UI? A: A marker is drawn on the cell’s top-right corner, and hovering the cell shows a comment tip.

Java:

Mon, 01 Jan 0001 00:00:00 +0000

——— title: How to use AutoFilter and Sort description: Enable AutoFilter on a selected range to apply per-column sort and filtering, or open the Sort dialog to run multi-level sorting on the selection. keywords: AutoFilter, Sort, SortFilter, Sort A -> Z, Sort Z -> A, Filter results visible to me only type: docs weight: 1 url: /java/aspose-cells-gridjs/user-guide/how-to-insert-sort-and-autoFilter/ aliases:

/java/aspose-cells-gridjs/how-to-use-autofilter
/java/aspose-cells-gridjs/how-to-use-sort
/java/aspose-cells-gridjs/how-to-sort-and-filter
/java/aspose-cells-gridjs/how-to-autofilter-sort
/java/aspose-cells-gridjs/how-to-apply-autofilter ———

Introduction

AutoFilter lets you toggle filtering for the current selection range and provides a per-column Sort/Filter panel from the header row. The Sort/Filter panel includes “Sort A -> Z”, “Sort Z -> A”, and a selectable value list, plus a “Filter results visible to me only” option in collaborative mode. The Sort button opens a dedicated Sort dialog that supports multiple sort levels, different sort-on types, and orientation options.

How to use

Select a range that includes the header row, then click AutoFilter on the toolbar or in the Edit menu to toggle filtering on the range.
Click the filter dropdown in a header cell to open the Sort/Filter panel.
In the panel, choose Sort A -> Z or Sort Z -> A, select the values to keep, and (in collaborative mode) toggle Filter results visible to me only if needed. Click OK to apply.
For multi-level sorting, select a range and click Sort on the toolbar or in the Edit menu to open the Sort dialog.
In the Sort dialog, confirm the range, choose Sort by, Sort on, and Order, optionally add more levels, set Orientation and My data has headers, then click OK.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Toggle AutoFilter for the current selection. xs.sheet.data.autofilter();

// Apply a filter and optional sort to a column in the current AutoFilter range. xs.sheet.data.setAutoFilter(ci, order, operator, values, unfilterValueSet, unfilterRecheck, showFilterResultForMeOnly);

// Run a sort operation on the current selection (or a provided range). xs.sheet.data.doSortOpr(ci, order, isHeader, sortOn, colorValues, positionValues, orientation, range);

Relevant functions

Function	Description	Parameters	Returns
data.autofilter()	Toggle AutoFilter on the current selection range.	None.	void
data.setAutoFilter(ci, order, operator, values, unfilterValueSet, unfilterRecheck, showFilterResultForMeOnly)	Apply
filter values and optional sort order for one column in the active AutoFilter range.	ci (column index), order (‘asc’ or
‘desc’ or null), operator (e.g., ‘in’ or ‘all’), values (array of filter keys), unfilterValueSet (Set), unfilterRecheck
(Set), showFilterResultForMeOnly (boolean).	void
data.doSortOpr(ci, order, isHeader, sortOn, colorValues, positionValues, orientation, range)	Execute a sort operation
for the current selection or the provided range, with support for multi-level sorting.	ci (array of column indices),
order (array of ‘asc’/‘desc’), isHeader (boolean), sortOn (array of ‘cellvalue’/‘cellcolour’/‘fontcolour’), colorValues
(array), positionValues (array), orientation (‘top2bottom’ or ‘left2right’), range (optional CellRange).	void

data.autofilter() toggles the AutoFilter state for the current selection. data.setAutoFilter(…) updates filter values and sort order for a specific column in the active AutoFilter and then refreshes the filtered result. data.doSortOpr(…) sends a sort operation using the provided sort levels, orientation, and optional range.

Common Questions

Q: Why can’t I enable AutoFilter on my selection? A: If the selection overlaps an existing table AutoFilter, the UI shows “there is already table autofilter in the selected range” and AutoFilter is not activated.

Q: Does AutoFilter sorting include the header row? A: No. When AutoFilter applies sorting, it sorts starting from the row below the header.

Q: Why does the Sort dialog show an error about merged areas? A: If the selected range contains merged areas, sorting is blocked and the UI shows “The select range has merge areas,we do not support sort on merge areas”.

Q: When is “Filter results visible to me only” available, and what does it do? A: It appears only when collaborative mode is enabled. If you uncheck it, the filter operation is sent to the server so others can see it; if checked, it stays local.

Java:

Mon, 01 Jan 0001 00:00:00 +0000

——— title: How to use Search description: Open the Search dialog to find values, formulas, or comments, then navigate or replace matches. keywords: Search, Find what, Replace, Replace All, Look in, Match entire contents, Case Sensitive, Values, Formulas, Comments type: docs weight: 1 url: /java/aspose-cells-gridjs/user-guide/how-to-search/ aliases:

/java/aspose-cells-gridjs/how-to-find
/java/aspose-cells-gridjs/how-to-replace
/java/aspose-cells-gridjs/how-to-replace-all
/java/aspose-cells-gridjs/how-to-search-comments
/java/aspose-cells-gridjs/how-to-search-formulas

———

Introduction

Search opens a dialog that lets you find text across Values, Formulas, or Comments, with options like Case Sensitive and Match entire contents. You can move through matches with Next and Previous, and the current match is highlighted in the grid. A separate Find & Replace view lets you replace a single match or all matches.

How to use

Open Search from the toolbar or the Edit menu, or press Ctrl + F.
In Find what, enter your text, then choose Look in (Values, Formulas, or Comments).
Optionally toggle Case Sensitive and Match entire contents, then click Next or Previous to navigate matches.
To replace, press Ctrl + H to open Find & Replace, enter Replace with, then use Replace or Replace All.

JavaScript API

xs = x_spreadsheet('#gridjs-demo-uid', option);

// Open Search (Find) dialog. xs.sheet.modalSearch.show();

// Open Find & Replace dialog. xs.sheet.modalSearch.show(true);

Relevant functions

Function	Description	Parameters	Returns
sheet.modalSearch.show(showReplace)	Show the Search dialog; when showReplace is true, the Replace fields are shown
and Look in is hidden.	showReplace (boolean)	void
sheet.modalSearch.hide()	Close the Search dialog.	None	void

sheet.modalSearch.show(showReplace) displays the Search UI and optionally the Replace UI based on the boolean parameter. sheet.modalSearch.hide() closes the dialog and clears the current search highlight.

Common Questions

Q: What can I search in? A: The Search dialog supports Values, Formulas, and Comments via the Look in dropdown.

Q: How do I open Replace? A: Use Ctrl + H (or call sheet.modalSearch.show(true)); the Replace fields appear and Look in is hidden.

Q: What happens if no matches are found? A: The UI shows an info message indicating that nothing was found.