Skip to main content

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

Spreadsheet Class

A client-side Spreadsheet object.

#Declaration

TypeScript
class Spreadsheet

#Methods

#applyCellEdit Method

Commit the editor’s value to the active cell.

#Declaration

TypeScript
applyCellEdit(): void

#Remarks

The applyCellEdit method deactivates the active cell editor and commits its value to the cell. If the cell editor is not activated by an end-user, the method is not in effect. To indicate when a cell editor is activated, subscribe to the cellBeginEdit event.

Use the cancelCellEdit method to deactivate the editor and clear its value.

#cancelCellEdit Method

Cancels the active cell editing.

#Declaration

TypeScript
cancelCellEdit(): void

#Remarks

The cancelCellEdit method deactivates the active cell editor and clears its value. Use the applyCellEdit method to deactivate the editor and commit the editor’s value to the active cell.

If the cell editor is not activated by an end-user, the method is not in effect. To indicate when a cell editor is activated, subscribe to the cellBeginEdit event.

#focus Method

Sets input focus to the Spreadsheet.

#Declaration

TypeScript
focus(): void

#getActiveCellValue Method

Gets the value of the currently active cell.

#Declaration

TypeScript
getActiveCellValue(): any

#Returns

Type Description
any

The currently active cell’s value.

#getActiveSheetName Method

Gets a name of the worksheet that is currently displayed in the spreadsheet.

#Declaration

TypeScript
getActiveSheetName(): string

#Returns

Type Description
string

The active worksheet’s name.

#getCellBounds(colModelIndex, rowModelIndex) Method

Gets the specified cell’s bounds.

#Declaration

TypeScript
getCellBounds(
    colModelIndex: number,
    rowModelIndex: number
): Rectangle

#Parameters

Name Type Description
colModelIndex number

The zero-based column index.

rowModelIndex number

The zero-based row index.

#Returns

Type Description
Rectangle

An object that defines the rectangle with the specified position and size.

#Remarks

The method returns the absolute position and size of the selected cell. The cell’s absolute position is defined relative to the page and is changed if an end-user scrolls a document (changes the visible cells range).

Spreadsheet cell bounds

#getCellComment(colModelIndex, rowModelIndex) Method

Returns the comment associated with the specified data cell.

#Declaration

TypeScript
getCellComment(
    colModelIndex: number,
    rowModelIndex: number
): any

#Parameters

Name Type Description
colModelIndex number

The data cell’s column index.

rowModelIndex number

The data cell’s row index.

#Returns

Type Description
any

The specified cell’s comment.

#getCellValue(colModelIndex, rowModelIndex) Method

Gets the value of the specified cell.

#Declaration

TypeScript
getCellValue(
    colModelIndex: number,
    rowModelIndex: number
): any

#Parameters

Name Type Description
colModelIndex number

The cell’s column index.

rowModelIndex number

The cell’s row index.

#Returns

Type Description
any

The specified cell’s value.

#Remarks

The method might return an irrelevant value of the specified cell in the following cases:

  • The specified cell is placed far from the displayed data cells. In this case, the method returns the null value since the client-side control stores the values only for a small area about the displayed data cells.

  • The document is used by more than one end-user. The method returns the value that is different from the value stored on the server side if the document is open and does not receive updates from the server side while another end-user has updated the server-side value.

#getEditMode Method

Returns the type of the element currently being edited in the Spreadsheet control.

#Declaration

TypeScript
getEditMode(): EditMode

#Returns

Type Description
EditMode

The spreadsheet element’s type.

#getSelection Method

Returns the current selection.

#Declaration

TypeScript
getSelection(): Selection

#Returns

Type Description
Selection

An object that defines the current selection.

#getSpreadsheetState Method

Gets the Spreadsheet’s client state.

#Declaration

TypeScript
getSpreadsheetState(): SpreadsheetClientState

#Returns

Type Description
SpreadsheetClientState

An object that contains information about the Spreadsheet’s client state.

#hasUnsavedChanges Method

Indicates whether any unsaved changes are contained in the current document.

#Declaration

TypeScript
hasUnsavedChanges(): boolean

