IHiddenNames

Defines the public contract for the HiddenNames class, exposing hidden worksheet/workbook-level name-value storage with typed serialization, metadata caching, discovery, and cross-scope import/export operations.

Introspection

Sheet #

Target worksheet reference

Signature:

Public Property Get Sheet() As Worksheet

Properties exposing the host and name existence checks. Returns the worksheet bound to this HiddenNames instance.

Returns: Worksheet. The host worksheet.

HasName #

Check whether a hidden name exists

Signature:

Public Function HasName(ByVal nameId As String) As Boolean

Determines whether the specified name is defined on the host scope.

Parameters:

nameId: String. Identifier of the hidden name.

Returns: Boolean. True when the name exists.

Hidden Name Management

EnsureName #

Ensure a hidden name exists with the provided default

Signature:

Public Function EnsureName(ByVal nameId As String, _
                           ByVal initialValue As Variant, _
                           Optional ByVal valueType As Byte = HiddenNameTypeVariant) As Name

Methods for creating, reading, updating, and removing hidden names. Creates the name with the initial value if it does not yet exist. Returns the cached Name definition so callers can retain a reference.

Parameters:

nameId: String. Identifier of the hidden name (scope-level).
initialValue: Variant. Value written on first creation.
valueType: Optional Byte. Type annotation guiding serialization. Defaults to HiddenNameTypeVariant.

Returns: Name. The Name definition after ensuring existence.

Value #

Retrieve a hidden value without coercion

Signature:

Public Function Value(ByVal nameId As String, _
                       Optional ByVal defaultValue As Variant) As Variant

Returns the stored value for the specified name. When the name is absent and a default is provided, returns the default; otherwise raises an error.

Parameters:

nameId: String. Identifier of the hidden name.
defaultValue: Optional Variant. Fallback when the name is absent.

Returns: Variant. The stored value, or the default.

SetValue #

Update the stored value using the cached metadata

Signature:

Public Sub SetValue(ByVal nameId As String, ByVal value As Variant)

Writes a new value to an existing hidden name. Raises an error when the name does not exist.

Parameters:

nameId: String. Identifier of the hidden name to update.
value: Variant. The new value to persist.

ValueAsString #

Retrieve the hidden value coerced to String

Signature:

Public Function ValueAsString(ByVal nameId As String, _
                              Optional ByVal defaultValue As String = vbNullString) As String

Parameters:

nameId: String. Identifier of the hidden name.
defaultValue: Optional String. Fallback when absent. Defaults to vbNullString.

Returns: String. The coerced value.

ValueAsBoolean #

Retrieve the hidden value coerced to Boolean

Signature:

Public Function ValueAsBoolean(ByVal nameId As String, _
                               Optional ByVal defaultValue As Boolean = False) As Boolean

Parameters:

nameId: String. Identifier of the hidden name.
defaultValue: Optional Boolean. Fallback when absent. Defaults to False.

Returns: Boolean. The coerced value.

ValueAsLong #

Retrieve the hidden value coerced to Long

Signature:

Public Function ValueAsLong(ByVal nameId As String, _
                            Optional ByVal defaultValue As Long = 0) As Long

Parameters:

nameId: String. Identifier of the hidden name.
defaultValue: Optional Long. Fallback when absent. Defaults to 0.

Returns: Long. The coerced value.

RemoveName #

Remove a hidden name definition

Signature:

Public Sub RemoveName(ByVal nameId As String)

Deletes the hidden name from the host scope and removes its metadata cache entry.

Parameters:

nameId: String. Identifier of the hidden name to remove.

Discovery

ListNames #

Enumerate recorded hidden names

Signature:

Public Function ListNames(Optional ByVal prefix As String = vbNullString) As BetterArray

Enumerate tracked hidden names. Returns metadata for all tracked hidden names, optionally filtered by a case-insensitive prefix.

Parameters:

prefix: Optional String. Prefix filter. Defaults to vbNullString (all names).

Returns: BetterArray. Array of metadata records: Array(nameId, HiddenNameValueType, lastUpdated).

Synchronisation

ExportNames #

Export all tracked hidden names to another worksheet

Signature:

Public Sub ExportNames(ByVal targetSh As Worksheet, _
                       Optional ByVal prefix As String = vbNullString)

Import/export operations across worksheets and workbooks.

Parameters:

targetSh: Worksheet. Destination worksheet.
prefix: Optional String. Prefix filter. Defaults to vbNullString.

ImportNames #

Import hidden names from another worksheet

Signature:

Public Sub ImportNames(ByVal sourceSh As Worksheet, _
                       Optional ByVal prefix As String = vbNullString, _
                       Optional ByVal overwriteExisting As Boolean = True)

Parameters:

sourceSh: Worksheet. Source worksheet providing the names.
prefix: Optional String. Prefix filter. Defaults to vbNullString.
overwriteExisting: Optional Boolean. When False, existing values are preserved. Defaults to True.

ExportNamesToWorkbook #

Export tracked names to another workbook scope

Signature:

Public Sub ExportNamesToWorkbook(ByVal targetWb As Workbook, _
                                 Optional ByVal prefix As String = vbNullString)

Parameters:

targetWb: Workbook. Destination workbook.
prefix: Optional String. Prefix filter. Defaults to vbNullString.

ImportNamesFromWorkbook #

Import hidden names from another workbook scope

Signature:

Public Sub ImportNamesFromWorkbook(ByVal sourceWb As Workbook, _
                                   Optional ByVal prefix As String = vbNullString, _
                                   Optional ByVal overwriteExisting As Boolean = True)

Parameters:

sourceWb: Workbook. Source workbook providing the names.
prefix: Optional String. Prefix filter. Defaults to vbNullString.
overwriteExisting: Optional Boolean. When False, existing values are preserved. Defaults to True.

SetListObjectHeader #

Create a workbook-level hidden name referencing a ListObject header

Signature:

Public Sub SetListObjectHeader(ByVal nameId As String, _
                               ByVal listObject As ListObject, _
                               ByVal headerName As String)

Adds or replaces a workbook-scoped hidden name whose RefersTo formula points at the specified ListObject column.

Parameters:

nameId: String. Identifier of the workbook name to assign.
listObject: ListObject. Target ListObject hosting the header.
headerName: String. Caption of the header column to reference.