Common Event Scenarios

This page demonstrates common event-driven patterns used in real-world SpreadJS applications.

Each scenario focuses on a practical requirement and shows which event to use and why.

Prevent Switching to Another Sheet

Requirement

Prevent users from switching away from the current sheet unless certain conditions are met (for example, unsaved changes exist).

Event Used

ActiveSheetChanging

Why

This event occurs before the active sheet changes and allows cancellation.

spread.bind(GC.Spread.Sheets.Events.ActiveSheetChanging, function (sender, args) {
    var hasUnsavedChanges = true;

    if (hasUnsavedChanges) {
        if (!confirm("You have unsaved changes. Continue?")) {
            args.cancel = true;
        }
    }
});

Prevent Editing Specific Cells

Requirement

Block editing in restricted rows or columns.

Event Used

EditStarting

Why

Triggered before a cell enters edit mode.

activeSheet.bind(GC.Spread.Sheets.Events.EditStarting, function (sender, args) {
    var restrictedColumn = 0;

    if (args.col === restrictedColumn) {
        args.cancel = true;
    }
});

Validate Input Before Commit

Requirement

Allow editing, but validate the value before committing.

Event Used

EditEnding

Why

Triggered before edit is committed. Provides access to the editor value.

activeSheet.bind(GC.Spread.Sheets.Events.EditEnding, function (sender, args) {
    var value = args.editingText;

    if (isNaN(value)) {
        alert("Only numeric values are allowed.");
        args.cancel = true;
    }
});

Track Data Changes

Requirement

Log or synchronize cell updates with a backend system.

Event Used

RangeChanged or ValueChanged

Why

Triggered after cell data changes.

activeSheet.bind(GC.Spread.Sheets.Events.RangeChanged, function (sender, args) {
    console.log("Changed range:",
        args.row,
        args.col,
        args.rowCount,
        args.colCount
    );
});

Block Row or Column Resizing

Requirement

Prevent users from resizing rows or columns.

Events Used

RowHeightChanging
ColumnWidthChanging

Why

These events occur before size changes and support cancellation.

activeSheet.bind(GC.Spread.Sheets.Events.RowHeightChanging, function (sender, args) {
    args.cancel = true;
});

activeSheet.bind(GC.Spread.Sheets.Events.ColumnWidthChanging, function (sender, args) {
    args.cancel = true;
});

Restrict Sorting Operations

Requirement

Prevent users from sorting certain columns.

Event Used

RangeSorting

Why

Occurs before automatic sorting.

activeSheet.bind(GC.Spread.Sheets.Events.RangeSorting, function (sender, args) {
    var restrictedColumn = 2;

    if (args.col === restrictedColumn) {
        alert("Sorting is not allowed for this column.");
        args.cancel = true;
    }
});

Prevent Deleting Shapes

Requirement

Protect visual elements from being removed.

Event Used

ShapeRemoving

activeSheet.bind(GC.Spread.Sheets.Events.ShapeRemoving, function (sender, args) {
    args.cancel = true;
});

Intercept Drag-and-Drop Operations

Requirement

Control or block drag-and-drop cell movement.

Event Used

DragDropBlock

activeSheet.bind(GC.Spread.Sheets.Events.DragDropBlock, function (sender, args) {
    if (!args.copy) {
        args.cancel = true; // allow copy, block move
    }
});

Detect Cut Operations

Requirement

Warn users before performing cut.

Event Used

ClipboardPasting

spread.bind(GC.Spread.Sheets.Events.ClipboardPasting, function (sender, args) {
    if (args.action === GC.Spread.Sheets.ClipboardActionType.cut) {
        if (!confirm("This is a cut operation. Continue?")) {
            args.cancel = true;
        }
    }
});

Enforce Business Rules in ReportSheet

Requirement

Validate data before submitting changes.

Events Used

ReportSheetDataChanging
ReportSheetRecordsSubmitting

report.bind(GC.Spread.Sheets.Events.ReportSheetDataChanging, function (sender, args) {
    if (args.newValue === null) {
        args.cancel = true;
    }
});