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 #

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

ApplyBusyStateCore #

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.

RefreshSnapshotCore #

refresh-snapshot

Re-capture the snapshot from the current application state

Signature:

Private Sub RefreshSnapshotCore()

RestoreInternal #

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

Self-reference as IApplicationState

Signature:

Public Property Get Self() As IApplicationState

Returns: IApplicationState. Self-reference.

Introspection

ApplicationObject #

application-object

Application reference currently guarded

Signature:

Public Property Get ApplicationObject() As Application

Returns: Application. The Excel Application instance.

IsBusy #

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.

HasSnapshot #

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

BindApplication #

bind-application

Bind a target application

Signature:

Friend Sub BindApplication(ByVal excelApplication As Application)

Parameters:

excelApplication: Application. The Excel Application to guard.

CaptureSnapshot #

capture-snapshot

Capture current application settings

Signature:

Friend Sub CaptureSnapshot()

Core Logic

CaptureSnapshotCore #

capture-snapshot-core

Capture all application settings into the snapshot

Signature:

Private Sub CaptureSnapshotCore()

TargetApplication #

target-application

Resolve the Excel Application reference

Signature:

Private Function TargetApplication() As Application

Returns: Application. The guarded Application instance.

EnsureSnapshot #

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.

EnsureNotBusy #

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.

SafeSetEnableAnimations #

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.

TryReadEnableAnimations #

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.

ThrowError #

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