IEventSetup

Defines the public contract for the EventSetup class, exposing methods to handle workbook-level setup events (open, activate, change), manage setup worksheet rows, sort tables, recalculate analysis helpers, and retrieve values from analysis-related ListObjects.

Depends on: IPasswords, BetterArray, IUpdatedValues, IDropdownLists, ILLdictionary, ILLChoices, ILLExport, IAnalysis, ISetupTranslationsTable

Lifecycle

Configure #

Configure the service with its host workbook context.

Signature:

Public Sub Configure(ByVal hostBook As Workbook)

Binds the service to a host workbook and resets all cached helpers. Must be called once before any event handler or row operation.

Parameters:

  • hostBook: Workbook. The workbook providing setup worksheets and infrastructure.

OnWorkbookOpen #

React to workbook open notifications.

Signature:

Public Sub OnWorkbookOpen()

Switches update watcher tags to "yes", resets the translation counter, disables stale value formatting, and applies the protection matrix.

Workbook events

OnSheetActivate #

Handle worksheet activation events.

Signature:

Public Sub OnSheetActivate(ByVal sh As Worksheet)

Invalidates relevant ribbon controls and refreshes analysis dropdowns when the Analysis sheet becomes active.

Parameters:

  • sh: Worksheet. The worksheet that became active.

OnSheetChange #

Handle worksheet change events fired by Excel.

Signature:

Public Sub OnSheetChange(ByVal sh As Worksheet, ByVal target As Range)

Forwards the change to the update watcher, processes choices label recalculation when the Choices sheet changes, and manages analysis dropdowns and calculations when the Analysis sheet changes.

Parameters:

  • sh: Worksheet. The worksheet raising the change event.
  • target: Range. The edited cells.
Auxiliary operations

RecalculateAnalysis #

Recalculate analysis tables in response to structural edits.

Signature:

Public Sub RecalculateAnalysis()

Forces recalculation of all cached analysis tables (time-series, graph, spatio-temporal, spatio-temporal specifications). Call after structural changes to analysis ListObjects.

UpdateAnalysisDropdowns #

Refresh cached dropdowns and related analysis helpers.

Signature:

Public Sub UpdateAnalysisDropdowns(Optional ByVal forceUpdate As Boolean = False)

Refreshes dropdown lists used by the Analysis sheet based on update watcher flags. When forceUpdate is True, rebuilds all dropdowns regardless of flags.

Parameters:

  • forceUpdate: Optional Boolean. When True, forces a full refresh regardless of update tags. Defaults to False.

ResetTranslationCounter #

Reset the translation update counter stored in hidden names.

Signature:

Public Sub ResetTranslationCounter()

Resets the hidden name counter that tracks translation updates back to zero. Called on workbook open and after translation table management.

Row operations

ManageRows #

Manage setup worksheet rows using cached helpers.

Signature:

Public Sub ManageRows(ByVal sheetName As String, Optional ByVal del As Boolean = False)

Delegates to the appropriate domain manager (dictionary, choices, analysis, exports) to add or remove rows, handling sheet protection around each operation.

Parameters:

  • sheetName: String. Worksheet name to process.
  • del: Optional Boolean. When True, removes rows instead of adding them. Defaults to False.

InsertRows #

Insert rows relative to a selection for supported setup sheets.

Signature:

Public Sub InsertRows(ByVal sheetName As String, _
                      ByVal targetCell As Range, _
                      Optional ByVal insertShift As Boolean = False)

Delegates to the appropriate domain manager to insert rows at the position indicated by targetCell. Handles sheet protection around the operation. For the Analysis sheet, insertShift is always forced to True.

Parameters:

  • sheetName: String. Worksheet name identifying which helper should process the insertion.
  • targetCell: Range. The worksheet selection to mirror.
  • insertShift: Optional Boolean. Controls whether worksheet rows should be inserted to preserve stacked tables. Defaults to False.

DeleteRows #

Delete rows relative to a selection for supported setup sheets.

Signature:

Public Sub DeleteRows(ByVal sheetName As String, _
                      ByVal targetCell As Range, _
                      Optional ByVal forceShift As Boolean = False)

Delegates to the appropriate domain manager to delete rows at the position indicated by targetCell. Handles sheet protection around the operation. For the Analysis sheet, forceShift is always forced to True.

Parameters:

  • sheetName: String. Worksheet name identifying which helper should process the deletion.
  • targetCell: Range. The worksheet selection to remove.
  • forceShift: Optional Boolean. Controls whether worksheet rows should be deleted. Defaults to False.

SortTables #

Sort setup worksheets leveraging cached managers.

Signature:

Public Sub SortTables(ByVal sheetName As String)

Delegates to the appropriate domain manager to sort the worksheet tables. Handles sheet protection around the operation. For exports, also unlocks the dictionary sheet because sort results may propagate.

Parameters:

  • sheetName: String. Worksheet name to sort.

BuildTimeSeriesHeader #

Compose the time-series header displayed in analysis tables.

Signature:

Public Function BuildTimeSeriesHeader(ByVal timeVar As String, _
                                      ByVal groupVar As String, _
                                      ByVal sumLabel As String) As String

Composes a display header by concatenating the summary label, time variable label, and group variable label separated by a horizontal-rule character.

Parameters:

  • timeVar: String. Time variable name.
  • groupVar: String. Group variable name.
  • sumLabel: String. Summary label prefix.

Returns: String. The composed header text.

AnalysisGraphValue #

Retrieve a value from the analysis graph label table.

Signature:

Public Function AnalysisGraphValue(ByVal graphTitle As String, _
                                   Optional ByVal graphCol As String = "Graph ID") As String

Looks up a cell value from the graph time-series label table using graphTitle as the row key and graphCol as the column header.

Parameters:

  • graphTitle: String. Graph title used as the row key.
  • graphCol: Optional String. Column to read. Defaults to "Graph ID".

Returns: String. The retrieved value, or empty.

AnalysisTimeSeriesValue #

Retrieve a value from the analysis time-series table.

Signature:

Public Function AnalysisTimeSeriesValue(ByVal seriesTitle As String, _
                                        Optional ByVal tsColumn As String = "Series ID") As String

Looks up a cell value from the time-series data table using seriesTitle as the row key and tsColumn as the column header.

Parameters:

  • seriesTitle: String. Series title used as the row key.
  • tsColumn: Optional String. Column to read. Defaults to "Series ID".

Returns: String. The retrieved value, or empty.

SpatioTemporalSpecValue #

Retrieve a value from the spatio-temporal specifications table.

Signature:

Public Function SpatioTemporalSpecValue(ByVal sectionName As String, _
                                        Optional ByVal specColumn As String = "N geo max") As String

Looks up a cell value from the spatio-temporal specifications table using sectionName as the row key and specColumn as the column header.

Parameters:

  • sectionName: String. Section name used as the row key.
  • specColumn: Optional String. Column to read. Defaults to "N geo max".

Returns: String. The retrieved value, or empty.

ResetCaches #

Clear cached resources so they are lazily rebuilt on demand.

Signature:

Public Sub ResetCaches()

Clears all lazily-cached domain managers and table wrappers so they are rebuilt from scratch on the next access.