#Returns

Type Description
boolean

true, if the document contains unsaved changes; otherwise, false.

#print(target) Method

Invokes the browser print dialog to print the sheet content.

#Declaration

TypeScript
print(
    target: string
): void

#Parameters

Name Type Description
target string

The target name.

#setCellEditorText(text) Method

Sets the cell editor’s value.

#Declaration

TypeScript
setCellEditorText(
    text: string
): void

#Parameters

Name Type Description
text string

The text received by the cell editor.

#Remarks

The setCellEditorText method passes the text parameter’s value to the active cell’s editor. Use the applyCellEdit or cancelCellEdit methods to commit the received value or roll it back respectively.

If the cell editor is not activated by an end-user, the method is not in effect. Subscribe to the cellBeginEdit event to indicate when a cell editor is activated.

#setFullscreenMode(fullscreen) Method

Enables you to switch the full-screen mode of the Spreadsheet.

#Declaration

TypeScript
setFullscreenMode(
    fullscreen: boolean
): void

#Parameters

Name Type Description
fullscreen boolean

true to activate full-screen mode; false to deactivate full-screen mode.

#Remarks

In full-screen mode, Spreadsheet occupies the browser’s entire client region and can be resized with the browser window.

#Events

#beginSynchronization Event

Fires after a client change has been made to the document and the client-server synchronization starts to apply the change on the server.

#Declaration

TypeScript
beginSynchronization: BeginSynchronizationEvent

#Event Data

The beginSynchronization event's data class is EventArgs.

#Remarks

After a document change is introduced on the client (documentChanged) the Spreadsheet starts synchronization between the client and server parts to apply the change and synchronize the document model. You can handle the beginSynchronization and endSynchronization events to be informed about the synchronization status.

#cellBeginEdit Event

Occurs before the cell editor is opened.

#Declaration

TypeScript
cellBeginEdit: CellBeginEditEvent

#Event Data

The cellBeginEdit event's data class is CellBeginEditEventArgs. The following properties provide information specific to this event:

Property Description
cancel Indicates whether the action that raised the event should be canceled. Inherited from CancelEventArgs.
columnIndex Gets the active cell’s column index.
formula Gets the active cell’s formula.
rowIndex Gets the active cell’s row index.
sheetName Gets the current worksheet’s name.
value Gets the active cell’s current value.

#Remarks

The event triggers when an end-user activates a cell’s editor. Handle the cellBeginEdit event to perform any actions before the cell editor is opened.

#cellCancelEdit Event

Occurs before the active cell’s editor is closed and the entered value is rolled back.

#Declaration

TypeScript
cellCancelEdit: CellCancelEditEvent

#Event Data

The cellCancelEdit event's data class is CellCancelEditEventArgs. The following properties provide information specific to this event:

Property Description
cancel Indicates whether the action that raised the event should be canceled. Inherited from CancelEventArgs.
columnIndex Gets the active cell’s column index.
formula Gets the active cell’s formula.
rowIndex Gets the active cell’s row index.
sheetName Gets the current worksheet’s name.
value Gets the active cell’s current value.

#Remarks

The cellCancelEdit event triggers when an end-user cancels edit of the active cell or the cancelCellEdit method is called. Handle the cellCancelEdit event to perform any actions before the Spreadsheet deactivates the cell editor and rolls back the entered value.

#cellEndEdit Event

Occurs before the cell editor is closed and the entered value is committed.

#Declaration

TypeScript
cellEndEdit: CellEndEditEvent

#Event Data

The cellEndEdit event's data class is CellEndEditEventArgs. The following properties provide information specific to this event:

Property Description
cancel Indicates whether the action that raised the event should be canceled. Inherited from CancelEventArgs.
columnIndex Gets the active cell’s column index.
editorText The text stored in the active cell’s editor.
formula Gets the active cell’s formula.
rowIndex Gets the active cell’s row index.
sheetName Gets the current worksheet’s name.
value Gets the active cell’s current value.

#Remarks

The event triggers when an end-user ends cell edit or the applyCellEdit method is called. Handle the cellEndEdit event to perform any actions before the Spreadsheet deactivates the cell editor and commits the entered value.

