Enum Statement (Visual Basic)
Declares an enumeration and defines the values of its members.
[ <attribute list> ] [ access modifier ] [ Shadows ]
Enum enumeration name [ As data type ]
member list
End Enum
Parts
Part |
Description |
attribute list |
Optional. List of attributes that apply to this enumeration. You must enclose the attribute list in angle brackets ("<" and ">"). The FlagsAttribute attribute indicates that the value of an instance of the enumeration can include multiple enumeration members, and that each member represents a bit field in the enumeration value. |
access modifier |
Optional. Specifies what code can access this enumeration. Can be one of the following: You can specify Protected Friend to allow access from code within the enumeration's class, a derived class, or the same assembly. |
Shadows |
Optional. Specifies that this enumeration redeclares and hides an identically named programming element, or set of overloaded elements, in a base class. You can specify Shadows only on the enumeration itself, not on any of its members. |
enumeration name |
Required. Name of the enumeration. For information on valid names, see Declared Element Names (Visual Basic). |
data type |
Optional. Data type of the enumeration and all its members. |
member list |
Required. List of member constants being declared in this statement. Multiple members appear on individual source code lines. Each member has the following syntax and parts: [<attribute list>] member name [ = initializer ]
PartDescription
member name Required. Name of this member.
initializer Optional. Expression that is evaluated at compile time and assigned to this member.
|
End Enum |
Terminates the Enum block. |
Remarks
If you have a set of unchanging values that are logically related to each other, you can define them together in an enumeration. This provides meaningful names for the enumeration and its members, which are easier to remember than their values. You can then use the enumeration members in many places in your code.
The benefits of using enumerations include the following:
Reduces errors caused by transposing or mistyping numbers.
Makes it easy to change values in the future.
Makes code easier to read, which means it is less likely that errors will be introduced.
Ensures forward compatibility. If you use enumerations, your code is less likely to fail if in the future someone changes the values corresponding to the member names.
An enumeration has a name, an underlying data type, and a set of members. Each member represents a constant.
An enumeration declared at class, structure, module, or interface level, outside any procedure, is a member enumeration. It is a member of the class, structure, module, or interface that declares it.
Member enumerations can be accessed from anywhere within their class, structure, module, or interface. Code outside a class, structure, or module must qualify a member enumeration's name with the name of that class, structure, or module. You can avoid the need to use fully qualified names by adding an Imports statement to the source file.
An enumeration declared at namespace level, outside any class, structure, module, or interface, is a member of the namespace in which it appears.
The declaration context for an enumeration must be a source file, namespace, class, structure, module, or interface, and cannot be a procedure. For more information, see Declaration Contexts and Default Access Levels (Visual Basic).
You can apply attributes to an enumeration as a whole, but not to its members individually. An attribute contributes information to the assembly's metadata.
Data Type
The Enum statement can declare the data type of an enumeration. Each member takes the enumeration's data type. You can specify Byte, Integer, Long, SByte, Short, UInteger, ULong, or UShort.
If you do not specify data type for the enumeration, each member takes the data type of its initializer. If you specify both data type and initializer, the data type of initializer must be convertible to data type. If neither data type nor initializer is present, the data type defaults to Integer.
Initializing Members
The Enum statement can initialize the contents of selected members in member list. You use initializer to supply an expression to be assigned to the member.
If you do not specify initializer for a member, Visual Basic initializes it either to zero (if it is the first member in member list), or to a value greater by one than that of the immediately preceding member.
The expression supplied in each initializer can be any combination of literals, other constants that are already defined, and enumeration members that are already defined, including a previous member of this enumeration. You can use arithmetic and logical operators to combine such elements.
You cannot use variables or functions in initializer. However, you can use conversion keywords such as CByte and CShort. You can also use AscW if you call it with a constant String or Char argument, since that can be evaluated at compile time.
Enumerations cannot have floating-point values. If a member is assigned a floating-point value and Option Strict is set to on, a compiler error occurs. If Option Strict is off, the value is automatically converted to the Enum type.
If the value of a member exceeds the allowable range for the underlying data type, or if you initialize any member to the maximum value allowed by the underlying data type, the compiler reports an error.
Modifiers
Class, structure, module, and interface member enumerations default to public access. You can adjust their access levels with the access modifiers. Namespace member enumerations default to friend access. You can adjust their access levels to public, but not to private or protected. For more information, see Access Levels in Visual Basic.
All enumeration members have public access, and you cannot use any access modifiers on them. However, if the enumeration itself has a more restricted access level, the specified enumeration access level takes precedence.
By default, all enumerations are types and their fields are constants. Therefore the Shared, Static, and ReadOnly keywords cannot be used when declaring an enumeration or its members.
Assigning Multiple Values
Enumerations typically represent mutually exclusive values. By including the FlagsAttribute attribute in the Enum declaration, you can instead assign multiple values to an instance of the enumeration. The FlagsAttribute attribute specifies that the enumeration be treated as a bit field, that is, a set of flags. These are called bitwise enumerations.
When you declare an enumeration by using the FlagsAttribute attribute, we recommend that you use powers of 2, that is, 1, 2, 4, 8, 16, and so on, for the values. We also recommend that "None" be the name of a member whose value is 0. For additional guidelines, see FlagsAttribute and Enum.
Example
The following example shows how to use the Enum statement. Note that the member is referred to as EggSizeEnum.Medium, and not as Medium.
Public Class Egg
Enum EggSizeEnum
Jumbo
ExtraLarge
Large
Medium
Small
End Enum
Public Sub Poach()
Dim size As EggSizeEnum
size = EggSizeEnum.Medium
' Continue processing...
End Sub
End Class
The method in the following example is outside the Egg class. Therefore, EggSizeEnum is fully qualified as Egg.EggSizeEnum.
Public Sub Scramble(ByVal size As Egg.EggSizeEnum)
' Process for the three largest sizes.
' Throw an exception for any other size.
Select Case size
Case Egg.EggSizeEnum.Jumbo
' Process.
Case Egg.EggSizeEnum.ExtraLarge
' Process.
Case Egg.EggSizeEnum.Large
' Process.
Case Else
Throw New ApplicationException("size is invalid: " & size.ToString)
End Select
End Sub
The following example uses the Enum statement to define a related set of named constant values. In this case, the values are colors you might choose to design data entry forms for a database.
Public Enum InterfaceColors
MistyRose = &HE1E4FF&
SlateGray = &H908070&
DodgerBlue = &HFF901E&
DeepSkyBlue = &HFFBF00&
SpringGreen = &H7FFF00&
ForestGreen = &H228B22&
Goldenrod = &H20A5DA&
Firebrick = &H2222B2&
End Enum
The following example shows values that include both positive and negative numbers.
Enum SecurityLevel
IllegalEntry = -1
MinimumSecurity = 0
MaximumSecurity = 1
End Enum
In the following example, an As clause is used to specify the data type of an enumeration.
Public Enum MyEnum As Byte
Zero
One
Two
End Enum
The following example shows how to use a bitwise enumeration. Multiple values can be assigned to an instance of a bitwise enumeration. The Enum declaration includes the FlagsAttribute attribute, which indicates that the enumeration can be treated as a set of flags.
' Apply the Flags attribute, which allows an instance
' of the enumeration to have multiple values.
<Flags()> Public Enum FilePermissions As Integer
None = 0
Create = 1
Read = 2
Update = 4
Delete = 8
End Enum
Public Sub ShowBitwiseEnum()
' Declare the non-exclusive enumeration object and
' set it to multiple values.
Dim perm As FilePermissions
perm = FilePermissions.Read Or FilePermissions.Update
' Show the values in the enumeration object.
Console.WriteLine(perm.ToString)
' Output: Read, Update
' Show the total integer value of all values
' in the enumeration object.
Console.WriteLine(CInt(perm))
' Output: 6
' Show whether the enumeration object contains
' the specified flag.
Console.WriteLine(perm.HasFlag(FilePermissions.Update))
' Output: True
End Sub
The following example iterates through an enumeration. It uses the GetNames method to retrieve an array of member names from the enumeration, and GetValues to retrieve an array of member values.
Enum EggSizeEnum
Jumbo
ExtraLarge
Large
Medium
Small
End Enum
Public Sub Iterate()
Dim names = [Enum].GetNames(GetType(EggSizeEnum))
For Each name In names
Console.Write(name & " ")
Next
Console.WriteLine()
' Output: Jumbo ExtraLarge Large Medium Small
Dim values = [Enum].GetValues(GetType(EggSizeEnum))
For Each value In values
Console.Write(value & " ")
Next
Console.WriteLine()
' Output: 0 1 2 3 4
End Sub
See Also
Reference
Const Statement (Visual Basic)
Type Conversion Functions (Visual Basic)
Concepts
Implicit and Explicit Conversions (Visual Basic)
Constants and Enumerations (Visual Basic)
Change History
Date |
History |
Reason |
|---|---|---|
|
July 2011 |
Reorganized paragraphs, and added remarks and examples. |
Information enhancement. |