Keys and Strings

Constructors

Box strings are used to derrive a key for each box.

PBUIBox* PBUIBoxMakeFromString(flags, PBStrLit("Key"));
PBUIBox* PBUIBoxMakeFromKey(flags, UIBoxKey(PBStrLit("Key"), 0));

Frame Coherence

Box keys are used to identify boxes across frames. For that reason, you must give boxes a unique key.

Key conflicts are automatically resolved internally, but there are limits to this. Consider the following example:

// frame 1
UIDiv(PBStrLit("my container"));
UIDiv(PBStrLit("my container"));
UIDiv(PBStrLit("my container"));

// frame 2
UIDiv(PBStrLit("my container"));
UIDiv(PBStrLit("my container"));

The UI does not know which element in the list was removed. The way to fix this is to use the index as part of the hash:

// frame 1
UIDiv(PBStrLit("my container##1"));
UIDiv(PBStrLit("my container##2"));
UIDiv(PBStrLit("my container##3"));

Now the UI system will recieve a unique key per element, so it can properly identify exactly which element was removed.

Special Strings

UI strings have a couple of extra features (for convinence):

PBStrLit("Hello##included_in_hash_not_shown"); // ##
PBStrLit("Hello###hash_part_only");            // ###

Anything after ## will not show as display text, but will be added when producing the UIKey.

Also, you may completely specify what the hash of a string is by using ###. In this case, only string contents after the ### will be used to produce a UIKey.

Loops

When writing loops that generate UI elements, you should make sure that each element can be uniquely identified (somehow).

For example:

for (u64 index = 0; index < 100; index += 1)
{
    UIDiv(UIfmt("my container##%llu", index));
}

Sometimes, your data may already have some unique element to identify each item in an array. In those cases you should use that instead:

for (u64 index = 0; index < items.count; index += 1)
{
    Item *item = &items.data[index];
    UIDiv(UIfmt("my container##%llu", item->id));
}

Zero Key

A zero key (UIKeyZero()) may be used for a temporary box.

The special property about zero keys is that they do not need any additional index provided to them.