#customCommandExecuted Event

Occurs after a custom command has been executed on the client side.

#Declaration

TypeScript
customCommandExecuted: CustomCommandExecutedEvent

#Event Data

The customCommandExecuted event's data class is CustomCommandExecutedEventArgs. The following properties provide information specific to this event:

Property Description
commandName Gets the name of the processed command.
parameter Provides additional information about the processed command.

#Remarks

Handle the customCommandExecuted event to perform specific client actions in response to a command initiated by a click on a custom command (such as a ribbon item or context menu item) in the Spreadsheet.

#documentChanged Event

Fires if any change is made to the Spreadsheet’s document on the client.

#Declaration

TypeScript
documentChanged: DocumentChangedEvent

#Event Data

The documentChanged event's data class is EventArgs.

#Remarks

The documentChanged event notifies about any client change made in the Spreadsheet’s document.

#endSynchronization Event

Fires after a document change has been applied to the server and server and client document models have been synchronized.

#Declaration

TypeScript
endSynchronization: EndSynchronizationEvent

#Event Data

The endSynchronization event's data class is EventArgs.

#Remarks

After a document change is introduced on the client (documentChanged) the Spreadsheet starts synchronization between the client and server parts to apply the change and synchronize the document model. You can handle the beginSynchronization and endSynchronization events to be informed about the synchronization status.

#hyperlinkClick Event

Occurs when a hyperlink is clicked in the Spreadsheet’s document.

#Declaration

TypeScript
hyperlinkClick: HyperlinkClickEvent

#Event Data

The hyperlinkClick event's data class is HyperlinkClickEventArgs. The following properties provide information specific to this event:

Property Description
handled Specifies whether the event is handled, and the default processing is not required.
htmlEvent Gets a DHTML event object that relates to the processed event.
hyperlinkType Identifies the clicked hyperlink type.
targetUri Gets the clicked link’s URI.

#init Event

Occurs on the client side after the control has been initialized.

#Declaration

TypeScript
init: InitEvent

#Event Data

The init event's data class is EventArgs.

#popupMenuShowing Event

Occurs before the context menu is displayed and enables menu customization.

#Declaration

TypeScript
popupMenuShowing: PopupMenuShowingEvent

#Event Data

The popupMenuShowing event's data class is PopupMenuShowingEventArgs. The following properties provide information specific to this event:

Property Description
cancel Indicates whether the action that raised the event should be canceled. Inherited from CancelEventArgs.
menuItems Provides access to a collection of menu items in the context menu being invoked.
menuType Gets the currently displayed context menu’s type.

#Remarks

Set the cancel property to true to prevent the popup menu from being displayed.

#Example

For a full example, see Spreadsheet - Context Menu Customization demo.

@(Html.DevExpress()
   .Spreadsheet("spreadsheet")
   .Height("500px")
   .Width("100%")
   .ConfirmOnLosingChanges(confirm => confirm.Enabled(false))
   .DocumentRequestHandlerUrl(Url.Action("DxDocumentRequest"))
   .Open(documentPath)
   .ClientSideEvents(events => {
       events.OnPopupMenuShowing("SpreadsheetPopupMenuShowing");
       events.OnCustomCommandExecuted("SpreadsheetCustomCommandExecuted");
   })
)

#protectionWarning Event

Occurs when attempting to edit a locked cell in a protected worksheet.

#Declaration

TypeScript
protectionWarning: ProtectionWarningEvent

#Event Data

The protectionWarning event's data class is EventArgs.

#Remarks

Each time a user attempts to modify a locked cell, the warning dialog appears. Set the cancel event parameter to true to prevent the dialog.

#selectionChanged Event

Occurs when a selection is changed in the Spreadsheet.

#Declaration

TypeScript
selectionChanged: SelectionChangedEvent

#Event Data

The selectionChanged event's data class is SelectionChangedEventArgs. The following properties provide information specific to this event:

Property Description
selection Gets an object that defines the currently selected region within the Spreadsheet.

#Remarks

The selectionChanged event allows you to respond to a selection being changed in the spreadsheet control on the client side.