Difference between revisions of "Enums"

Revision as of 23:12, 31 January 2012

An enum (also enumerated type or enumeration) is a primitive data type in UnrealScript. The possible values of an enum type are a list of identifiers, which can be compared not only for equality, but also for order.

Declaration syntax

The general syntax of enum declarations is:

enum enumname {
  value1,value2,...
}

An enum declaration may appear either as standalone declaration, in which case it must be followed by a semicolon, or as inline declaration instead of the type specification in variable declarations. There is no difference between a standalone and inline declaration, in both cased the enum is a direct member of the class.

Remember that all members of an UnrealScript class share the same namespace. An enum declaration may hide any member of a parent class if it has the same name.

Unlike structs, enum types may neither have any modifiers nor contain anything else than their value declarations. By convention, enum names start with the letter E to easily recognize the type as an enum. This is only a convention, not a requirement, though.

Value declarations

The values of an enum type are identifiers, that means they must start with a letter or underscore character, may contain letters, digits and the underscore character and are restricted to a maximum length of 63 characters. Values are separated by commas and there may be an optional comma after the last value.

By convention, enum value names start with a series of capital letters specific to the enum's name, followed by an underscore character. For short enum names this is usually the capitalized enum name, like AXIS_X or AXIS_Y for the EAxis enum. For longer enum names, often either the initial letters of each enum name part are used or one of the parts, possibly shortened, is capitalized. Examples here are the EDrawType enum with values such as DT_Sprite or DT_Mesh and the ENetRole enum with values such as ROLE_SimulatedProxy or ROLE_Authority.

In Unreal Engine 3 there may be a metatag right after each value declaration to specify the value's display name in any of UnrealEd's properties lists.

A good example for an enum declaration with custom display names for its values is UIRoot.EMaterialAdjustmentType in UT3:

enum EMaterialAdjustmentType
{
	ADJUST_None<DisplayName=Clipped>,
	ADJUST_Normal<DisplayName=Scaled>,
	ADJUST_Justified<DisplayName=Uniformly Scaled>,
	ADJUST_Bound<DisplayName=Bound>,
	ADJUST_Stretch<DisplayName=Stretched>,
};

As you can see, the display name of an enum value may be totally different from the actual value identifier.

Implicit enum properties

Enum types an implicit property EnumCount. This property is similar to the Length property of a dynamic array in that it returns the number of values declared for that enum. In Unreal Engine 1 and 2 it is only available at runtime, but in Unreal Engine 3 it can also be used at compile-time to define static array sizes. For some reason it doesn't count as constant expression when defining constants.

As a synonym for EnumCount, Unreal Engine 3 also provides the implicit enum value XYZ_MAX, where XYZ is the prefix used for other values in the same enum. For example the Actor.EPhysics enum has the implicit value PHYS_MAX representing the value 13. Note that this additional enum value is also exported when generating C++ headers for native classes in Unreal Engine 2 and earlier, but it's not available to UnrealScript in those engine generations.

Converting enum values

Enum value to number

Each enum value also stands for a byte value. Variables of an enum type or function returning an enum value can directly be used as if they were of an integer type. The integer representation of an enum value depends on its position in the value list. The first value represents the integer value 0, the second represents 1, the next 2, then next 3 and so on.

Numbers to enum values

Converting generic numbers to enum values is possible (at least in UE3), by assigning to a temporary variable:

local EMaterialAdjustmentType TheEnum;
TheEnum = 3;
`Log(TheEnum);

...will return "ADJUST_Bound". The standard casting syntax for UE3 appears to work:

`Log(EMaterialAdjustmentType(3));

...but this will return "3".

Enum value to name

To get the name of an enum value you can use the GetEnum function. It expects an object literal representing the enum type and the index of the enum value whose name to return.

Take the following call, for example:

GetEnum(Enum'EPhysics', 2)

This will return the name equal to the name literal 'PHYS_Falling'. Note that the second parameter of the GetEnum function is actually of type int. Since enum values can also be used as numbers (as described above), you can also pass in variables or function return values of an enum type.

Enum value to string

If you typecast an enum value to string, you will only get the string representation of the numeric representation as described above in "Enum value to number". To get the string representation of the enum value name, you can instead typecast the return value of the GetEnum function to string.

String or name to enum value

This is only really possible in Unreal Engine 1 and 2 and only for enum variables at the class level, because it requires the SetPropertyText function, which was removed in Unreal Engine 3. Simply pass the name of the enum variable as the first parameter and the desired enum value as the second parameter to assign the value to the variable.