Linelist

Facade for the output linelist workbook. This class orchestrates the full lifecycle of creating, populating, saving, and error-managing the .xlsb workbook that end-users receive. It lazily creates the output workbook (or opens a template), adds temporary and permanent worksheets, exports specifications, prepares hidden names and ListObjects, formats the admin sheet, transfers all VBA code components, and finally saves the workbook with password protection. The class uses VB_Creatable = True so that factory consumers create instances via New Linelist rather than With New Linelist.

Depends on: ILinelistSpecs, ILLdictionary, ITranslationObject, IPasswords, ILLFormat, ITemporaryRepos, ICodeTransfer, IHiddenNames, IButtons, IDropdownLists, ICustomPivotTable, DropdownLists, CustomPivotTable, TemporaryRepos, HiddenNames, Buttons, CodeTransfer, BetterArray

Version: 1.0 (2026-02-09)

Factory

create #

Instantiate a Linelist facade bound to specifications

Signature:

Public Function Create(ByVal specs As ILinelistSpecs) As ILinelist

Instance creation via VB_Creatable = True factory pattern. Validates that the supplied specifications object is not Nothing, creates a new Linelist instance via New Linelist, binds the specifications through the Friend property, and returns an ILinelist interface reference.

Parameters:

specs: ILinelistSpecs. The linelist specifications providing dictionary, translations, design format, passwords, and all other setup data required to build the output workbook.

Returns: ILinelist. A ready-to-use linelist facade.

Throws:

ProjectError.ObjectNotInitialized When specs is Nothing.

Public properties

linelist-data #

Specifications backing this linelist

Signature:

Public Property Get LinelistData() As ILinelistSpecs

Worksheet resolution and collaborator accessors exposed through the ILinelist contract. Returns the ILinelistSpecs instance that was supplied during factory construction, providing access to dictionary, choices, translations, and all other setup data.

Returns: ILinelistSpecs. The linelist specifications.

dictionary #

Dictionary from the specifications

Signature:

Public Property Get Dictionary() As ILLdictionary

Convenience accessor that delegates to specs.Dictionary, avoiding the extra indirection at call sites.

Returns: ILLdictionary. The linelist dictionary.

wksh #

Worksheet from the output workbook by name

Signature:

Public Property Get Wksh(ByVal sheetName As String) As Worksheet

Returns the worksheet matching the given name from the output workbook. Delegates to ResolveWksh with scope 1 (no prefix). Raises an error if the sheet does not exist.

Parameters:

sheetName: String. The worksheet name to look up.

Returns: Worksheet. The resolved worksheet.

Throws:

ProjectError.InvalidArgument When the sheet does not exist.

print-wksh #

Printed companion worksheet by base name

Signature:

Public Property Get PrintWksh(ByVal sheetName As String) As Worksheet

Returns the printed companion worksheet (prefixed with "print_") from the output workbook. Used for HList sheets that have a printable duplicate. Delegates to ResolveWksh with scope 2.

Parameters:

sheetName: String. The base sheet name (without the print_ prefix).

Returns: Worksheet. The printed companion worksheet.

Throws:

ProjectError.InvalidArgument When the sheet does not exist.

crf-wksh #

CRF companion worksheet by base name

Signature:

Public Property Get CRFWksh(ByVal sheetName As String) As Worksheet

Returns the CRF companion worksheet (prefixed with "crf_") from the output workbook. Used for case report form layouts. Delegates to ResolveWksh with scope 3.

Parameters:

sheetName: String. The base sheet name (without the crf_ prefix).

Returns: Worksheet. The CRF companion worksheet.

Throws:

ProjectError.InvalidArgument When the sheet does not exist.

Dropdown lists manager for the output workbook

Signature:

Public Property Get Dropdown(Optional ByVal scope As Byte = 1) As IDropdownLists

Returns an IDropdownLists instance backed by the appropriate list sheet. Scope 1 uses the temporary dropdown_lists__ sheet with "dropdown_" prefix; scope 2 uses the custom choice sheet with no prefix.

Parameters:

scope: Optional Byte. 1 = standard dropdowns, 2 = custom choice dropdowns. Defaults to 1.

Returns: IDropdownLists. The dropdown lists manager.

pivots #

Pivot tables manager for the output workbook

Signature:

Public Property Get Pivots() As ICustomPivotTable

Returns an ICustomPivotTable instance backed by the translated custom pivot table sheet in the output workbook.

Returns: ICustomPivotTable. The pivot tables manager.

sheet-exists #

Check whether a sheet exists in the output workbook

Signature:

Public Function SheetExists(ByVal sheetName As String) As Boolean

