ApplicationState

Cell-based guard that snapshots Excel Application settings before entering a locked-down busy mode and restores them afterwards. Handles ScreenUpdating, DisplayAlerts, Calculation, EnableAnimations, EnableEvents, AutomationSecurity, cursor, and CalculateBeforeSave.

Depends on: ProjectError

Version: 1.0 (2026-02-09)

Factory

create #

Factory returning an initialised interface

Signature:

Public Function Create(Optional ByVal excelApplication As Application) As IApplicationState

Captures the current application state immediately so callers can switch to busy mode without an additional call.

Parameters:

excelApplication: Application. Target application. Defaults to Excel.Application.

Returns: IApplicationState. Ready to use.

Core Logic

apply-busy-state #

Apply the busy state to the target application

Signature:

Private Sub ApplyBusyStateCore(Optional ByVal suppressEvents As Boolean = False, _
                               Optional ByVal calculateOnSave As Boolean = True, _
                               Optional ByVal busyCursor As Long = 0, _
                               Optional ByVal blockSecurity As Boolean = False)

Switches the target Excel Application into a locked-down mode for heavy operations: disables screen updating, alerts, automatic calculation, and optionally suppresses events and blocks automation security. Does nothing when the scope is already busy. On failure the busy flag is cleared and a ProjectError is raised so the caller can attempt recovery.

Parameters:

suppressEvents: Optional Boolean. When True, disables Application.EnableEvents. Defaults to False.
calculateOnSave: Optional Boolean. Value assigned to CalculateBeforeSave. Defaults to True.
busyCursor: Optional Long. Cursor shown while busy. When 0 (default), leaves cursor unchanged.
blockSecurity: Optional Boolean. When True, forces msoAutomationSecurityForceDisable. Defaults to False.

Throws:

ProjectError.ErrorUnexpectedState When the application settings cannot be applied.

refresh-snapshot #

Re-capture the snapshot from the current application state

Signature:

Private Sub RefreshSnapshotCore()

restore #

Restore all captured settings to the application

Signature:

Private Sub RestoreInternal(ByVal silent As Boolean)

Parameters:

silent: Boolean. When True, swallows errors instead of raising them.

Internal members (not exported)

Factory

self #

Self-reference as IApplicationState

Signature:

Public Property Get Self() As IApplicationState

Returns: IApplicationState. Self-reference.

Introspection

application-object #

Application reference currently guarded

Signature:

Public Property Get ApplicationObject() As Application

Returns: Application. The Excel Application instance.

is-busy #

Whether the busy state is currently active

Signature:

Public Property Get IsBusy() As Boolean

Returns: Boolean. True when ApplyBusyState has been invoked without a matching Restore.

has-snapshot #

Whether a snapshot exists and restoration is possible

Signature:

Public Property Get HasSnapshot() As Boolean

Returns: Boolean. True when a snapshot has been captured.

Internal Workflow

bind-application #

Bind a target application

Signature:

Friend Sub BindApplication(ByVal excelApplication As Application)

Parameters:

excelApplication: Application. The Excel Application to guard.

capture-snapshot #

Capture current application settings

Signature:

Friend Sub CaptureSnapshot()

Core Logic

capture-snapshot-core #

Capture all application settings into the snapshot

Signature:

Private Sub CaptureSnapshotCore()

target-application #

Resolve the Excel Application reference

Signature:

Private Function TargetApplication() As Application

Returns: Application. The guarded Application instance.

ensure-snapshot #

Guard that a snapshot exists before proceeding

Signature:

Private Sub EnsureSnapshot(ByVal operationName As String)

Parameters:

operationName: String. Name of the calling operation for error messages.

ensure-not-busy #

Guard that the scope is not busy before proceeding

Signature:

Private Sub EnsureNotBusy(ByVal operationName As String)

Parameters:

operationName: String. Name of the calling operation for error messages.

safe-set-enable-animations #

Set EnableAnimations with graceful fallback on unsupported platforms

Signature:

Private Sub SafeSetEnableAnimations(ByVal target As Application, ByVal value As Boolean)

Parameters:

target: Application. The Excel Application instance.
value: Boolean. The desired EnableAnimations state.

try-read-enable-animations #

Attempt to read EnableAnimations from the target application

Signature:

Private Function TryReadEnableAnimations(ByVal target As Application, _
                                         ByRef value As Boolean) As Boolean

Parameters:

target: Application. The Excel Application instance.
value: Boolean. ByRef. Receives the current EnableAnimations value on success.

Returns: Boolean. True when the property was read successfully.

throw-error #

Raise a typed project error

Signature:

Private Sub ThrowError(ByVal errNumber As ProjectError, ByVal message As String)

Parameters:

errNumber: ProjectError. The error code.
message: String. Descriptive error message.

Used in (23 file(s))