Events
- 4 minutes to read
This topic provides a comprehensive list of events raised in the SpreadsheetControl. All events are grouped into five categories, according to the functions they perform:
- Track User Activity
- Custom Draw
- Handle Exceptions
- Track Changes to the Document Content
- Track Modifications Performed via API
Track User Activity
The table below lists the sequence of events that are raised when an end-user performs a particular operation in the SpreadsheetControl. While it is not a comprehensive list of all end-user actions, it details events for the most common operations performed by an end-user.
User Action | Event |
|---|---|
Create a blank workbook. | SpreadsheetControl.DocumentClosing SpreadsheetControl.InitializeDocument SpreadsheetControl.EmptyDocumentCreated |
Load a workbook. | SpreadsheetControl.DocumentClosing SpreadsheetControl.BeforeImport SpreadsheetControl.InitializeDocument SpreadsheetControl.DocumentLoaded |
Save a workbook. | SpreadsheetControl.BeforeExport |
Print a workbook. | |
Insert a new worksheet. | SpreadsheetControl.SheetInserted SpreadsheetControl.ActiveSheetChanging |
Click a worksheet tab in the Sheet Tab Selector. | SpreadsheetControl.ActiveSheetChanging |
Rename a worksheet. | SpreadsheetControl.SheetRenaming |
Delete a worksheet. | SpreadsheetControl.ActiveSheetChanged |
Insert columns in a worksheet. | SpreadsheetControl.ColumnsInserted |
Remove columns from a worksheet. | SpreadsheetControl.ColumnsRemoved |
Insert rows in a worksheet. | SpreadsheetControl.RowsInserted |
Remove rows from a worksheet. | SpreadsheetControl.RowsRemoved |
Freeze rows and columns. | |
Unfreeze rows and columns. | |
Select cells, ranges, rows, columns or shapes on a worksheet. | |
Activate the cell’s in-place editor or Formula Bar, and begin editing cell content. | |
Finalize the modification of cell content and close the in-place editor. | SpreadsheetControl.CellEndEdit SpreadsheetControl.CellValueChanged |
Finalize the modification of cell content by clicking the Enter button on the Formula Bar. | SpreadsheetControl.CellEndEdit SpreadsheetControl.CellValueChanged SpreadsheetControl.ContentChanged |
Cancel the input by pressing the ESC key. | SpreadsheetFormulaBarControl.Rollback |
Cancel the input by clicking the Cancel button on the Formula Bar. | SpreadsheetFormulaBarControl.Rollback SpreadsheetControl.CellCancelEdit |
Apply formatting options to cells. | |
Click a hyperlink. | |
Zoom in or out of a worksheet. | |
Right-click a visual element of the SpreadsheetControl. |
Custom Draw
The SpreadsheetControl provides numerous custom draw events that allow you to customize document appearance. To custom paint worksheet cells, use the SpreadsheetControl.CustomDrawCell and SpreadsheetControl.CustomDrawCellBackground events. To custom draw row and column headings, handle the SpreadsheetControl.CustomDrawRowHeader, SpreadsheetControl.CustomDrawRowHeaderBackground, SpreadsheetControl.CustomDrawColumnHeader and SpreadsheetControl.CustomDrawColumnHeaderBackground events. To custom paint frozen pane borders in the SpreadsheetControl, handle the SpreadsheetControl.CustomDrawFrozenPaneBorder event.
Note that custom painting is not saved in a workbook file.
Handle Exceptions
You can catch exceptions that are not processed by the SpreadsheetControl by handling the SpreadsheetControl.InvalidFormatException and SpreadsheetControl.UnhandledException events. Use the SpreadsheetControl.InvalidFormatException event to handle exceptions raised when an end-user tries to load a document in an unsupported format. The SpreadsheetControl.UnhandledException event allows you to catch exceptions that may occur when an end-user executes a command via the SpreadsheetControl UI. For example, use this event to prevent the application from crashing when an end-user attempts to save a document to a read-only or locked file.
Track Changes to the Document Content
There are two events indicating that the current document has been modified: SpreadsheetControl.ContentChanged and SpreadsheetControl.ModifiedChanged. The SpreadsheetControl.ContentChanged event occurs each time the document content has been changed. When you use API methods to assign a value or apply formatting options to a worksheet cell, it leads to significant changes in the internal document model, and the event fires twice. The SpreadsheetControl.ModifiedChanged event indicates that the current document was modified for the first time since it was loaded or last saved, and the SpreadsheetControl.Modified property has been changed. This property can be used by validation or data-saving methods to determine if a workbook has been modified, so that its content is either validated or saved. Saving the current document also raises the SpreadsheetControl.ModifiedChanged event, since the SpreadsheetControl.Modified property reverts to false. Changing the SpreadsheetControl.Modified property value fires the SpreadsheetControl.PropertyChanged event, which occurs each time a property of the SpreadsheetControl class is modified.
Track Modifications Performed via API
Some events can be raised in response to modifications performed in code. The SpreadsheetControl.UnitChanging and SpreadsheetControl.UnitChanged events fire when the document units of measurement have been changed via the SpreadsheetControl.Unit or ISpreadsheetComponent.Unit property. When you use the SpreadsheetControl.ReadOnly property to prohibit or allow document modifications in the SpreadsheetControl, the SpreadsheetControl.ReadOnlyChanged event occurs. Use the SpreadsheetControl.BeforeDispose event to take the necessary steps for saving changes before the SpreadsheetControl instance is removed from memory.
Some events are normally raised only for changes made with the SpreadsheetControl UI (SpreadsheetControl.ActiveSheetChanged, SpreadsheetControl.ColumnsInserted, SpreadsheetControl.ColumnsRemoved, SpreadsheetControl.SelectionChanged, etc.), but you can fire them when modifications are made to a document via an API. To do this, set the WorkbookEventOptions.RaiseOnModificationsViaAPI property to true.