Tests whether a worksheet with the given name exists in the output workbook without raising an error. Uses On Error Resume Next internally.

Parameters:

sheetName: String. The worksheet name to test.

Returns: Boolean. True when the sheet exists, False otherwise.

add-output-sheet #

Add a worksheet to the output workbook

Signature:

Public Sub AddOutputSheet(ByVal sheetName As String, _
                          Optional ByVal Hide As Long = xlSheetVeryHidden, _
                          Optional ByVal sheetScope As Byte = 1, _
                          Optional ByVal beforeSheet As String = vbNullString)

Creates a new worksheet in the output workbook with the given name, applying an optional scope prefix ("print_" or "crf_") and visibility setting. The sheet name is truncated to 30 characters (Excel limit for sheet names). When beforeSheet is supplied and that sheet exists in the output workbook, the new sheet is inserted immediately before it; otherwise the sheet is appended at the default position.

Parameters:

sheetName: String. The base name for the new worksheet.
Hide: Optional Long. Excel visibility constant. Defaults to xlSheetVeryHidden.
sheetScope: Optional Byte. 1 = no prefix, 2 = print_ prefix, 3 = crf_ prefix. Defaults to 1.
beforeSheet: Optional String. Name of an existing worksheet to insert before. Defaults to vbNullString (append at default position).

Lifecycle

prepare #

Build the full linelist output workbook from specifications

Signature:

Public Sub Prepare()

Build, save, and error-manage the output workbook. Orchestrates the complete linelist creation process:

Initialises the temporary repository for code transfer files.
Lazily creates the output workbook (or opens a template).
Optionally shows the instruction sheet for template workbooks.
Adds six temporary sheets (single, list, analysis, import, spatial, show/hide) and prepares them with hidden names and ListObjects.
Exports specifications to the workbook via ILinelistSpecs.Export.
Adds analysis and custom sheets in reversed dictionary order.
Adds data entry sheets from the dictionary's unique sheet names.
Repositions the instruction sheet.
Adds and formats the admin sheet (non-template only).
Deletes the initial default sheet.
Transfers all VBA code via CodeTransfer (classes, modules, forms, workbook code).

save-ll #

Save the output workbook as .xlsb with password protection

Signature:

Public Sub SaveLL()

Saves the output workbook in .xlsb format with the configured password, protects the workbook structure via IPasswords.Protect, activates an appropriate visible sheet (admin or instruction), closes the workbook, and cleans up temporary files via ITemporaryRepos.Reset.

error-manage #

Display an error dialog for incomplete linelist operations

Signature:

Public Sub ErrorManage(Optional ByVal textMessage As String = vbNullString)

Shows a message box with the error details and asks the user whether they want to view the incomplete linelist workbook or close it without saving. If the user chooses Yes the workbook's Application is made visible; otherwise the workbook is closed without saving.

Parameters:

textMessage: Optional String. Error description to display. Defaults to vbNullString.

Internal members (not exported)

Bindings

bin-specs #

Bind the linelist specifications to this instance

Signature:

Friend Property Set BinSpecs(ByVal value As ILinelistSpecs)

Friend setters used by the factory to inject dependencies. Called by Create to inject the ILinelistSpecs dependency into the backing UDT. Exposed as Friend to prevent external callers from resetting specifications after construction.

Parameters:

value: ILinelistSpecs. The specifications to bind.

Private — Workbook management

output-wkb #

Return the output workbook from LinelistSpecs

Signature:

Private Property Get OutputWkb() As Workbook

Internal helpers for lazily creating and managing the output workbook and suppressing UI updates during batch operations. On first access, retrieves the output workbook that LinelistSpecs.Prepare created and caches it locally. Also records the name of the initial default sheet so Prepare can delete it later.

Returns: Workbook. The output workbook.

resolve-wksh #

Resolve a worksheet from the output workbook with scope prefix

Signature:

Private Sub ResolveWksh(ByVal sheetName As String, ByVal sheetScope As Byte, _
                        ByRef result As Worksheet)

Builds the actual sheet name by prepending the appropriate prefix based on sheetScope (1 = none, 2 = "print_", 3 = "crf_"), verifies the sheet exists, and returns a reference through the ByRef result parameter.

Parameters:

sheetName: String. The base sheet name.
sheetScope: Byte. 1 = no prefix, 2 = print_ prefix, 3 = crf_ prefix.
result: Worksheet. ByRef output parameter receiving the resolved sheet.

Throws:

ProjectError.InvalidArgument When the sheet does not exist.

Private — Prepare helpers

prepare-temporary-sheets #

