Class Element<TemplateSpecType, TypeConfig>

Type Parameters

Hierarchy (View Summary)

Implements

Constructors

Properties

__$type_TemplateSpec: CompileElementTemplateSpecType<
    TemplateSpecType,
    TypeConfig,
>

Phantom type that holds the LiteralType.

NOT AVAILABLE AT RUNTIME.

active: boolean

Active State

true if this Element is active, otherwise false.

See Lifecycle Events.

alpha: number

Defines the opacity of this Element and its descendants. This can be any number between 0.0 (0% opacity) and 1.0 (100% opacity).

  • If set to 0.0:
    • This Element is not rendered, but will still maintain its space in a Flex Box layout
  • If set to 1.0 (default):
    • This Element is rendered with 100% opacity.

The visible property takes prescendence over alpha.

1.0
attached: boolean

Attached State

true if this Element is attached, otherwise false.

See Lifecycle Events.

boundsMargin: null | [number, number, number, number]

Sets a Bounds Margin for this Element.

Format:

[left margin, top margin, right margin, bottom margin]
  • If null (default):
    • Inherit from Bounds Margins from parent

Note: If no bounds margins are set in the render tree, the default on all sides is 100.

The Bounds Margin influences whether an Element will be rendered as if it were on screen. If the Bounds Margin is 0 on all sides, then this Element will only be rendered if exactly any part of it's rectangle is potentially visible on screen. Adding to the Bounds Margin allows an Element to be rendered as it gets closer to becoming visible on screen.

null
childList: ElementChildList
clipbox: boolean

Clipbox

If set to true (default), does not render any of this Element's children if the Element itself is completely out-of-bounds.

Explicitly set this to false to enable rendering of children in that situation.

true

clipping: boolean

Defines whether clipping should be turned on or off for this element

  • If set to true:
    • Everything outside the dimensions of this Element is not rendered. (The effect is similar to overflow:hidden in CSS.)
  • If set to false (default):
    • Everything outside the dimensions of this Element is rendered.

Setting this property might increase the performance, as descendants outside the clipping region are detected and not rendered.

Clipping is implemented using the high-performance WebGL operation scissor. As a consequence, clipping does not work for non-rectangular areas. So, if the Element is rotated (by itself or by any of its ancestors), clipping is not applied. In such situations, you can use the advanced renderToTexture property which applies clipping as a side effect.

false
collision: boolean

Mouse pointer collision

If set true, then it allows a Mouse Pointer to click/hover over this Element.

color: number

Rectangle Color

This and the other color* properties are used to change the color of the Element when rect is set to true.

This property sets all of the corners/sides to the same color.

The color value is expressed as an ARGB hexadecimal value:

   A R G B
| | | |
0xffeeddcc
colorBl: number

Bottom-left Corner Rectangle Color

color

colorBottom: number

Bottom Side Rectangle Color

color

colorBr: number

Bottom-right Corner Rectangle Color

color

colorizeResultTexture: boolean

If set to true, applies a colorization effect to the resulting texture when rtt is on.

This property has no effect if rtt is not enabled.

colorLeft: number

Left Side Rectangle Color

color

colorRight: number

Right Side Rectangle Color

color

colorTop: number

Top Side Rectangle Color

color

colorUl: number

Upper-left Corner Rectangle Color

color

colorUr: number

Upper-right Corner Rectangle Color

color

cursor: undefined | string

Hover cursor

See the keyword values at cursor CSS property (MDN) for valid values.

See PR #356 for more information on this feature.

undefined (no cursor)

displayedTexture: null | TextureType<TypeConfig>

The currently displayed texture. While this.texture is loading, this one may be different.

enabled: boolean

Enabled State

true if this Element is enabled, otherwise false.

See Lifecycle Events.

finalH: number

If flexbox is enabled for this Element, contains the final height of the Element after the layout update operation has been done.

See Flexbox - Final Coordinates for more information.

finalW: number

If flexbox is enabled for this Element, contains the final width of the Element after the layout update operation has been done.

See Flexbox - Final Coordinates for more information.

finalX: number

If flexbox is enabled for this Element, contains the final X position of the Element after the layout update operation has been done.

See Flexbox - Final Coordinates for more information.

finalY: number

If flexbox is enabled for this Element, contains the final Y position of the Element after the layout update operation has been done.

See Flexbox - Final Coordinates for more information.

flex: Flex

Flexbox container properties

See Flexbox documentation for more information.

flexItem: FlexItem

Flexbox item properties

See Flexbox documentation for more information.

forceZIndexContext: boolean

Forces a new z-index context for children of this Element.

See Z-Indexing for more information.

false

isElement: 1
isRoot: boolean
mh: number

The maximum expected texture source height.

WARNING: DO NOT read from this property. It is WRITE-ONLY. It will return undefined.

mount: number

Texture mountpoint

Controls the position within the Element that is placed at x and y along both the horizontal and vertical axes. Can be any floating point number between 0.0 and 1.0.

Examples:

  • 0.0 (default) = top-left corner
  • 0.5 = center
  • 1.0 = bottom-right corner

mountX: number

Texture mountpoint on horizontal axis

