Shadowing & Displacement

Basics

Shadowing and Displacement are intended for use on picks that can be present on gizmos. If a pick is shadowed or displaced, it effectively exists in two containers at once: the gizmo container, and another container (usually the hero container).

This means that the pick can be found by iterators (for example, a foreach loop, a call to firstchild, or a table shown in the UI) in both containers. This is often used to add a pick on a gizmo, then have that pick also appear on the hero in some way (for example, in a list of weapons or special abilities).

Shadowing and Displacement are set up using the shadow and displace elements on a component.

Note that both displaced and shadowed picks may only be deleted through the original container they were added through. They may not be deleted by the user from a table in any other container.

If a pick on the hero is shadowed or displaced, there is no effect.

What's the Difference?

Normal (non-shadowed or -displaced) picks have only one container - the container that they were added through, which is known as their "owner" container. Shadowed and displaced picks have another, named the "shadow" container (how sinister!).

• If a pick is shadowed, its owner container remains the same. The shadow container is the other container (the hero or parent of the gizmo).

• If a pick is displaced, its owner container becomes the container the pick is displaced into (the hero or parent of the gizmo). The shadow container is the original container.

This has important implications. The "container" transition always goes to the owner container. Consider this script:

perform container.assign[Group.Tag]

On a normal or shadowed pick, the tag "Group.Tag" is assigned to the container the pick was added to. However, on a displaced pick, the tag is assigned to the container the pick was displaced into, because that's its owner container.

Also, bootstrapped picks are always added to the owner container. This means that if a displaced pick bootstraps other picks, those picks will be added to the container the pick was displaced into.

Script Access

Several related script transitions and target references are available for shadowed and displaced picks.

shadow	Transitions to the shadow container for a pick.
shadowed	Returns non-zero if the pick is shadowed, 0 otherwise.
displaced	Returns non-zero if the pick is displaced, 0 otherwise.

Limitations

The following limitations apply to shadowed and displaced picks:

• Choose One Only: It is not legal to have a pick that is shadowed under some circumstances, and displaced under others. Only one of the components in a component set may specify a "shadow" or "displace" element. Trying to do otherwise will cause a compilation error.

• Uniqueness: Even if a shadowed or displaced pick is unique, it will not be merged with other picks in the shadow container; merging two unique picks with different containers is not possible. (Uniqueness is observed normally in the "owner" container.)

• User-ordering: When a pick is shadowed or displaced, it maintains a SEPARATE user-sorted order within each container to avoid conflicts. The "echo" behavior of the user-sorted order into a field value is only performed for the order within the "owner" container.

• Duplication & Moving: Displaced picks can't be duplicated or stacked, or moved between gizmos and the hero (since movement and stacking effectively duplicates the original pick to move or split it). Note: This only applies to displaced picks. Shadowed picks can be duplicated, moved and stacked as normal.

• Maxlimit: Displaced picks can't use "maxlimit". This is because limits within a foreign container cannot be properly detected and policed by Hero Lab's engine. Note: This only applies to displaced picks. Shadowed picks can be duplicated, moved and stacked as normal.