Skip to main content

Element References

Evolve is a high performance UI library and as such makes certain decisions around what the concept of a UI element really is. Unlike most other UI systems, the core unit of Evolve is not a tree node that is subclassed from some type, but a simple 4 byte type called ElementId.

Because we don't use real objects to represent our UI elements, we need a way work with ElementIds in the context of our game in order to set styles, attributes, perform layout and do all of the typical UI things. The solution to this in Evolve is a type called ElementReference.

The purpose of an ElementReference is to be the one stop shop for interfacing with the system data for a single element. An ElementReference can be used to query layout results, set style properties, manipulate a list of applied styles, check the 'live-ness' of an element, and is often passed around in templates as arguments to things that need to position themselves relatively or query an element for certain properties.

There are a few ways to get an ElementReference depending on the context you are working in.

Have a look at the built in variables: $root, $element, and $parent.

The next easiest way to get an ElementReference is by extruding one. There is a speical extrusion operator & which will resolve to an ElementReference.

You can use this operator with any identifier you want to extrude an ElementReference. When using &, as aliases are invalid. 


template Example render {

    Thing() [&myElement];
    run myElement.SetAttribute("cool", "definitely");
    
}

Element references with companion types​

When defining a companion type in C#, you can define a public, non readonly field of type ElementReference and mark it with the attribute [InjectElementReference] and the system will set the value of this field to the paired ElementReference.

// when used as a companion, the myElementReference will be set by the system. This still works even if this companion type
// is used as a companion for a decorator. Note that it will NOT be set when used as the companion of a `function`, because functions
// are not mapped 1-1 with elements. No error will be thrown in this case, the field will simply not be initialized. 
public class SomeCompanion {

    [InjectElementReference]
    public ElementReference myElementReference;

}