Controls the position within the Element that is placed at x and y along the horizontal axis. Can be any floating point number between 0.0 and 1.0.

Examples

  • 0.0 (default) = left side
  • 0.5 = center
  • 1.0 = right side
0.0
mountY: number

Texture mountpoint on vertical axis

Controls the position within the Element that is placed at x and y along the vertical axis. Can be any floating point number between 0.0 and 1.0.

Examples

  • 0.0 (default) = top side
  • 0.5 = center
  • 1.0 = bottom side
0.0
mw: number

The maximum expected texture source width.

WARNING: DO NOT read from this property. It is WRITE-ONLY. It will return undefined.

onAfterCalcs:
    | undefined
    | null
    | OnAfterCalcsCallback<
        Lightning.Element<
            Lightning.Element.TemplateSpecLoose,
            Lightning.Element.TypeConfigLoose,
        >,
    >

??? (make sure matches literal version)

Note: This property will always return undefined when read.

onAfterUpdate:
    | undefined
    | null
    | OnAfterUpdateCallback<
        Lightning.Element<
            Lightning.Element.TemplateSpecLoose,
            Lightning.Element.TypeConfigLoose,
        >,
    >

Callback called after the Element's flexbox layout is updated.

Note: This property will always return undefined when read.

onUpdate:
    | undefined
    | null
    | OnUpdateCallback<
        Lightning.Element<
            Lightning.Element.TemplateSpecLoose,
            Lightning.Element.TypeConfigLoose,
        >,
    >

Callback called before the Element's flexbox layout is updated.

Note: This property will always return undefined when read.

p:
    | null
    | Lightning.Element<
        Lightning.Element.TemplateSpecLoose,
        Lightning.Element.TypeConfigLoose,
    >

Alias of parent

parent:
    | null
    | Lightning.Element<
        Lightning.Element.TemplateSpecLoose,
        Lightning.Element.TypeConfigLoose,
    >

Parent Element of this Element

pivot: number

Rotational Pivot Position

Controls the pivot that the rotation property rotates around along both the horizontal and vertical axis. Can be any floating point number between 0.0 and 1.0.

Examples

  • 0.0 = top-left
  • 0.5 (default) = center
  • 1.0 = bottom-right
0.5
pivotX: number

Rotational Pivot Position (horizonal axis)

Controls the pivot that the rotation property rotates around along the horizontal axis. Can be any floating point number between 0.0 and 1.0.

Examples

  • 0.0 = left
  • 0.5 (default) = center
  • 1.0 = right
0.5
pivotY: number

Rotational Pivot Position (vertical axis)

Controls the pivot that the rotation property rotates around along both the vertical axes. Can be any floating point number between 0.0 and 1.0.

Examples

  • 0.0 = top
  • 0.5 (default) = center
  • 1.0 = bottom
0.5
rect: boolean

Rectangle texture mode

When set, this Element adopts a RectangleTexture as its Texture and displays a rectangle colored by the various color* properties.

Cannot be set at the same time as src or text.

See Texture Types for more information.

false
ref: undefined | string

Element's reference key

renderHeight: number
renderOffscreen: boolean

Forces the Element's contents to be rendered to an offscreen frame buffer. If set to true, the Element will not be drawn onto the screen.

You can use this offscreen texture as a sampler for drawing other elements. So, renderToTexture must be set to true for this to work.

renderToTexture: boolean

rtt

renderWidth: number
rotation: number

Rotation Transform (in radians)

Rotates this Element around the pivot (defined by pivot, pivotX, and pivotY).

  • 0.0 = No rotation
  • Math.PI / 2 = 90 degree rotation
  • Math.PI = 180 degree rotation
  • Math.PI * 3 / 2 = 270 degree rotation
  • Math.PI * 2 = 360 degree rotation (same as no rotation)
0.0
rtt: boolean

If set to true, enables Render-to-Texture mode on this Element

Render-to-Texture renders the children of this element to a seperate texture before rendering it to screen. This allows shader effects to work on an entire component as well as enabling advanced transformations (like rotations).

false

rttLazy: boolean

Determines if the texture is always updated or only when necessary

false

scale: number

Scale Tranform

Stretches or shrinks this Element along both the horizontal and vertical axes.

1.0
scaleX: number

Scale Horizontal Tranform

Stretches or shrinks this Element along the horizontal axis.

1.0
scaleY: number

Scale Vertical Tranform

Stretches or shrinks this Element along the vertical axis.

1.0
src: undefined | string

Image source URI

When set, this Element adopts an ImageTexture as its Texture and loads/displays the image located at the URI.

Cannot be set at the same time as rect or text.

See Texture Types for more information.

Application's Global Stage

tagRoot: boolean

Creates a tag context

Tagged Elements in this branch will not be reachable from ancestors of this Element.

false
texturizer: ElementTexturizer
visible: boolean

Defines the visibility of this Element and its descendents.

  • If set to true (default):
    • This Element is rendered.
  • If set to false:
    • This Element is not rendered and its space in a Flex Box layout is collapsed.

If an element is invisible, the off-screen Elements are invisible as well, so you do not have to hide those manually to maintain a good performance.

