Udostępnij za pośrednictwem

Enum Statement (Visual Basic)

  • Artykuł

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

Enum

Const Statement (Visual Basic)

Dim Statement (Visual Basic)

Type Conversion Functions (Visual Basic)

AscW

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.