Secrets of the Enumeration Editor

Depending on your style of coding the Enumeration Editor might be used regularly or not a lot. But, either way it probably contains a secret or two waiting for you.

Keyboard
The Tab key steps to the next enumeration line. Tabbing off the last enumeration lands on the blank ‘+’ line. Unfortunately pressing Return does not open the enumeration line editor (hmm, Feature Request!). Tabbing off the blank ‘+’ lands on the enumeration editor ‘Name’ field.

Shift-Tab steps to the previous enumeration line. Tabbing off the first enumeration line lands on the enumeration declaration in the Navigator.

Reordering
Existing enumerations can be reordered. Using the mouse, grab the line to be moved, drag it to the desired location in the enumeration list and release. Do not try grabbing the ‘-‘ symbol!

Assignments
A value can be assigned to an enumeration label. After the label type ‘=’ and an integer value. For example: ‘foo = 123’. Spaces around the assignment symbol (‘=’) are optional.

Note: ‘foo =’ will generate a syntax error.

Non-sequential values
Values assigned to enumeration labels do not have to be sequential. For example:

Note: Same value assignments are legal, so ‘one’ and ‘two’ could be assigned the same value, e.g. 3.

Non-ordered values
Values assigned to enumeration labels do have to be ordered. For example:

Assigned and unassigned enumerations
If assigned and unassigned enumerations are intermixed, the unassigned enumeration will be assigned the last assigned value + 1. For example:

one = 16
two
three = -2
four
five = 3
six

will render as:

one = 16
two = 17
three = -2
four = -1
five = 3
six = 4

Comments
Enumeration lines can contain comments. For example:

one = 16  //This is a comment

Any of the valid Xojo comment symbols are allowed, I just prefer ‘//’.

Base type
The default base type for an enumeration is Integer. It can be any integer type. For example: int32
One of my favourites is uint8. But you need to be aware of a couple of things. In the following example, the enumeration is ‘Foos’ and the base type is uint8:

Foos(uint8):

one =-2
two
three
four
five = 17
six

will render as:

one = 254 //value wrapped around the base type range
two = 255
three = 0
four = 1
five = 17
six = 18//Incremented from the previous value

If converting the enumeration to an integer the same base type bit-width must be used.
For example: thisValue as int32 = uint8(Foos.two)

or: thisValue as int32 = int8(Foos.two)

I try to stick to using the same enumeration base type. It avoids confusion caused by type range wrap-around.

Enumeration value references
An enumeration value can be assigned an enumeration label from another enumeration declaration. For example, given one enumeration is declared as ‘Foos’ and there is another enumeration declared as ‘Things’. In the following example ‘Things’ is attached to a module or class called ‘Those’.

Those.Things(integer):
thing1 = 1
thing2 = -2

Foos(uint8):

one = 1
two = Foos.four
three = Those.Things.thing2
four = Foos.three

Foos will render as:

one = 1
two = 254 //Clever compiler 
three = 254 //Remember base type wrap-around
four = 254

Note: The compiler will catch recursive declarations!

Constant references are also allowed. For example:

THING = 127

Foos(uint8):

one = THING

will render as:

one = 127

Current limitations
a) Non-integer base types are not allowed, e.g. String or Double

b)  Enumeration values cannot be expressions, e.g. 2+3 is not allowed Hint: Another secret, some fields in the IDE do allow simple expressions.

c)  The maximum number of enumeration elements is uint64[Max]. If that is a limitation, then your code probably has other problems!

d)  An enumeration argument is not rigorously checked against its declaration when passed as a function or method parameter. For example:

Foos(int32)
one = 1
two = 2

sub Test(value as Foos)
  dim thisValue as int32 = int32(value)
end sub

Test(Foos(5))

Would result in ‘thisValue’ having the value 5. Interestingly the Debugger will show the value ‘5’ in red, so something can detect invalid values.

e)  The enumeration editor font is not affected by the Options/Preferences,Code Editor, Font selection.

I hope there were at a least of couple of things in here you did not know before. I’m not sure if any of this makes the Enumeration Editor any easier to use, but it might make it a little more fun. Enjoy!