# Events

A tutorial on how to bind code to frequently used events in SpreadJS

## Content

SpreadJS provides a comprehensive event system that allows developers to respond to user interactions, data modifications, structural changes, and advanced workbook operations.
All events are defined in the [GC.Spread.Sheets.Events](/spreadjs/api/classes/GC.Spread.Sheets.Events) class and can be bound to either a Workbook or a Worksheet, depending on the scope of the operation.
This page introduces the event model, binding mechanism, lifecycle patterns, and usage principles used throughout SpreadJS.

## Event Scope

Events in SpreadJS are scoped according to the object that raises them.

### Workbook-Level Events

Workbook events are triggered by operations that affect the workbook as a whole, such as:

* Active sheet changes
* Clipboard operations
* Table structural updates
* Collaboration workflows
* Calculation progress
* Permission changes

These events must be bound to the `Workbook` instance.

### Worksheet-Level Events

Worksheet events are triggered by interactions within a specific sheet, including:

* Cell interaction and selection
* Editing lifecycle
* Value and range changes
* Row and column operations
* Filtering and sorting
* Shape, picture, floating object, and form control updates
* PivotTable and advanced feature operations

These events must be bound to a `Worksheet` instance.
Binding events at the correct scope ensures predictable behavior and avoids unnecessary handlers.

## Binding and Unbinding Events

Use the `bind` method to register an event handler and `unbind` (or `unbindAll`) to remove it.

```javascript
const spread = new GC.Spread.Sheets.Workbook(document.getElementById("ss"));
const sheet = spread.getActiveSheet();
sheet.bind(GC.Spread.Sheets.Events.CellClick, function (sender, args) {
    console.log("Row:", args.row, "Column:", args.col);
});
```

Each handler receives:

* sender – The object that raised the event (Workbook or Worksheet)
* args – An event-specific argument object containing contextual information

To remove a handler:

```javascript
sheet.unbind(GC.Spread.Sheets.Events.CellClick, handler);
sheet.unbindAll(GC.Spread.Sheets.Events.CellClick);
```

## Event Argument Model

While argument properties vary by event type, many follow consistent patterns:

* Location context — `row`, `col`, `sheet`, `sheetName`
* Range context — `cellRange`, `changedCells`
* State indicators — `action`, `isUndo`
* Control flag — `cancel`

Always refer to the API Reference for event-specific argument details.

## Event Lifecycle Patterns

Many SpreadJS events follow consistent lifecycle naming patterns. Understanding these patterns helps you determine when to intercept or respond to an operation.

### 1\. Changing → Changed

Used for structural or state changes.

* Changing — Triggered before the operation is applied. Often cancelable.
* Changed — Triggered after the operation completes.

Example pattern:

* `SheetChanging` → `SheetChanged`
* `ColumnWidthChanging` → `ColumnWidthChanged`

Typical scenarios include:

* Sheet insertion, removal, renaming, or movement
* Row or column property updates
* Filtering and sorting operations
* Table and range modifications

Use Changing events for validation and prevention.
Use Changed events for post-operation processing or synchronization.

### 2\. Starting → Ending → Ended

Used for interaction and editing workflows.

* Starting — Before the process begins
* Ending — Just before completion (often cancelable)
* Ended — After completion

Example pattern:

* `EditStarting`
* `EditEnding`
* `EditEnded`

Use:

* Starting to initialize state
* Ending to validate or cancel
* Ended to process committed results

## Cancelable Events

Some events allow you to prevent the default behavior by setting:

```javascript
args.cancel = true;
```

Cancelable events typically occur in the Changing or Ending stage.
For example:

* Prevent leaving edit mode
* Prevent sheet switching
* Prevent paste operations
* Prevent column resizing

Cancellation must occur during the appropriate pre-action stage (such as `Changing` or `Ending`).
Post-action events (such as `Changed` or `Ended`) cannot be canceled.
Cancelable events are typically used to:

* Prevent sheet switching
* Block invalid edits
* Restrict resizing operations
* Intercept paste actions
* Enforce business rules

## Event Categories

The SpreadJS event system spans multiple functional areas, including:

* Cell interaction and selection
* Editing lifecycle
* Data and structural changes
* Filtering, sorting, grouping, and tables
* Sheet and workbook lifecycle
* Clipboard integration
* Shapes, pictures, floating objects, and form controls
* PivotTable, ReportSheet, and TableSheet operations
* Calculation and collaboration workflows
* Permission and view-related operations

This structure allows developers to integrate SpreadJS into complex application logic while maintaining fine-grained control over user actions and system behavior.
Detailed event definitions and parameter specifications are available in the API Reference under: [GC.Spread.Sheets.Events](/spreadjs/api/classes/GC.Spread.Sheets.Events).

## Usage Guidelines

When implementing event logic:

* Bind events at the correct scope (Workbook vs Worksheet).
* Use pre-action events for validation and cancellation.
* Use post-action events for logging and synchronization.
* Avoid heavy processing inside frequently triggered events (such as selection or scrolling).
* Remove handlers when disposing or recreating sheets to prevent unintended behavior.

The following sections organize events by functional category and provide focused guidance and examples for common development scenarios.