This property takes prescendence over the alpha property.

true
withinBoundsMargin: boolean

true if Element is within the bounds margin

zIndex: number

Z-index

See Z-Indexing for more information.

0

Accessors

  • get h(): number
  • Height of this Element

    Returns number

  • set h(h: number | (parentHeight: number) => number): void
  • Height of this Element

    Parameters

    • h: number | (parentHeight: number) => number

    Returns void

    If set with a method the value is made dynamic based on the parent Element's height.

    0
    
  • set smooth(object: SmoothTemplate<TemplateSpecType>): void
  • Starts a smooth transition for all the included properties of the object

    Parameters

    Returns void

    This is the same as calling Element.setSmooth for each property.

    For each property:

    • If the value is a number:
      • Property value to smoothly transition to (using the default transition)
    • If the value is a 2-value array:
      • array[0] = Property value to smoothly transition to
      • array[1] = Settings describing the transition

    WARNING: DO NOT read from this property. It is WRITE-ONLY. It will always return undefined.

  • get w(): number
  • Width of this Element

    Returns number

  • set w(w: number | (parentWidth: number) => number): void
  • Width of this Element

    Parameters

    • w: number | (parentWidth: number) => number

    Returns void

    If set with a method the value is made dynamic based on the parent Element's width.

    0
    
  • get x(): number
  • X position of this Element

    Returns number

  • set x(x: number | (parentWidth: number) => number): void
  • X position of this Element

    Parameters

    • x: number | (parentWidth: number) => number

    Returns void

    If set with a method the value is made dynamic based on the parent Element's width.

    0
    
  • get y(): number
  • Y position of this Element

    Returns number

  • set y(y: number | (parentHeight: number) => number): void
  • Y position of this Element

    Parameters

    • y: number | (parentHeight: number) => number

    Returns void

    If set with a method the value is made dynamic based on the parent Element's height.

    0
    

Methods

  • Synchronously calls each of the listeners registered for the event named name, in the order they were registered, passing the supplied arguments to each.

    Type Parameters

    • EventName extends string | number | symbol

    Parameters

    Returns void

  • Fast-forward a currently transitioning property to its target value immediately.

    Type Parameters

    • Key extends string | number | symbol

    Parameters

    Returns void

    This method also supports providing a property path (i.e. 'texture.x'). To do this within a strongly typed Element / Component you can do so with an explicit as any.

    strongElement.fastForward('texture.x' as any);
    
  • Force re-create of render texture and re-invoke shader

    Returns void

  • Gets the ancestor of this Element that has the depth of depth in the render tree.

    • If depth === 0:
      • Will return the root Element (generally the Application)
    • If depth === 1:
      • Will return the ancestor that is the child of the root Element
    • If depth === this.getDepth()
      • Will return this Element

    Parameters

    • depth: number

      Depth in the render tree from the root Element

    Returns void

  • Get the corner points of this Element

    Format:

    [
    topLeftX, topLeftY,
    topRightX, topRightY,
    bottomRightX, bottomRight,
    bottomLeftX, bottomLeftY
    ]

    Returns [number, number, number, number, number, number, number, number]

  • Gets the number of levels deep this Element is in the render tree.

    Returns number

  • Get the location identifier of this Element

    Returns string

  • Get the current target value of an active transition.

    • If property is not actively transitioning:
      • Returns value, if provided.
      • Otherwise, returns undefined.

    Type Parameters

    • Key extends string | number | symbol

    Parameters

    Returns undefined | Extract<TemplateSpecType[Key], AnimatableValueTypes>

    This method also supports providing a property path (i.e. 'texture.x'). To do this within a strongly typed Element / Component you can do so with an explicit as any.

    strongElement.getSmooth('texture.x' as any);
    
  • Get the current target value of an active transition.

    • If property is not actively transitioning:
      • Returns value, if provided.
      • Otherwise, returns undefined.

    Type Parameters

    • Key extends string | number | symbol
    • Value extends any

    Parameters

    Returns ReduceSpecificity<Value, AnimatableValueTypes>

    This method also supports providing a property path (i.e. 'texture.x'). To do this within a strongly typed Element / Component you can do so with an explicit as any.

    strongElement.getSmooth('texture.x' as any);
    
  • Returns one of the Elements from the subtree that has this tag path.

    Type Parameters

    • Path extends string | number | symbol

    Parameters

    • tagName: Path

      . separated tag path

    Returns undefined | TemplateSpecTags<TemplateSpecType>[Path]

    Using getByRef may be slightly more performant, but only works one level at a time.

    In strongly typed Components, only fully qualified paths are supported in a type-safe way (i.e. 'MyChild.MyGrandChild.MyGreatGrandChild'). If you'd like to reference a deep element by its ref name (i.e. just 'MyGreatGrandChild') you can opt into this by asserting as any:

    // No error and is typed
    this.tag('MyChild.MyGrandChild.MyGreatGrandChild')
    // Needs `any` assertion and is typed as `any`
    this.tag('MyGreatGrandChild' as any)

    See Tags for more information.

  • Retruns true if a texture is currently loaded in this Element

    Returns boolean