Enums - Revision history

SeriousBarbie: added chapter "Enum constants and variables"

2016-10-27T19:01:41Z

added chapter "Enum constants and variables"

KingJackaL: updated - you can convert an int to an Enum in UE3, have given example

2012-02-01T05:12:46Z

updated - you can convert an int to an Enum in UE3, have given example

Eliot: /* Value declarations */ Metadata

2010-07-10T02:32:46Z

‎Value declarations: Metadata

Wormbo: /* Implicit enum properties */ actually it can't

2009-06-14T17:20:57Z

‎Implicit enum properties: actually it can't

Wormbo: /* Implicit enum properties */ EnumCount doesn't work in constant definitions

2009-06-14T11:25:49Z

‎Implicit enum properties: EnumCount doesn't work in constant definitions

Wormbo: info about EnumCount and the ..._MAX value

2008-04-26T17:36:11Z

info about EnumCount and the ..._MAX value

Wormbo: New page: 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 co...

2008-04-18T15:57:07Z

New page: 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 co...

New page

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 [[UE2:Object (UT2004)#EAxis|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 [[UE1:Actor (UT)#EDrawType|EDrawType]] enum with values such as DT_Sprite or DT_Mesh and the [[UE3:Actor (UT3)#ENetRole|ENetRole]] enum with values such as ROLE_SimulatedProxy or ROLE_Authority.

In [[Unreal Engine 3]] there may be a [[metadata definition]] right after each value declaration to specify the value's [[Metadata definition#Displyname|display name]] in any of [[UnrealEd]]'s [[properties lists]].

A good example for an enum declaration with custom display names for its values is [[UE3:UIRoot (UT3)#EMaterialAdjustmentType|UIRoot.EMaterialAdjustmentType]] in [[UT3]]:
<uscript>
/** The type of adjustment to apply to a material. */
enum EMaterialAdjustmentType
{
/** no modification to material - if material is larger than target dimension, material is clipped */
ADJUST_None<DisplayName=Clipped>,

/** material will be scaled to fit the target dimension */
ADJUST_Normal<DisplayName=Scaled>,

/** material will be scaled to fit the target dimension, maintaining aspect ratio */
ADJUST_Justified<DisplayName=Uniformly Scaled>,

/** target's dimensions will be adjusted to match material dimension */
ADJUST_Bound<DisplayName=Bound>,

/** material will be stretched to fit target dimension */
ADJUST_Stretch<DisplayName=Stretched>,
};
</uscript>
As you can see, the display name of an enum value may be totally different from the actual value identifier.

==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 not possible, since there's no guarantee there's actually a valid enum value representing that number.

===Enum value to name===
To get the name of an enum value you can use the [[Object#GetEnum|GetEnum]] function. It expects an [[Literals#Objects|object literal]] representing the enum type and the index of the enum value whose name to return.

Take the following call, for example:
<uscript>GetEnum(Enum'EPhysics', 2)</uscript>
This will return the name equal to the [[Literals#Names|name literal]] <code>'PHYS_Falling'</code>. 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.

{{navbox unrealscript}}

← Older revision		Revision as of 19:01, 27 October 2016
Line 11:		Line 11:

	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.		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.
		+
		+	=== Enum constants and variables ===
		+	After an enum has been defined, use that enumname like a [[Types\|data type]]. Examples:
		+	<uscript>var EMyEnum MyEnumVar;
		+	const EMyEnum MyEnumConst;</uscript>
		+	It is also possible to define an enum and variable at once using the keyword '''[[Variables#Declaration\|var]]''' as prefix:
		+	<uscript>var enum enumname {
		+	value1, value2,...
		+	} variablename;</uscript>

	==Value declarations==		==Value declarations==

@@ Line 45: / Line 45: @@
 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 [[UE3:EPhysics (UT3)|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. Unlike the '''EnumCount''' property, the "..._MAX" constant can be used in constant definitions in UE3.
+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 [[UE3:EPhysics (UT3)|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==

@@ Line 43: / Line 43: @@
 ===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 [[constants]] or [[static array]] sizes.
+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 [[UE3:EPhysics (UT3)|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.
+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 [[UE3:EPhysics (UT3)|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. Unlike the '''EnumCount''' property, the "..._MAX" constant can be used in constant definitions in UE3.
 ==Converting enum values==

@@ Line 42: / Line 42: @@
 ===Numbers to enum values===
-Converting generic numbers to enum values is not possible, since there's no guarantee there's actually a valid enum value representing that number.
+Converting generic numbers to enum values is possible (at least in UE3), by assigning to a temporary variable:
 ===Enum value to name===

@@ Line 17: / Line 17: @@
 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 [[UE2:EAxis (UT2004)|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 [[UE1:EDrawType (UT)|EDrawType]] enum with values such as DT_Sprite or DT_Mesh and the [[UE3:ENetRole (UT3)|ENetRole]] enum with values such as ROLE_SimulatedProxy or ROLE_Authority.
-In [[Unreal Engine 3]] there may be a [[metadata definition]] right after each value declaration to specify the value's [[Metadata definition#Displyname|display name]] in any of [[UnrealEd]]'s [[properties lists]].
+In [[Unreal Engine 3]] there may be a [[metadata|metatag]] right after each value declaration to specify the value's [[Metadata#Tags|display name]] in any of [[UnrealEd]]'s [[properties lists]].
 A good example for an enum declaration with custom display names for its values is [[UE3:EMaterialAdjustmentType (UT3)|UIRoot.EMaterialAdjustmentType]] in [[UT3]]:
 <uscript>
 enum EMaterialAdjustmentType
+{
 	ADJUST_None<DisplayName=Clipped>,
 	ADJUST_Normal<DisplayName=Scaled>,
 	ADJUST_Justified<DisplayName=Uniformly Scaled>,
 	ADJUST_Bound<DisplayName=Bound>,
 	ADJUST_Stretch<DisplayName=Stretched>,
 };

@@ Line 15: / Line 15: @@
 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 [[UE2:Object (UT2004)#EAxis|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 [[UE1:Actor (UT)#EDrawType|EDrawType]] enum with values such as DT_Sprite or DT_Mesh and the [[UE3:Actor (UT3)#ENetRole|ENetRole]] enum with values such as ROLE_SimulatedProxy or ROLE_Authority.
+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 [[UE2:EAxis (UT2004)|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 [[UE1:EDrawType (UT)|EDrawType]] enum with values such as DT_Sprite or DT_Mesh and the [[UE3:ENetRole (UT3)|ENetRole]] enum with values such as ROLE_SimulatedProxy or ROLE_Authority.
 In [[Unreal Engine 3]] there may be a [[metadata definition]] right after each value declaration to specify the value's [[Metadata definition#Displyname|display name]] in any of [[UnrealEd]]'s [[properties lists]].
-A good example for an enum declaration with custom display names for its values is [[UE3:UIRoot (UT3)#EMaterialAdjustmentType|UIRoot.EMaterialAdjustmentType]] in [[UT3]]:
+A good example for an enum declaration with custom display names for its values is [[UE3:EMaterialAdjustmentType (UT3)|UIRoot.EMaterialAdjustmentType]] in [[UT3]]:
 <uscript>
 /** The type of adjustment to apply to a material. */
@@ Line 41: / Line 41: @@
 </uscript>
 As you can see, the display name of an enum value may be totally different from the actual value identifier.
 ==Converting enum values==