Spreadsheet Class

A client-side Spreadsheet object.

Declaration

class Spreadsheet

Methods

applyCellEdit Method

Commit the editor’s value to the active cell.

Declaration

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

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

focus(): void

getActiveCellValue Method

Gets the value of the currently active cell.

Declaration

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

getActiveSheetName(): string

Returns

Type	Description
string	The active worksheet’s name.

getCellBounds(colModelIndex, rowModelIndex) Method

Gets the specified cell’s bounds.

Declaration

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

getCellComment(colModelIndex, rowModelIndex) Method

Returns the comment associated with the specified data cell.

Declaration

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

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

getEditMode(): EditMode

Returns

Type	Description
EditMode	The spreadsheet element’s type.

getSelection Method

Returns the current selection.

Declaration

getSelection(): Selection

Returns

Type	Description
Selection	An object that defines the current selection.

getSpreadsheetState Method

Gets the Spreadsheet’s client state.

Declaration

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

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

print(
    target: string
): void

Parameters

Name	Type	Description
target	string	The target name.

setCellEditorText(text) Method

Sets the cell editor’s value.

Declaration

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

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

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

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

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

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

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

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

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

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

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

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.

Razor

@(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");
   })
)

JS

function SpreadsheetPopupMenuShowing(s, e) {
      if (e.menuType === PopupMenuType.Cell) {
          e.menuItems.Clear();
          if (needToAddCustomMenuItems(s)) {
              if (isSelectedCellOfType(s, currencyColumns))
                  addCustomMenuItem(e.menuItems, convertCurrencyCommand);
              if (isSelectedCellOfType(s, discountColumns))
                  addCustomMenuItem(e.menuItems, discountCommand);
              if (isSelectedCellOfType(s, weightColumns))
                  addCustomMenuItem(e.menuItems, convertUnitsCommand);
          }
      }
      else if (e.menuType !== PopupMenuType.AutoFilter)
          e.cancel = true;
}

protectionWarning Event

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

Declaration

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

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.