# Attributes
{: .no_toc }

An attribute, written in square brackets, gives the compiler an instruction or annotates a form, module, class, type, enumeration, declaration or procedure.

Attributes have two major functions: 

- they can act as instructions to compiler to influence how code is generated, or 
- to annotate Forms, Modules, Classes, Types, Enums, Declares, and [procedures](/tB/Gloss.md#procedure) i.e. Subs/Functions/Properties. 

Previously in VBx, these attributes, such as the procedure description, hidden, default member, and others, were set via hidden text the IDE's editor didn't show you, configured via the Procedure Attributes dialog or some other places. In tB, these are all visible in the code editor. The legacy ones from VBx are supported for compatibility, but new attributes use the following syntax:   
`[Attribute]` or `[Attribute(value)]`

In attributes that take an optional boolean argument, the value of the argument is taken to be **True** if no value is provided. This does not mean that the default value of the attribute is True, just that if the attribute is specified within the braces with no value, its value will be set to True. Different boolean-valued attributes have different default values. Those values apply unless the user has explicitly provided the attribute.

Multiple attributes can be specified in the same square braces, separated by comma:   
`[Attribute1, Attribute2(param), Attribute3]`

---

The available attributes are listed below in alphabetic order. Not every attribute applies to every language element. The applicability of each attribute is given below its syntax. Many attributes are refused where they do not apply, with either TB5155, *This attribute is not supported in this context*, or TB5182, *Syntax error. No handler for this symbol*. The compiler accepts others there and ignores them, so a build with no error does not show that an attribute does anything at that place. The `Applicable to:` line lists where an attribute has its effect.
* TOC
{:toc}
---

## AllowUnpopulatedVtableEntry
{: #allowunpopulatedvtableentry index="TB5260" }

Syntax: **[AllowUnpopulatedVtableEntry]**

Applicable to: [procedure](/tB/Gloss.md#procedure) prototype in an [**Interface**](/tB/Core/Interface.md), [procedure](/tB/Gloss.md#procedure) in a [**Class**](/tB/Core/Class.md)

Marks a prototype that a class implementing the interface is not obliged to supply.

The twinBASIC packages use it to add members to an interface without breaking code written against an earlier revision of it. `ItbHostEventsV2` extends `ItbHostEventsV1` and adds one such prototype; `ItbHostEventsV3` extends that and adds another. An addin that implements only the **V1** members still satisfies **V3**.

On a **Public** procedure of a **Class**, it does the same for a class that [**Implements**](/tB/Core/Implements.md) that class: the member may be left out, where otherwise the build fails with TB5260, *Missing implementation of member ...*, on the name after **Implements**. On a property it covers only the accessor it is written on, so a **Property Get** and its **Property Let** each need it.

## AppObject  (optional Bool)
{: #appobject }

Syntax: **[AppObject** [ **( True** \| **False )** ] **]**

Applicable to: [**CoClass**](/tB/Core/CoClass.md), [**Class**](/tB/Core/Class.md)

Legacy VB attribute: *VB_GlobalNameSpace*

Indicates the class is part of the global namespace. You should not include this attribute without a full understanding of the meaning. The **Global** class is an AppObject.

On a **Class**, the members of the class can be called by their bare names anywhere in the project. Those calls all reach one instance of the class, which is not the same as an instance created with [**New**](/tB/Core/New.md). In an ActiveX build the class is marked `appobject` in the type library, so a client sees its members as global names too.

For more details, see [this VBA documentation page](https://learn.microsoft.com/en-us/openspecs/microsoft_general_purpose_programming_languages/ms-vbal/189fb41b-cc3a-4999-a6d2-ba89f72d2870).

## ArrayBoundsChecks  (optional Bool)
{: #arrayboundschecks }

Syntax: **[ArrayBoundsChecks** [ **( True** \| **False )** ] **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**Module**](/tB/Core/Module.md), [procedure](/tB/Gloss.md#procedure)

Disables or enables array element access bounds checking within the scope of a class, module, or a single procedure/method. Used on performance-critical routines. **ArrayBoundsChecks(False)** turns the check off. **ArrayBoundsChecks(True)** turns it back on where the project setting [**Disable Array Bounds Checks**](/tB/IDE/Project-Settings.md#disable-array-bounds-checks) has turned it off for the whole project.

## BindOnlyIfNoArguments  (optional Bool)
{: #bindonlyifnoarguments index_also="TB5030" }

Syntax: **[BindOnlyIfNoArguments** [ **( True** \| **False )** ] **]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md), variable in a [**Module**](/tB/Core/Module.md), variable in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure)

Only binds this name to a callsite when no arguments are present. Normally false, but see below for an exception.

This attribute resolves the cases where compiler's special treatment of certain procedure names conflicts with a procedure of the same name that shouldn't be treated specially. This currently affects procedures named `Left`. Such procedures get an implicit `[BindOnlyIfNoArguments(True)]` assigned by the compiler. If the user wants to have a procedure of this name, it should include `[BindOnlyIfNoArguments(False)]`.

A **Declare** takes the attribute as a procedure does, and a **Declare** named `Left` gets the implicit one too. On a variable named like a built-in procedure, a call with arguments binds to the built-in procedure, where it would otherwise be error TB5030, *Unexpected call arguments*.

## BindOnlyIfStringSuffix  (optional Bool)
{: #bindonlyifstringsuffix }

Syntax: **[BindOnlyIfStringSuffix** [ **( True** \| **False )** ] **]**

Applicable to: [procedure](/tB/Gloss.md#procedure)

## ClassId  (String)
{: #classid }

Syntax: **[ClassId("** 00000000-0000-0000-0000-000000000000 **")]**

Applicable to:  [**Class**](/tB/Core/Class.md)

Assigns a COM CLSID to a class. For details, [see this COM documentation page](https://learn.microsoft.com/en-us/windows/win32/com/com-class-objects-and-clsids).

## ClassInterface
{: #classinterface }

twinBASIC doesn't supports this attribute directly. It supports its values under different names. See:

* [DualInterface](#dualinterface)
* [DispInterface](#dispinterface)


## CoClassCustomConstructor  (String)
{: #coclasscustomconstructor }

Syntax: **[CoClassCustomConstructor("** fully qualified path to factory method **")]**

Applicable to: [**CoClass**](/tB/Core/CoClass.md)

Allows custom logic for creating and returning a new instance of the coclass' implementation.

Example:

```tb check_build
[CoClassId("7980D953-10BF-478C-93BB-DD0093315D96")]
[CoClassCustomConstructor("FooFactory.CreateFoo")]
[COMCreatable(True)]
Public CoClass Foo
   ' ...
End CoClass
```

For an overview of coclasses in tB, see [Defining coclasses](/Features/Language/Interfaces-CoClasses.md#defining-coclasses).

## CoClassId  (String)
{: #coclassid }

Syntax: **[CoClassId("** 00000000-0000-0000-0000-000000000000 **")]**

Applicable to: [**CoClass**](/tB/Core/CoClass.md)

In addition to interfaces, twinBASIC also allows defining coclasses -- creatable classes that implement one or more defined interfaces. Like interfaces, these too must be in .twin files and not legacy .bas/.cls files, and must appear prior to the `Class` or `Module` statement. The generic form is:

```tb inert=skeleton
[CoClassId("00000000-0000-0000-0000-000000000000")]
*<attributes>*
CoClass <name>
    [Default] Interface <interface name>
    *[Default, Source] Interface <event interface name>*
    *<additional Interface items>*
End CoClass
```

The methods are [procedures](/tB/Gloss.md#procedure).

For an overview of coclasses in tB, see [Defining coclasses](/Features/Language/Interfaces-CoClasses.md#defining-coclasses).

## COMControl  (optional Bool)
{: #comcontrol }

Syntax: **[COMControl** [ **( True** \| **False )** ] **]**

Applicable to: [**Interface**](/tB/Core/Interface.md), [**Class**](/tB/Core/Class.md)

On a **Class**, it marks the class as an ActiveX control (the `control` flag of its coclass in the type library). The compiler then warns, with TB0013, about a class that has no [InterfaceId](#interfaceid) or no [EventInterfaceId](#eventinterfaceid) attribute: a host may cache those identifiers, so they should be fixed rather than generated anew by each build.

## COMCreatable  (optional Bool)
{: #comcreatable index_also="TB5121; TB5135" }

Syntax: **[COMCreatable** [ **( True** \| **False )** ] **]**

Applicable to:  [**Class**](/tB/Core/Class.md), [**CoClass**](/tB/Core/CoClass.md)

Indicates whether the class can be created through COM. It does not govern [**New**](/tB/Core/New.md) inside the project: a `[COMCreatable(False)]` class is created with **New** as usual. A COM-creatable class needs a constructor that takes no arguments, so a class whose only `Sub New` has required arguments fails with TB5135 --- *error generating implicit default constructor ... (for COM exposure)* --- unless it is marked `[COMCreatable(False)]`, is **Private**, or has a constructor without arguments as well. The first two fixes leave the class with no constructor that takes no arguments, so it still cannot be declared [**As New**](/tB/Core/New.md): that fails with TB5121. See [Parameterized Class Constructors](/Features/Advanced/Classes-and-Modules.md#parameterized-class-constructors).

## ComExport  (optional Bool)
{: #comexport }

Syntax: **[ComExport** [ **( True** \| **False )** ] **]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md) and constants, in a [**Module**](/tB/Core/Module.md)

The attribute marks a given API for export from the ActiveX control DLL being built from the project the attribute is used in.

The **Declare** can be a **Function** or a **Sub**, including the **PtrSafe** and **DeclareWide** forms. The compiler rejects the attribute on a procedure with a body, on a variable, and on a **Declare** or a constant inside a class.

```tb check_build
[ComExport]
Public Declare Function GetTickCount Lib "kernel32" () As Long
```

See also [DllExport](#dllexport).

## COMExtensible  (optional Bool)
{: #comextensible }

Syntax: **[COMExtensible** [ **( True** \| **False )** ] **]**

Applicable to: [**Interface**](/tB/Core/Interface.md), [**Class**](/tB/Core/Class.md)

Specifies whether new members added at runtime can be called by name through an interface implementing **IDispatch**. This attribute is set to **False** by default. On a **Class**, it applies to the interface the class exposes through COM.

## ComImport  (optional Bool)
{: #comimport }

Syntax: **[ComImport** [ **( True** \| **False )** ] **]**

Applicable to: [**Interface**](/tB/Core/Interface.md)

Specifies that an interface is an import from an external COM library, for instance, the Windows shell.

## CompileIf  (Bool)
{: #compileif }

Syntax: **[CompileIf(** condition **)]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md), [**Const**](/tB/Core/Const.md) in a [**Module**](/tB/Core/Module.md) or a [**Class**](/tB/Core/Class.md), variable in a [**Module**](/tB/Core/Module.md), variable in a [**Class**](/tB/Core/Class.md), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), [procedure definitions](/tB/Gloss.md#procedure)

Controls the conditional compilation of a procedure definition. Has no default value.

It controls a **Declare**, a **Const**, a variable or an **Event** in the same way: with a **False** condition the declaration is left out, so a use of its name is an error, such as TB5079, *Unrecognized symbol*.

The condition can read a **Const** of the same class or module, so two declarations of one name can each carry a condition and only one of them is compiled.

## CompilerOptions  (String)
{: #compileroptions }

Syntax: **[CompilerOptions( "** options **" )]**

Applicable to: [procedure definitions](/tB/Gloss.md#procedure)

Sets the LLVM compiler options for one procedure, in place of the **Compiler Options** in [Project Settings](/tB/IDE/Project-Settings.md). *options* is a comma-separated list of flags; an empty string turns LLVM off for the procedure. Typical use would be `[CompilerOptions("+llvm,+optimize,+optimizesize")]` to compile the procedure using the built-in LLVM instead of the default compiler, with chosen optimizations. [Getting Started with LLVM](/LLVM/Getting-Started.md) describes LLVM compilation in full. Compiler options available:

- **+llvm** - uses LLVM to compile this procedure. This feature is experimental at the moment. The LLVM compiler back-end is built into twinBASIC. It is not necessary to have LLVM separately installed, and any such installation is ignored by twinBASIC.
- **+optimize** - enables optimization during compilation of this procedure
- **+optimizesize** - optimize this procedure for small code size, potentially at the expense of slower speed of the procedure
- **+** and the name of a CPU instruction set, such as **+avx2** - lets LLVM use that instruction set in this procedure. The program then does not run on a CPU without it. [Per-procedure LLVM options](/LLVM/Getting-Started.md#per-procedure-llvm-options) lists the instruction sets.

## ConstantFoldable  (optional Bool)
{: #constantfoldable }

Syntax: **[ConstantFoldable** [ **( True** \| **False )** ] **]**

Applicable to: [**Function**](/tB/Core/Function.md) in a [**Module**](/tB/Core/Module.md), [**Property Get**](/tB/Core/Property.md) in a [**Module**](/tB/Core/Module.md). The compiler rejects it on a method in a [**Class**](/tB/Core/Class.md).

Specify this attribute for functions that, when called with non-variable input, can be computed at compile time rather than at runtime. For example, a function that converts a string literal to ANSI. The result never changes, so the resulting ANSI string is stored rather than recomputed on every run. Such functions are also called *pure functions*, because their output depends only on the arguments and not on the state of the program.

The restriction to modules is not an oversight. Folding a call to a method would require constant propagation through object state, and a notion of a constant object for the propagation to terminate on. twinBASIC's object model is dynamic enough to make both hard, so the compiler rejects the attribute there rather than folding a subset of cases that would be difficult to describe.

Calls are folded only when **Constant Function Folding** is set to **Yes** in [Project Settings](/tB/IDE/Project-Settings.md#constant-function-folding). A **Property Get** in a module folds as a function does. On a **Sub** or a **Declare Sub** the attribute is accepted and has no effect.

> [!WARNING] BETA 1042
> The compiler also accepts the attribute on a **Declare Function**. With **Constant Function Folding** on, a call to such a function whose arguments are all constants crashes the compiler during the build, though the project compiles without an error.

## ConstantFoldableNumericsOnly  (optional Bool)
{: #constantfoldablenumericsonly }

Syntax: **[ConstantFoldableNumericsOnly** [ **( True** \| **False )** ] **]**

Applicable to: [**Function**](/tB/Core/Function.md) in a [**Module**](/tB/Core/Module.md), [**Property Get**](/tB/Core/Property.md) in a [**Module**](/tB/Core/Module.md). The compiler rejects it on a method in a [**Class**](/tB/Core/Class.md).

A limited case of [constant foldable attribute](#constantfoldable), which applies only if the function was called with a numeric parameter. The restriction to modules is the same one [ConstantFoldable](#constantfoldable) carries, and for the same reason, and so are the Project Settings option it needs and the crash on a **Declare Function**.

## CustomControl  (String)
{: #customcontrol }

Syntax: **[CustomControl("** image file name **")]**

Applicable to: [**Class**](/tB/Core/Class.md)

## CustomDesigner  (String)
{: #customdesigner }

Syntax: **[CustomDesigner("** designer name **")]**

Applicable to: variables in a [**Class**](/tB/Core/Class.md)

Chooses which editor the IDE's property window offers for one property, instead of the editor it would otherwise pick from the property's declared type. The argument names an editor built into the IDE.

The editor names the twinBASIC packages use, most-used first. The list is not exhaustive -- these are the ones the packages happen to ask for, and the IDE may offer others.

| Name | Applied to |
|---|---|
| `designer_SpectrumWindows` | an **OLE_COLOR** property: **BackColor**, **ForeColor**, **MaskColor**, **BorderColor**, **FillColor**, **PaperColor** |
| `designer_SpectrumWindowsOrClear` | **TransparencyKey**, an **OLE_COLOR** in which -1 means no colour |
| `designer_IconBytes` | an icon held as **Byte()**: **MouseIconINIT**, **DragIconINIT**, **IconINIT** |
| `designer_RestrictedOLEDropMode` | **OLEDropMode** |
| `designer_MultiLineText` | a **String** property holding text that may wrap: **ToolTipTextINIT**, **Caption_INIT** |
| `designer_PictureBytes` | an image held as **Byte()**: **PictureINIT**, **PaletteINIT**, **ToolboxBitmapINIT**, **MaskPictureINIT** |
| `designer_ImageList` | an image-list reference: **Icons_INIT**, **SmallIcons_INIT**, **ColumnHeaderIcons_INIT** |
| `designer_Spectrum` | a **ColorRGBA** property |
| `designer_Grapick` | a **FillColorPoints** gradient property |
| `designer_PropertyPages` | a property-pages reference |
| `BINARY` | **InternalImages_INIT** |

## Debuggable  (optional Bool)
{: #debuggable }

Syntax: **[Debuggable** [ **( True** \| **False )** ] **]**

Applicable to: [**Module**](/tB/Core/Module.md), [**Class**](/tB/Core/Class.md), [procedure in a **Class** or **Module**](/tB/Gloss.md#procedure)

When false, turns off breakpoints and stepping for the method, class or module. The default value is **True**. In a class or module marked `[Debuggable(False)]`, a [**Stop**](/tB/Core/Stop.md) statement does not enter break mode.

## DebugOnly  (optional Bool)
{: #debugonly index="TB5162" }

Syntax: **[DebugOnly** [ **( True** \| **False )** ] **]**

Applicable to: [**Sub**](/tB/Core/Sub.md), generic [**Sub**](/tB/Core/Sub.md), a [**Sub**](/tB/Core/Sub.md) in a [**Class**](/tB/Core/Class.md) (**Friend** included), a [**Sub**](/tB/Core/Sub.md) prototype in an [**Interface**](/tB/Core/Interface.md), [**Declare Sub**](/tB/Core/Declare.md)

Excludes calls to this procedure from the Build. They are only available when running from the IDE, i.e. debugging. On a **Declare Sub** the same holds for calls to the API procedure. The arguments of a call that is left out are not evaluated.

In a **Class**, and through an **Interface**, the same holds for an early-bound call. The procedure stays in the class, so a late-bound call, through an **Object** or **Variant** variable or with **CallByName**, runs in the Build too.

> [!WARNING] BETA 1042
> On **Class_Initialize** the attribute breaks the Build: a program that creates the class stops with error 91, *Object variable or With block variable not set*, or ends with an access violation. A run from the IDE is right. Written as `[DebugOnly(False)]` it changes nothing.

The attribute is accepted on a **Sub** in a **Module**, a **Class** or an **Interface**, and on a **Declare Sub**. On a **Function**, a **Property** or a **Declare Function** it is error **TB5162**, *[DebugOnly] is only allowed on Sub procedures*.

## Default
{: #default }

Syntax: **[Default]**

Applicable to: [**Interface**](/tB/Core/Interface.md) declaration within a [**CoClass**](/tB/Core/CoClass.md)

Marks which of a CoClass's interfaces is its default: the one a client binds to when it holds the CoClass without asking for a particular interface.

A CoClass declares one default interface, and separately one default source interface, which also carries [Source](#source):

```tb check_build project=packages
[CoClassId("E7F3D923-475B-4367-B5EF-568FCF3A74B5")]
CoClass CustomControlTimer
    [Default] Interface _CustomControlTimer
    [Default, Source] Interface _CustomControlTimerEvents
End CoClass
```

## DefaultDesignerEvent
{: #defaultdesignerevent }

Syntax: **[DefaultDesignerEvent]**

Applicable to: [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md)

Marks the event a control nominates as its primary one. Each control of the VB package that declares it declares exactly one: **Click** for **CheckBox** and **CommandButton**, **Change** for **ComboBox**, **Validate** for **Data**. The **ListView** and **TreeView** controls of WinNativeCommonCtls mark two, **Click** and **BeforeLabelEdit**.

## DefaultMember (optional Bool)

{: #defaultmember }

Syntax: **[DefaultMember** [ **(** **True** \| **False** **)** ] **]**

Applicable to: [procedure in a **Class**](/tB/Gloss.md#procedure), [procedure](/tB/Gloss.md#procedure) prototype in an [**Interface**](/tB/Core/Interface.md)

Default members are accessed under the instance of the object itself, without specifying their name. For example, a class that offers indexable elements may have an **Item** property that is the default member:

```tb check_build slot=file
Class MyCollection
    [DefaultMember]
    Property Get Item(ByVal index&) As String
        ' ...
    End Property
        
    [DefaultMember]
    Property Let Item(ByVal index&, ByVal value$)
        ' ...
    End Property
End Class

Module DefaultMemberDemo
    Sub Example()
        Dim coll As New MyCollection
        Debug.Print "Item #3: ", coll(3)   ' Property Get Item is invoked
        coll(4) = "Item 4"                 ' Property Let Item is invoked
    End Sub
End Module
```

On a prototype in an **Interface**, the member gets the dispatch ID 0, so it is the default member of a variable declared as that interface, whichever class is behind it.

## Description  (String) 
{: #description }

Syntax: **[Description("** arbitrary text **")]**

Applicable to: [**Class**](/tB/Core/Class.md), [**CoClass**](/tB/Core/CoClass.md), [**Const**](/tB/Core/Const.md) in a [**Module**](/tB/Core/Module.md) or a [**Class**](/tB/Core/Class.md), [**Declare** (API declaration)](/tB/Core/Declare.md), [**Enum**](/tB/Core/Enum.md), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), variable in a [**Class**](/tB/Core/Class.md), variable in a [**Module**](/tB/Core/Module.md), [**Interface**](/tB/Core/Interface.md), [**Module**](/tB/Core/Module.md), [procedure](/tB/Gloss.md#procedure), [procedure](/tB/Gloss.md#procedure) parameter, [**Type** (UDT)](/tB/Core/Type.md), member of a [**Type** (UDT)](/tB/Core/Type.md)

Provides a description in information popups in the IDE, and is exported as a `helpstring` attribute in the type library (if applicable). The type library holds one for each public procedure, property, event and variable of a class, and for each prototype of an interface. A **Const**, an **Enum**, a variable of a module, a **Type** member and a parameter get none there: their text shows in the popup, and in the Object Browser for a **Const**, an **Enum** and a variable of a module.

The text of a parameter shows when the pointer rests on the parameter's name in the body of the procedure. A parameter of a **Declare** or of an **Interface** prototype has no body, so nothing shows its text.

> [!NOTE] BETA 1042
> The popup of a member of a **Type**, and of a variable of a **Class**, shows the text twice, run together: *one lineone line*.

The value is a **String** whose content is Markdown. The IDE renders it when it displays the popup, so headings, code spans and fenced code blocks all work. The attribute takes a single string literal, so a description running to several lines is assembled with `& vbCrLf & _` continuations, one source line per line of Markdown.

The packages that ship with twinBASIC follow a consistent shape, shown here on `CurrentProjectName` from the VBA package's `Compilation` module:

```tb check_build
[Description("Retrieves the name of the current project as a literal string.  " & vbCrLf & _
             "### Syntax" & vbCrLf & _
             "`projectName = CurrentProjectName()`  " & vbCrLf & _
             "### Parameters" & vbCrLf & _
             "This function does not take any parameters.  " & vbCrLf & _
             "### Return value" & vbCrLf & _
             "Returns the name of the current project as a String.  " & vbCrLf & _
             "### Example" & vbCrLf & _
             "```basic" & vbCrLf & _
             "' Example: Retrieve the current project name" & vbCrLf & _
             "Dim projectName As String" & vbCrLf & _
             "projectName = CurrentProjectName()" & vbCrLf & _
             "MsgBox ""The name of this project is "" & projectName" & vbCrLf & _
             "```")]
' Note, this function uses special internal bindings and so may not behave like a regular function
Public DeclareWide PtrSafe Function CurrentProjectName Lib "<compilation>" Alias "#-33" () As String
```

Five details of that are easy to get wrong:

- **The member is a `Declare`, not an ordinary Function.** Nothing about the attribute requires that -- it is simply how this particular member happens to be written -- but it is worth reading carefully, because a description shaped like a function's is sitting on an API declaration.

- **The two spaces before several of the closing quotes are Markdown hard line breaks.** A bare newline is a soft break in Markdown and renders as a space, so removing them runs the lead sentence and the prose under each heading together into one paragraph. They appear on the prose lines only: the `###` headings and the lines inside the fenced block are already block-level and do not need them. They read as stray trailing whitespace and are easy to delete by accident.
- **A literal `"` inside the string is doubled**, as in `""The name of this project is ""`. That is ordinary twinBASIC string syntax rather than anything Markdown-specific, but it is dense enough here to be misread as part of the description.
- **The fence tag is `basic`**, which is what the IDE's Markdown renderer understands. It has nothing to do with the fence languages this documentation site highlights.
- **The section order is conventional**: a lead sentence, then `### Syntax`, `### Parameters`, `### Return value` and `### Example`. The example above keeps `### Parameters` even though the function takes none, and says so in the body.

## DispId  (Integer)
{: #dispid }

Syntax: **[DispId(** 123 **)]**

Applicable to: [procedure in an Interface](/tB/Gloss.md#procedure), [procedure in a **Class**](/tB/Gloss.md#procedure), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md)

Defines a dispatch ID associated with the procedure when exposed via **IDispatch**. In a **Class**, it sets the dispatch ID of the member in the interface the class exposes through COM, or, on an **Event**, in its event interface; the accessors of a property share one ID.

## DispInterface
{: #dispinterface }

Syntax: **[DispInterface]**

Applicable to: [**Interface**](/tB/Core/Interface.md) in a **Library**

> [!NOTE]
> This attribute is generated in the **Library** modules that twinBASIC generates for COM references in a project. It cannot be manually created.

Indicates that the interface exposes methods via **IDispatch** late-binding. This is the default. Note that [**DualInterface**](#dualinterface) can also be specified, giving much improved performance over that of **IDispatch**-based interfaces.

It is usually written combined with the other attributes on the interface rather than alone --- `[Hidden, DispInterface, COMExtensible]`. See [**LibraryId**](#libraryid) for what a generated **Library** module looks like.

## DllExport  (optional String)
{: #dllexport index="TB5163" }

Syntax: **[DllExport** [ **("** export name **")** ] **]**

Applicable to: [procedures](/tB/Gloss.md#procedure) and constants in a module.

It's possible to export a function or constant from standard modules. The compiler rejects the attribute on a module-level variable. Example:

```tb check_build
[DllExport]
Public Const MyExportedSymbol As Long = &H00000001
```

Without an argument the DLL exports the procedure or constant under its own name. A **String** argument sets the name the DLL exports it under:

```tb check_build
[DllExport("Add_Numbers")]
Public Function AddNumbers(ByVal a As Long, ByVal b As Long) As Long
    Return a + b
End Function
```

The attribute takes no **Boolean**: `[DllExport(True)]` and `[DllExport(False)]` are error **TB5163**, *Expected a single String argument*.

## DLLStackCheck  (optional Bool)
{: #dllstackcheck }

Syntax: **[DLLStackCheck** [ **( True** \| **False)** ] **]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md), [**Delegate**](/tB/Core/Delegate.md)

Switches the stack check that follows a call in a 32-bit build. A 64-bit build has no check, with or without the attribute.

A call through a **Delegate** is checked by default. When the delegate's signature has left the stack wrong, the call raises error -353703419, *Bad DLL definition. Stack corruption detected.* `[DLLStackCheck(False)]` removes the check, which makes the code smaller; the program may then end with an access violation. Written bare or with **True**, the attribute changes nothing.

> [!WARNING] BETA 1042
> On a **Declare** the attribute works the other way round. A call of a **Declare** is not checked by default, so a wrong signature can end the program with an access violation. `[DLLStackCheck(False)]` adds the check, which makes the code larger, and a wrong signature then raises the same error. Written bare or with **True**, it changes nothing. VB6 raises error 49, *Bad DLL calling convention*, in its IDE and in a P-Code exe.

## DualInterface
{: #dualinterface }

Syntax: **[DualInterface]**

Applicable to: [**Interface**](/tB/Core/Interface.md) in a **Library**

> [!NOTE]
>
> This attribute is generated in the **Library** modules that twinBASIC generates for COM references in a project. It cannot be manually created.

Indicates that the interface exposes methods through the OLE VTable binding. The latter has much improved performance over that of **IDispatch**-based interfaces.

See [**LibraryId**](#libraryid) for what a generated **Library** module looks like.

## EnforceErrors  (Warning code list)
{: #enforceerrors index="TB5169" }

Syntax: **[EnforceErrors** **(** **TBnnnn** [ **,** **TBmmmm** ]... **)** **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**Interface**](/tB/Core/Interface.md), [**Module**](/tB/Core/Module.md), [**Declare**](/tB/Core/Declare.md), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure)

Reports the named warnings as errors within the class, interface, module or procedure the attribute is applied to. The codes are written bare, as for [IgnoreWarnings](#ignorewarnings). With `[EnforceErrors(TB0009)]` on a procedure, a call to a procedure marked [Unimplemented](#unimplemented) is an error where it would otherwise be warning TB0009. Written bare it is accepted and has no effect. With **True** or **False** in place of a code it is error TB5169, *Expected an error code in the format of TBxxxx*.

On a **Declare** or an **Event** it covers the warnings of the declaration itself, such as TB0003 for a parameter with no type. A warning at a call of the **Declare** is not covered.

## EnforceWarnings  (Warning code list)
{: #enforcewarnings index_also="TB5169" }

Syntax: **[EnforceWarnings** **(** **TBnnnn** [ **,** **TBmmmm** ]... **)** **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**Interface**](/tB/Core/Interface.md), [**Module**](/tB/Core/Module.md), [**Declare**](/tB/Core/Declare.md), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure)

Takes warning codes written bare, as [IgnoreWarnings](#ignorewarnings) does. A warning it names is reported as a warning, also one the compiler does not report by default: with `[EnforceWarnings(TB0018)]`, assigning a **Long** to an **Integer** gives warning TB0018, *implicit narrowing conversion*, which is otherwise not reported. With **True** or **False** in place of a code the attribute is TB5169, *Expected an error code in the format of TBxxxx*.

On a **Declare** or an **Event** it covers the warnings of the declaration itself. Written bare it has no effect.

## Enumerator
{: #enumerator }

Syntax: **[Enumerator]**

Applicable to: [procedure](/tB/Gloss.md#procedure) in a [**Class**](/tB/Core/Class.md) or [**Interface**](/tB/Core/Interface.md)

Marks the member that supplies an enumerator, which is what makes the object usable with [For Each](/tB/Core/For-Each-Next.md). The member is conventionally named `_NewEnum` and returns **stdole.IUnknown** or a **Variant** wrapping one.

```tb check_build slot=class
Private InternalCollection As New Collection

[Enumerator]
Public Property Get _NewEnum() As Variant
    Return InternalCollection.[_NewEnum]
End Property
```

This replaces VB6's hidden `VB_UserMemId = -4` procedure attribute, which twinBASIC still accepts for compatibility. [Custom Enumerators](/Features/Language/Custom-Enumerators.md) describes the member's rules, and how a class can implement the enumerator itself.

## EnumId  (String)
{: #enumid }

Syntax: **[EnumId("** 00000000-0000-0000-0000-000000000000 **")]**

Applicable to: [**Enum**](/tB/Core/Enum.md)

Specifies a GUID to be associated with an enum in type libraries.

## EventInterfaceId  (String)
{: #eventinterfaceid }

Syntax: **[EventInterfaceId("** 00000000-0000-0000-0000-000000000000 **")]**

Applicable to: [**Class**](/tB/Core/Class.md)

Assigns a fixed COM IID to the event interface twinBASIC generates for a class from its **Event** declarations. It is the events-side counterpart of [InterfaceId](#interfaceid), which fixes the IID of the class's own interface.

A host may cache the IID, so a generated one that changes between builds or between bitnesses breaks clients that have already stored it. That is what the TB0013 recommendation on a [COMControl](#comcontrol) interface is asking for.

## EventsUseDispInterface  (optional Bool)
{: #eventsusedispinterface }

Syntax: **[EventsUseDispInterface** [ **( True** \| **False )** ] **]**

Applicable to: [**Class**](/tB/Core/Class.md)

Makes the event interface generated for the class a dispinterface, so events are raised through **IDispatch** by member id rather than through a vtable. VB6 and VBA event sinks expect a dispinterface, so a control meant to be consumed from either sets this.

## Flags  (optional Bool)
{: #flags }

Syntax: **[Flags** [ **( True** \| **False )** ] **]**

Applicable to: [**Enum**](/tB/Core/Enum.md)

Calculate implicit enum values as a flag set (powers of 2).

> [!NOTE]
> To prevent confusion, once an explicit value is used, all remaining values after it must also be explicit)

With the IDE option **Always show IDE Inline Code Hints** on, the editor shows the value of each member:

![An Enum named MyFlags marked with the Flags attribute, with four members flag1 to flag4. The editor's inline hints after the members read 1 << 0 to 1 << 3, each with the value in hexadecimal, from &H00000001& to &H00000008&.](/Reference/Images/flags-attribute.png){:width="358" height="142"}

## FloatingPointErrorChecks  (optional Bool)
{: #floatingpointerrorchecks }

Syntax: **[FloatingPointErrorChecks** [ **( True** \| **False)** ] **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**Module**](/tB/Core/Module.md), [procedure](/tB/Gloss.md#procedure)

Disables or enables floating point error checks within the scope of a class, module, or a single procedure/method. Used on performance-critical routines. **FloatingPointErrorChecks(False)** turns the checks off. **FloatingPointErrorChecks(True)** turns them back on where the project setting [**Disable FPU Error Checks**](/tB/IDE/Project-Settings.md#disable-fpu-error-checks) has turned them off for the whole project.

## FormDesignerId  (String)
{: #formdesignerid }

Syntax: **[FormDesignerId("** 00000000-0000-0000-0000-000000000000 **")]**

Applicable to: [**Class**](/tB/Core/Class.md)

## Hidden  (optional Bool)
{: #hidden }

Syntax: **[Hidden** [ **(** **True** \| **False** **)** ] **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**CoClass**](/tB/Core/CoClass.md), [**Interface**](/tB/Core/Interface.md), [**Module**](/tB/Core/Module.md), a [procedure](/tB/Gloss.md#procedure) in a Class or Module, a procedure in an Interface, variable in a Class, variable in a Module, [**Const**](/tB/Core/Const.md), [**Event**](/tB/Core/Event.md) declaration in a Class, [**Declare**](/tB/Core/Declare.md)

Hides the declaration from certain IntelliSense and other lists. It applies to a whole type --- a **Class**, **CoClass**, **Interface** or **Module** --- and equally to a single member of one, so a member can be kept out of those lists without hiding the type that declares it. Within a **Class** that covers procedures, variables, constants and events; within an **Interface**, the member prototypes; within a **Module**, procedures, variables, constants and [**Declare**](/tB/Core/Declare.md) statements.

In the type library of an ActiveX build, it sets the `hidden` flag of each public member of a class and each prototype of an interface it is written on; on a property, the flag goes on every accessor, whichever one carries the attribute.

> [!NOTE]
> A **CoClass** can only be hidden whole. Its body holds nothing but **Interface** lines, and the attribute is refused there with TB5155 --- unlike [**Default**](#default) and [**Source**](#source), which are interface-line attributes. It is likewise refused on an **Enum** or [**Type**](/tB/Core/Type.md) declaration, on a **Type** member, and on a procedure parameter. An **Enum** member cannot be hidden either: written before the member on the same line, the attribute is **TB5182**, and on a line of its own inside the **Enum**, `[Hidden]` declares a member named `Hidden` (see [**Enum**](/tB/Core/Enum.md)).


## IdeButton  (String)
{: #idebutton }

Syntax: **[IdeButton("** caption **")]**

Applicable to: [procedure](/tB/Gloss.md#procedure) definition in a module.

## IgnoreWarnings  (Warning code list)
{: #ignorewarnings }

Syntax: **[IgnoreWarnings** **(** **TBnnnn** [ **,** **TBmmmm** ]... **)** **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**Interface**](/tB/Core/Interface.md), [**Module**](/tB/Core/Module.md), [**Declare**](/tB/Core/Declare.md), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure)

Suppresses the named warnings within the class, interface, module or procedure the attribute is applied to. The codes are written bare, exactly as the compiler prints them, and are **not** quoted:

```tb check_build
[IgnoreWarnings(TB0001)]
Module MD5
    ' ...
End Module
```

On a **Declare** or an **Event** it covers the warnings of the declaration itself, such as TB0003 for a parameter with no type, and TB0030 for an **Alias** that repeats the name. A warning at a call of the **Declare** is not covered. Written bare, or with a code the declaration does not draw, it has no effect.

## ImplementsViaPrivateFriendlies
{: #implementsviaprivatefriendlies }

Syntax: **[ImplementsViaPrivateFriendlies]**

Applicable to: an [**Implements**](/tB/Core/Implements.md) **... Via** statement in a [**Class**](/tB/Core/Class.md)

Keeps the delegate's **Friend** members private to the delegating class. A plain `Implements ... Via` forwards the delegate's **Public** *and* **Friend** members, so a **Friend** member of the delegate becomes callable on the delegating class from anywhere else in the project. With this attribute it stays reachable from inside the class and nowhere else; **Public** members forward as they always did.

The attribute belongs on the `Via` form of the statement only. A plain **Implements** does not take it, and [**WithDispatchForwarding**](#withdispatchforwarding) --- which does --- is not accepted on the `Via` form.

```tb check_build
Public Class CVehicle
    Public Sub Honk()
    End Sub
    Friend Sub Diagnostics()
    End Sub
End Class

Public Class CCar
    [ImplementsViaPrivateFriendlies] Implements CVehicle Via mBase = New CVehicle
End Class
```

Elsewhere in the project, `Honk` is callable on a **CCar** and `Diagnostics` is not. Inside **CCar**, both are.

For an overview of the `Implements ... Via` mechanism itself, see [Implements Via for basic inheritance](/Features/Language/Inheritance.md#implements-via-for-basic-inheritance).

## IntegerOverflowChecks  (optional Bool)
{: #integeroverflowchecks }

Syntax: **[IntegerOverflowChecks** [ **( True** \| **False )** ] **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**Module**](/tB/Core/Module.md), [procedure](/tB/Gloss.md#procedure)

Disables or enables integer overflow checks within the scope of a class, module, or a single procedure/method. Used on performance-critical routines. **IntegerOverflowChecks(False)** turns the checks off. **IntegerOverflowChecks(True)** turns them back on where the project setting [**Disable Overflow Checks**](/tB/IDE/Project-Settings.md#disable-overflow-checks) has turned them off for the whole project.

Dividing the most negative **Integer**, **Long** or **LongLong** by -1 with [**\\**](/tB/Core/IntegerDivide.md) or [**Mod**](/tB/Core/Mod.md) raises error 6 whatever this attribute or the project setting says.

## InterfaceId  (String)
{: #interfaceid }

Syntax: **[InterfaceId( "**00000000-0000-0000-0000-000000000000**" )]**

Applicable to: [**Interface**](/tB/Core/Interface.md), [**Class**](/tB/Core/Class.md)

On a **Class**, it fixes the identifier of the interface the class exposes through COM, which is otherwise generated anew by each build. [EventInterfaceId](#eventinterfaceid) does the same for the class's event interface. A control class ([COMControl](#comcontrol)) should have both, and the compiler warns when it does not.

twinBASIC supports defining COM interfaces using BASIC syntax, rather than needing an type library with IDL and C++. These are only supported in .twin files, not in legacy .bas or .cls files. They must appear *before* the [**Class**](/tB/Core/Class.md) or [**Module**](/tB/Core/Module.md) statement, and will always have a project-wide scope. the The generic form for is as follows:

```tb inert=skeleton
[InterfaceId ("00000000-0000-0000-0000-000000000000")]
*<attributes>*
Interface <name> Extends <base-interface>
    *<attributes>*
	<method 1>
	*<attributes>*
	<method 2>
	' ...
End Interface
```

The methods are [procedures](/tB/Gloss.md#procedure).

For an overview of interfaces in tB, see [Defining interfaces](../../Features/Language/Interfaces-CoClasses.html#defining-interfaces).

## LibraryId  (String)
{: #libraryid }

Syntax: **[LibraryId( "**00000000-0000-0000-0000-000000000000**" )]**

Applicable to: **Library**

> [!NOTE]
> This attribute is generated in the **Library** modules that twinBASIC generates for COM references in a project. It cannot be manually created.

The GUID of the type library the **Library** module was imported from, written without surrounding braces. It is the same GUID the reference itself is recorded under in the project settings.

A **Library** module is the BASIC form of a referenced type library. Adding a COM reference to a project makes one appear, read-only, under **References** in the Project Explorer, and it is where [**DispInterface**](#dispinterface), [**DualInterface**](#dualinterface) and [**Version**](#version) are met. Its head names the library and says where it came from:

```tb inert=external
[LibraryId("00020430-0000-0000-C000-000000000046")]
[Version(2.0)]
[Description("OLE Automation")]
Library stdole

    ' Original type library: C:WindowsSysWOW64stdole2.tlb
    ' NOTE: Offsets and lengths calculated for current Win32 target.

    [InterfaceId("4EF6100A-AF88-11D0-9846-00C04FC29993")]
    [Hidden, DispInterface, COMExtensible]
    [Description("Event interface for the Font object")]
    Interface FontEvents Extends stdole.IDispatch
        [DispId(9)]
        Sub FontChanged(ByVal PropertyName As String)
    End Interface

End Library
```

The **Library** keyword is not available in project source: `Library`, `End Library` and this attribute are each rejected there with **TB5182**.

## MustBeQualified  (optional Bool)
{: #mustbequalified }

Syntax:  **[MustBeQualified** [ **(True** \| **False )** ] **]**

Applicable to: [**Module**](/tB/Core/Module.md), and to [procedures](/tB/Gloss.md#procedure), [**Declare**](/tB/Core/Declare.md) statements and [**Enum**](/tB/Core/Enum.md)s in a [**Module**](/tB/Core/Module.md)

Requires a name to be written with its qualifier, so that names that would otherwise clash stay apart. **MustBeQualified** and **MustBeQualified(True)** are the same; **MustBeQualified(False)** has no effect.

- On a procedure or a **Declare** statement, code outside its module must call it as *module*.*procedure*. A call without the module name is error **TB5079**, *Unrecognized symbol*. Inside its own module the procedure can still be called by its name alone.
- On one of a property's procedures, it applies to the property's name, so outside the module every use of the property needs the module name: with the attribute on the **Property Let** alone, a bare read through the **Property Get** is also **TB5079**.
- On an **Enum**, code outside its module must write each member as *enum*.*member*; inside its own module the member can still be written alone. The type name itself can still be used alone, as in `As` *enum*.
- On a **Module**, the module name must itself be qualified by the project or package name: *project*.*module*.*member*. The module's members can still be used by their names alone.

The **Assert** package marks all three of its modules this way, and every member in them, which is why its members are called as `Assert.Strict.IsTrue`: `Strict.IsTrue` and a bare `IsTrue` are both **TB5079**; see [Assert](/tB/Packages/Assert/index.md). The **VBRUN** package marks some of its enumerations.

```tb check_build
[MustBeQualified]
Public Enum PenStyle
    Solid
    Dashed
End Enum

Public Sub Draw()
    Dim Style As PenStyle = PenStyle.Dashed   ' outside this module, a bare Dashed is TB5079
End Sub
```

On a class the attribute is error **TB5155**, *This attribute is not supported in this context*. On a member of a class, or on an **Enum** in a class, it is error **TB5182**, *Syntax error. No handler for this symbol*.

## NonBrowsable  (optional Bool)
{: #nonbrowsable }

Syntax: **[NonBrowsable** [ **( True** \| **False )** ] **]**

Applicable to: variable in a [**Class**](/tB/Core/Class.md), [procedure in a **Class**](/tB/Gloss.md#procedure), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure) prototype in an [**Interface**](/tB/Core/Interface.md)

Keeps a member out of the surfaces that list a class's members, while leaving it callable. The twinBASIC packages apply it to members that exist for the framework's own use, such as `InternalSectionId` and `hWndHeader`.

In the type library of an ActiveX build, it sets the `nonbrowsable` flag of a public procedure, property or event of a class and of a prototype of an interface; on a property, the flag goes on every accessor. A public variable of a class gets no flag.

This is distinct from [Hidden](#hidden), which reaches the same member as well as the whole type, and from [Restricted](#restricted).

## OleAutomation  (optional Bool)
{: #oleautomation }

Syntax:  **[OleAutomation** [ **(True** \| **False )** ] **]**

Applicable to: [**Interface**](/tB/Core/Interface.md)

Controls whether this attribute is applied in the typelibrary. This attribute is set to **True** by default.

It changes only an interface that extends **IUnknown**. An interface that extends **IDispatch** is a dual interface, which is OLE Automation compatible whatever the attribute says.

## PackingAlignment  (Integer)
{: #packingalignment index="packing alignment" }

Syntax:  **[PackingAlignment( 1** \| **2** \| **4** \| **8** \| **16** \| **32** \| **64 )]**

Applicable to: [**Type** (UDT)](/tB/Core/Type.md)

twinBASIC normally aligns objects naturally within UDTs, e.g. an 8-byte object is aligned at the 8-byte boundary relative to the beginning of the UDT. This can leave gaps between UDT fields. A tighter packing can be achieved with a smaller **PackingAlignment**:

```tb check_build
[PackingAlignment(2)]
Private Type MyUDT
    x As Integer
    y As Long
    z As Integer
End Type

Private Sub CheckPacking()
    Dim t As MyUDT
    Debug.Assert Len(t) = 8 And LenB(t) = 8
End Sub
```

You'll now find that both `Len(t)` and `LenB(t)` are 8.

> [!NOTE]
> Alignment, not packing alignment, is not set this way. Specifying 16 would not get you a 16-byte structure for `t`. twinBASIC does not currently have an equivalent for `__declspec_align(n)`, but such a feature is planned. This is rare outside kernel mode programming.

For introduction to this feature, see [Custom UDT Packing](/Features/Language/UDTs.md#custom-udt-packing).

## PopulateFrom  (...)
{: #populatefrom }

Syntax: **[PopulateFrom( "json", "**internal path to .json**", "** table field **", "** name field **", "** value field **" )]**

Applicable to: [**Enum**](/tB/Core/Enum.md)

Populates an **Enum** with values from a json file bundled with the project.

The path to the .json file, and the field names, are arbitrary. Thus, the json file doesn't have to be in the Resources folder within the project.

In the future, this attribute may be expanded to allow more data file types, and more context of use besides **Enum**.

For example, consider this enum declaration in a .twin file:

```tb check_build
[PopulateFrom("json", "/Resources/MESSAGETABLE/Strings.json", "events", "name", "id")]
Enum EVENTS
End Enum
```

Then, there should be a `/Resources/MESSAGETABLE/Strings.json` file with following structure:

``` json resource=/Resources/MESSAGETABLE/Strings.json
{
    "events": 
    [
        {
            "id": -1073610751,
            "name": "service_started",
            "LCID_0000": "%1 service started"
        }
    ]
}
```

The result is as-if we hand-typed the following **Enum** definition:

```tb check_build
Enum EVENTS
    service_started = -1073610751
End Enum
```

## PredeclaredID  (optional Bool)
{: #predeclaredid }

Syntax: **[PredeclaredId** [ **( True** \| **False )** ] **]**

Applicable to: [**Class**](/tB/Core/Class.md), [**CoClass**](/tB/Core/CoClass.md)

When set, a global instance of the class is created when the application starts.

This attribute is equivalent to the `VB_PredeclaredId` attribute in VBx .cls files.

On a **CoClass**, the name of the coclass stands for one instance, created through COM at its first use and apart from any made with [**New**](/tB/Core/New.md). The coclass needs a `[Default]` interface: without one a use of its name is TB5044, *Unable to determine default interface of coclass*. The [App](/tB/Packages/AppGlobalClassObject/index.md) object is declared this way, its members marked with [RedirectToStaticImplementation](#redirecttostaticimplementation), which run with no instance at all. Unlike [AppObject](#appobject), the attribute does not make the members global names: they are written with the name in front.

> [!NOTE] BETA 1042
> In an ActiveX build, a **Class** is marked `appobject` in the type library as well as `predeclid`, which is what [AppObject](#appobject) gives it, so a client that references the library treats the members of the class as global names.

## PreserveSig  (optional Bool)
{: #preservesig }

Syntax: **[PreserveSig** [ **(** **True** \| **False** **)** ] **]**

Applicable to: Method in an [Interface](/tB/Core/Interface.md), [API Declarations](/tB/Core/Declare.md).

Default value: **False** in an Interface, **True** in an API Declare.

In COM interfaces, the default value of this attribute is **False**, since normally methods return an HRESULT that the language hides from you. **[PreserveSig** [ **(True)** ] **]** overrides this behavior and defines the function exactly as you provide. This is necessary if you need to define it as returning something other than a 4-byte **Long**, or want to handle the result yourself, bypassing the normal runtime error raised if the return value is negative (this is helpful when a negative value indicates an expected, acceptable failure, rather than a true error, like when an enum interface is out of items).

In APIs, the default value of this attribute is `True`. So therefore, you can specify `False` to rewrite the last parameter as a return. Example:

```tb inert=external
Public Declare PtrSafe Function SHGetDesktopFolder Lib "shell32" (ppshf As IShellFolder) As Long
```

can be rewritten as

```tb inert=external
[PreserveSig(False)] 
Public Declare PtrSafe Function SHGetDesktopFolder Lib "shell32" () As IShellFolder
```

## PropertyPage  (String)
{: #propertypage index="TB5259" index_also="TB5163" }

Syntax: **[PropertyPage("** page name **")]**

Applicable to: variables and [procedures](/tB/Gloss.md#procedure) in a [**Class**](/tB/Core/Class.md)

Legacy VB attribute: *VB_ProcData.VB_Invoke_Property*

Ties a property of a [**UserControl**](/tB/Packages/VB/UserControl/index.md) to one of the project's property pages, so that a host that shows a property page for a single property (the **...** button of a property sheet) opens that one. The argument is the class name of the property page, as **Add Windows PropertyPage** created it, matched exactly, case included. The control reports the page through **IPerPropertyBrowsing.MapPropertyToPage**.

```tb inert=designer
[PropertyPage("CaptionPage")]
Public Property Get Caption() As String
    Return m_Caption
End Property

Public Property Let Caption(ByVal Value As String)
    m_Caption = Value
    PropertyChanged "Caption"
End Property
```

A property takes the page from its first accessor in the source, normally the **Property Get**, whichever kind of accessor that is. Written on a later accessor, the attribute has no effect, though its name is still checked; when two accessors name different pages, the control reports the first one's. On a **Sub**, a **Function** or a **Public** variable of the control, the control reports the page for that member's DISPID in the same way. In a class that is not a **UserControl** the compiler accepts the attribute and it has no effect. On an **Interface** prototype the control reports no page, but the name is checked, as on a procedure. The legacy line `Attribute Caption.VB_ProcData.VB_Invoke_Property = "CaptionPage"` inside the **Property Get** means the same. The argument must be a **String**: `[PropertyPage]` with no argument, or with a **Boolean** or a number, is TB5163, *Expected a single String argument*. On a procedure, a name that matches no property page in the project is error TB5259, *Failed to find named PropertyPage '...' for procedure '...'*. That includes an empty string and a name that differs only in case. A variable's name is not checked.

> [!NOTE] BETA 1042
> VB6 stores a property's page as `"PageName;Category"` in the legacy attribute, with the category the property sheet groups the property under. twinBASIC reads such a legacy line and drops what follows the semicolon. **[PropertyPage]** takes the whole string as the name, so `[PropertyPage("CaptionPage;Appearance")]` is TB5259.

```tb probe projname=propertypage-semicolon project=activex-control slot=file id=propertypage-semicolon expect-error=TB5259
[Description("")]
[FormDesignerId("7B247400-0000-4000-9000-7B2474000F51")]
[ClassId("7B247400-0000-4000-9000-7B2474000F55")]
[InterfaceId("7B247400-0000-4000-9000-7B2474000F56")]
[EventInterfaceId("7B247400-0000-4000-9000-7B2474000F57")]
[COMControl]
Class ProbeControl
    [PropertyPage("ProbePage;Appearance")]
    Public Property Get Caption() As String
    End Property
End Class
```

```tb probe projname=propertypage-legacy-semicolon project=activex-control slot=file id=propertypage-legacy-semicolon
[Description("")]
[FormDesignerId("7B247400-0000-4000-9000-7B2474000F51")]
[ClassId("7B247400-0000-4000-9000-7B2474000F55")]
[InterfaceId("7B247400-0000-4000-9000-7B2474000F56")]
[EventInterfaceId("7B247400-0000-4000-9000-7B2474000F57")]
[COMControl]
Class ProbeControl
    Public Property Get Caption() As String
        Attribute Caption.VB_ProcData.VB_Invoke_Property = "ProbePage;Appearance"
    End Property
End Class
```

```tb probe projname=propertypage-legacy-unknown project=activex-control slot=file id=propertypage-legacy-unknown expect-error=TB5259
[Description("")]
[FormDesignerId("7B247400-0000-4000-9000-7B2474000F51")]
[ClassId("7B247400-0000-4000-9000-7B2474000F55")]
[InterfaceId("7B247400-0000-4000-9000-7B2474000F56")]
[EventInterfaceId("7B247400-0000-4000-9000-7B2474000F57")]
[COMControl]
Class ProbeControl
    Public Property Get Caption() As String
        Attribute Caption.VB_ProcData.VB_Invoke_Property = "NoSuchPage;Appearance"
    End Property
End Class
```

The pages the control offers as a whole are listed in its [**PropertyPages**](/tB/Packages/VB/UserControl/index.md#propertypages) property.

## RedirectToStaticImplementation  (String)
{: #redirecttostaticimplementation }

Syntax: **[RedirectToStaticImplementation("** fully qualified path to a procedure **")]**

Applicable to: [procedure](/tB/Gloss.md#procedure) prototype in an [**Interface**](/tB/Core/Interface.md)

Supplies an implementation for an interface prototype without a class behind it: the interface declares the signature, and the named module-level procedure is what a call reaches.

The [App](/tB/Packages/AppGlobalClassObject/index.md) object is built this way, each of its properties naming a procedure in a private module:

```tb check_build
Public Interface _App Extends stdole.IUnknown
    [RedirectToStaticImplementation("InternalStuff.GetAppPath")]
    Property Get Path() As String
    [RedirectToStaticImplementation("InternalStuff.GetAppEXEName")]
    Property Get EXEName() As String
End Interface
```

## Restricted  (optional Bool)
{: #restricted }

Syntax: **[Restricted** [ **( True** \| **False )** ] **]**

Applicable to: [**Interface**](/tB/Core/Interface.md), [**Class**](/tB/Core/Class.md), [**Module**](/tB/Core/Module.md), [procedure in a **Class** or **Module**](/tB/Gloss.md#procedure), [**Declare** (API declaration)](/tB/Core/Declare.md), [**Const**](/tB/Core/Const.md) in a [**Module**](/tB/Core/Module.md) or a [**Class**](/tB/Core/Class.md), variable in a [**Class**](/tB/Core/Class.md), variable in a [**Module**](/tB/Core/Module.md), [**Event**](/tB/Core/Event.md) declaration in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure) prototype in an [**Interface**](/tB/Core/Interface.md)

Restricts the interface methods from being called in most contexts.

This is attribute has the same function as the [**restricted** MIDL attribute][MIDL restricted]. On a **Class**, it marks the class and the interface it exposes through COM as restricted in the type library. On a single member, it marks that member; on a property, only the accessor it is written on.

A **Module** and its members do not reach a type library. There the attribute hides the name in the IDE and changes nothing else: the code still compiles and runs. A procedure or a **Declare** leaves the IntelliSense lists and the Object Browser, a **Const** or a variable leaves the IntelliSense lists only, and a **Module** leaves the Object Browser only. A **Declare** or a **Const** in a **Class** leaves the lists of the code inside the class.

[MIDL restricted]: https://learn.microsoft.com/en-us/windows/win32/midl/restricted

## RunAfterBuild  (optional Bool)
{: #runafterbuild index="TB5114" index_also="TB5155" }

Syntax: **[RunAfterBuild** [ **( True** \| **False )** ] **]**

Applicable to: [**Sub**](/tB/Core/Sub.md) in a [**Module**](/tB/Core/Module.md)

Specifies a procedure that runs after your exe is built. There's `App.LastBuildPath` to know where it is if you're e.g. signing the executable.

The procedure is a **Sub** with no parameters that is not generic. On a **Function**, a **Property Get**, a **Sub** that has a parameter, even an optional one, or a generic **Sub**, the attribute is error TB5155:

```tb check_build expect-error=TB5155
[RunAfterBuild]
Public Function Signed() As Boolean
    Signed = True
End Function
```

```tb check_build expect-error=TB5155
[RunAfterBuild]
Public Sub Signed(Of T)()
End Sub
```

Only one **[RunAfterBuild]** is allowed per project. A second one is compile error TB5114, *encountered too many [RunAfterBuild] attributes. Only allowed one per-project.* A **[RunAfterBuild]** procedure in a package that the project references does not run, and does not count as the project's one.

The procedure runs whatever the project's modules and procedures are called: a module may have the project's name, and the module that holds the procedure may also hold a procedure with the module's own name, such as a `Sub Probe` in a module `Probe`.

> [!NOTE]
> VB6 refuses a module that has the project's name, with *Name conflicts with existing module, project, or object library*. It allows a procedure named like its module.

## RunBeforeStartupObject
{: #runbeforestartupobject }

Syntax: **[RunBeforeStartupObject]**

Applicable to: [procedure](/tB/Gloss.md#procedure) in a [**Module**](/tB/Core/Module.md)

Runs the function before the project's startup object. Returning **True** suppresses the startup object entirely; returning **False** lets startup proceed as normal.

A **Function** is the usual form, returning a **Boolean**. A **Function** of another type, or a **Property Get**, works the same way: a result of 0 or **Nothing** lets startup proceed, and any other result suppresses the startup object. A **Sub** runs too, and then the startup object never runs.

A procedure with the attribute in a package that the project references runs too, before the startup object, whether or not the project calls the package.

> [!NOTE] BETA 1042
> The attribute is not allowed on a generic procedure, such as `Sub Pre(Of T)()`. The project compiles in the editor without an error, but building it fails with the message *Build FAILED due to invalid RunBeforeStartupObject procedure*, which names neither the procedure nor the reason.

> [!WARNING] BETA 1042
> The compiler accepts the attribute on more than one procedure, with no error or warning, and the built program runs only the last of them; the others never run. It also accepts the attribute on a procedure with parameters, which then runs with arbitrary values for its parameters, even for an **Optional** parameter that has a default. Give the attribute to one procedure, with no parameters.

The CEF package uses it to intercept the sub-process launches Chromium makes of the host executable, which must not run the application's own `Sub Main`:

```tb check_build project=packages
Private Module PreSubMain
    [RunBeforeStartupObject]
    Function BeforeMain() As Boolean
        If (InStr(Command, "--type=") = 0) Then
            Return False        ' not a CEF sub process, so launch as usual
        Else
            cefPackage.InitializeCef()
            Return True         ' Sub Main / the startup form will NOT be invoked
        End If
    End Function
End Module
```

Compare [RunAfterBuild](#runafterbuild), which runs in the IDE at build time rather than in the built program.

## Serialize  (optional Bool)
{: #serialize }

Syntax: **[Serialize** [ **( True** \| **False )** ] **]**

Applicable to: variables in a [**Class**](/tB/Core/Class.md), a [**Property Get**](/tB/Core/Property.md) in a [**Class**](/tB/Core/Class.md)

Decides whether a member of a control class is stored with the form. A **Public** variable and a property with a **Public** **Property Get** are listed under PROPERTIES by default. `[Serialize(False)]` on the variable, or on the property's **Property Get**, takes it off the list, and a variable marked so is not restored when the form loads. Written on a **Property Let** or a **Property Set** it has no effect.

## SetDllDirectory  (optional Bool)
{: #setdlldirectory }

Syntax: **[SetDllDirectory** [ **( True** \| **False )** ] **]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md), [**Module**](/tB/Core/Module.md), [**Class**](/tB/Core/Class.md)

Allows an explicitly loaded DLL to load its own dependencies from its load path. It can be used per-declare, or on a module or a class, where it applies to every **Declare** inside it.

It also lets a **Declare** that names its DLL without a path find the DLL in the current directory, which the search otherwise leaves out. An exe started from its own folder has the app path as its current directory. So has a 32-bit run in the IDE; a 64-bit run in the IDE has the IDE's folder.

## SimplerByVals  (optional Bool)
{: #simplerbyvals }

Syntax: **[SimplerByVals** [ **( True** \| **False )** ] **]**

Applicable to: [procedures](/tB/Gloss.md#procedure) and [**Declare**](/tB/Core/Declare.md) statements in a [**Module**](/tB/Core/Module.md)

On a **Declare**, the attribute passes a `ByVal` object without the **AddRef** that the caller otherwise makes: a native callee finds a reference count of 1, not 2.

On a procedure in a **Class** or an **Interface**, and on a **Declare** in a class, the attribute is error **TB5182**, *Syntax error. No handler for this symbol*.

## Source
{: #source }

Syntax: **[Source]**

Applicable to: [**Interface**](/tB/Core/Interface.md) declaration within a [**CoClass**](/tB/Core/CoClass.md)

Marks a CoClass interface as the one the CoClass raises events on, rather than one callable on it. A client implements this interface to receive the events.

Every use in the twinBASIC packages pairs it with [Default](#default) in one set of braces, which marks the interface as the CoClass's *default* source interface:

```tb check_build project=packages
CoClass CustomControlTimer
    [Default] Interface _CustomControlTimer
    [Default, Source] Interface _CustomControlTimerEvents
End CoClass
```

The pairing is a convention rather than a requirement -- `[Source]` on its own compiles, and marks the interface as a source of events without making it the default one.

## SpecialCompilerBinding  (Integer)
{: #specialcompilerbinding }

Syntax: **[SpecialCompilerBinding(** *n* **)]**

Applicable to: [procedure](/tB/Gloss.md#procedure), [**Declare** (API declaration)](/tB/Core/Declare.md)

Binds the member to one of the compiler's own internal implementations, selected by number.

> [!IMPORTANT]
> This attribute exists for the packages that ship with twinBASIC. The numbers are not a vocabulary a project can choose from: each names one behaviour already built into the compiler, and nothing says what an unlisted number does.

The numbers the VB package uses, should you meet one while reading its source: `(1)` and `(2)` on the `GlobalLoad` and `GlobalUnload` declares, `(3)` on a generic `Item` property, `(4)` on `IdleMessageLoopBreakpoint`, `(253)` on the **Left**, **Top**, **Width** and **Height** properties of the controls, forms, user controls, property pages and reports, and `(254)` on **Form**'s `Show`, where a comment in the source says it "prevents ClassBeforeFirstMemberAccessFunc for this member".

## TestCase  (optional Bool)
{: #testcase }

Syntax: **[TestCase** [ **( True** \| **False )** ] **]**

Applicable to: [procedure](/tB/Gloss.md#procedure) definition in a module.

## TestFixture  (optional Bool)
{: #testfixture }

Syntax: **[TestFixture** [ **( True** \| **False )** ] **]**

Applicable to: [**Module**](/tB/Core/Module.md)

## TypeHint  (EnumType)
{: #typehint }

Syntax: **[TypeHint(** an enum type **)]**

Applicable to: [procedure](/tB/Gloss.md#procedure) parameters

Allows populating Intellisense with an enum for types other than **Long**.

## Unimplemented  (optional Bool)
{: #unimplemented }

Syntax: **[Unimplemented** [ **( True** \| **False )** ] **]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md), variable in a [**Class**](/tB/Core/Class.md), [procedure](/tB/Gloss.md#procedure) definitions

Makes the compiler issue a warning about the procedure being unimplemented wherever it's called. You can upgrade it to an error too.

On a **Declare** the warning, TB0009, comes at each call in the same way. On a **Public** variable of a class it comes at each use of the variable from outside the class; a use inside the class gives none.

## UseGetLastError  (optional Bool)
{: #usegetlasterror }

Syntax: **[UseGetLastError** [ **( True** \| **False )** ] **]**

Applicable to: [**Declare** (API declaration)](/tB/Core/Declare.md)

If the declared function indicates an error condition, the compiler won't automatically call `GetLastError` to retrieve the error code. The default value of this attribute is **True**, i.e. Declare-d functions are assumed to set `LastError` upon error.

## UserDefinedTypeIsAnAlias  (optional Bool)
{: #userdefinedtypeisanalias }

Syntax: **[UserDefinedTypeIsAnAlias** [ **( True** \| **False )** ] **]**

Applicable to:  [**Type** (UDT)](/tB/Core/Type.md)

## Version  (version number)
{: #version }

Syntax: **[Version(** *major* **.** *minor* **)]**

Applicable to: **Library**

> [!NOTE]
> This attribute is generated in the **Library** modules that twinBASIC generates for COM references in a project. It cannot be manually created.

The version of the imported type library, as a **major.minor** pair --- `[Version(2.0)]` for version 2.0 of OLE Automation. It matches the version recorded against the reference in the project settings, and is the version shown beside the library in the **Version** column of the Library References list of Project Settings.

Not to be confused with the project's own version, which is set from the project settings rather than by an attribute. See [**LibraryId**](#libraryid) for the shape of a generated **Library** module.

## WindowsControl  (String)
{: #windowscontrol }

Syntax: **[WindowsControl("** toolbox image path **")]** or **[WindowsControl("no_designer")]**

Applicable to: [**Class**](/tB/Core/Class.md)

Marks a class as a Windows control, one the form designer can place on a form, and says which image represents it in the toolbox. Pass **"no_designer"** in place of a path for a control that should compile as a control without appearing in the toolbox.

A path is relative to the project root. Where the toolbox wants the image at several sizes, `??` in the path stands for the size and the IDE resolves it against the sizes that are present:

```tb inert=skeleton
[WindowsControl("/miscellaneous/ICONS??/CheckBox??.png")]
```

The VB package supplies that one as `Miscellaneous/ICONS24/Checkbox24.png` and again under `ICONS30`, `ICONS32`, `ICONS36` and `ICONS40`. The lookup ignores case, which is why `Checkbox24` and `CheckBox30` both resolve.

Compare [CustomControl](#customcontrol), which takes one image path and no size placeholder.

## WithDispatchForwarding
{: #withdispatchforwarding }

Syntax: **[WithDispatchForwarding]**

Applicable to: an [**Implements**](/tB/Core/Implements.md) statement in a [**Class**](/tB/Core/Class.md)

Routes late-bound calls arriving on the implemented interface to the class's own default interface. Without it, a host calling through **IDispatch** reaches the implemented interface and finds nothing there to dispatch to.

The **MyCOMAddin** sample states the consequence directly: the attribute "is needed so that late-bound calls on the IRibbonExtensibility interface get routed to our MyCOMAddin default interface. Without it, events like OnHelloWorldClicked will not fire."

```tb inert=external
[WithDispatchForwarding]
Implements IRibbonExtensibility
```