Set up hidden names and ListObjects on temporary sheets

Signature:

Private Sub PrepareTemporarySheets()

Internal routines called by Prepare to set up temporary sheets, the admin sheet, and code transfer. Performs three setup tasks on the output workbook:

Creates workbook-level hidden names for global flags (update list auto, import done, geo update manual, show all optionals, export init, number of exports, epi week start) — replaces the removed TemporarySheetUpdates.
Creates four ListObjects on the import report sheet for tracking sheets and variables not imported/found.
Creates twelve ListObjects on the analysis sheet (tab_ids, graph_ids, graph_formats for each of the four analysis scopes: uba, ts, sp, sptemp) plus four worksheet-level hidden names storing the translated analysis sheet names.

initialise-workbook-names #

Set language HiddenNames on the output workbook

Signature:

Private Sub InitialiseWorkbookNames()

Creates workbook-level HiddenNames for the dictionary language (RNG_DictionaryLanguage) and interface language (RNG_LLLanguageCode) on the output workbook. These are required by LLTranslation.TransObject to resolve the correct language code for translation lookups.

initialise-translation-names #

Propagate language HiddenNames to the translation worksheet and create translated names

Signature:

Private Sub InitialiseTranslationNames()

Calls InitialiseSheetNames on the LLTranslation instance to store dictionary and interface language codes as worksheet-level HiddenNames on the translation sheet. Then calls InitialiseHiddenNames to create all RNG_* translated message/sheet names on the output workbook.

prepare-admin #

Format the admin sheet and add Advanced/Export buttons

Signature:

Private Sub PrepareAdmin()

Applies the linelist design format to the admin sheet, then creates two large-scope buttons (Advanced and Export) with translated labels. After placing the buttons, re-suppresses UI updates and activates the admin sheet. Finally protects the active sheet via IPasswords.Protect with the "_active" scope marker.

Remarks:

The trads object is switched to TranslationOfShapes scope to fetch shape-specific translated labels for the buttons.

transfer-all-code #

Transfer all VBA code components to the output workbook

Signature:

Private Sub TransferAllCode(ByVal codeTransfer As ICodeTransfer)

Uses the supplied ICodeTransfer to copy VBA components from the setup workbook to the output workbook in five phases:

Transfers 49 class modules (interface+implementation pairs for DataSheet, LLExport, LLChoices, LLdictionary, LLGeo, Passwords, LLSheets, LLTranslation, OSFiles, TranslationObject, LLVariables, LLSpatial, DropdownLists, ShowHideManager, CustomTable, LLExporter, LLImporter, Graphs, AnaTabIds, ExportButton, HiddenNames, EventLinelist, ApplicationState, plus BetterArray and Checking).
Transfers 7 standard modules (LinelistCustomFunctions, GeoModule, LinelistEventsManager, EventsLinelistButtons, FormLogicAdvanced, FormLogicExportMig, FormLogicExport). For template workbooks, copies the ribbon module text (EventsLinelistRibbon); otherwise transfers it as a new module.
Transfers 9 user forms (F_Advanced, F_Export, F_ExportMig, F_Geo, F_ImportRep, F_ShowHideLL, F_ShowHidePrint, F_ShowVarLabels, F_EpiWeek).
Transfers the workbook code module (EventLinelistWorkbook).

Parameters:

codeTransfer: ICodeTransfer. The code transfer engine.

Private — Error handling

throw-error #

Raise a project error with class context

Signature:

Private Sub ThrowError(ByVal errNumber As Long, ByVal errorMessage As String)

Centralised error-raising helper. Wraps Err.Raise with CLASS_NAME as the source, providing consistent error attribution across all methods in this class.

Parameters:

errNumber: Long. The ProjectError constant to raise.
errorMessage: String. Descriptive message for the error.

ILinelist implementation

ILinelist_Wksh #

Signature:

Private Property Get ILinelist_Wksh(ByVal sheetName As String) As Worksheet

Delegated members satisfying the ILinelist contract. All members forward to their Public counterparts above.

Used in (18 file(s))

Linelist

create #

linelist-data #

dictionary #

wksh #

print-wksh #

crf-wksh #

dropdown #

pivots #

sheet-exists #

add-output-sheet #

prepare #

save-ll #

error-manage #

Bindings

bin-specs #

Private — Workbook management

output-wkb #

resolve-wksh #

Private — Prepare helpers

prepare-temporary-sheets #

initialise-workbook-names #

initialise-translation-names #

prepare-admin #

transfer-all-code #

Private — Error handling

throw-error #

ILinelist implementation

ILinelist_Wksh #