Interface TemplateSpec<ContentType>

Base strongly-typed TemplateSpec for a Component

Example

If you inherit from this, follow this example closely:

export interface MyComponentTemplateSpec extends lng.Component.TemplateSpec {
  myProperty1: number;
  myProperty2: string;
  // ^----- Your properties should not be optional (so TS can enforce that they are implemented in your Component)
  MyChildComponent: typeof MyChildComponent
  // ^----- Child components should be typed by their `typeof` types
  MyChildElement: object
  // ^----- Child elements, which contain no children, should inserted with `object`
  MyChildInlineElementType: {
    ElementChild1: object;
    ElementChild2: typeof MyCoolComponent;
  };
  // ^----- Child elements, which have children of their own, are inserted with an inline-object type
  content: Element.PatchTemplate<Element.TemplateSpecLoose>;
  // ^----- If your Component has a property that when set, patches
  //        the value into itself, use `PatchTemplate<ComponentTemplateSpecType>`
}

interface TemplateSpec<
    ContentType extends Lightning.Element = Lightning.Element,
> {
    alpha: number;
    amount: number;
    boundsMargin: null | [number, number, number, number];
    children:
        | Lightning.Element<
            Lightning.Element.TemplateSpecLoose,
            Lightning.Element.TypeConfigLoose,
        >[]
        | { [id: string]: any }[];
    clipbox: boolean;
    clipping: boolean;
    collision: boolean;
    color: number;
    colorBl: number;
    colorBottom: number;
    colorBr: number;
    colorizeResultTexture: boolean;
    colorLeft: number;
    colorRight: number;
    colorTop: number;
    colorUl: number;
    colorUr: number;
    content: PatchTemplate<Lightning.Element.ExtractTemplateSpec<ContentType>>;
    cursor: undefined | string;
    flex: Flex;
    flexItem: false | FlexItem;
    forceZIndexContext: boolean;
    h: number | (parentHeight: number) => number;
    mh: number;
    mount: number;
    mountX: number;
    mountY: number;
    mw: number;
    onAfterCalcs:
        | undefined
        | null
        | OnAfterCalcsCallback<
            Lightning.Element<
                Lightning.Element.TemplateSpecLoose,
                Lightning.Element.TypeConfigLoose,
            >,
        >;
    onAfterUpdate: | undefined
    | null
    | OnAfterUpdateCallback<
        Lightning.Element<
            Lightning.Element.TemplateSpecLoose,
            Lightning.Element.TypeConfigLoose,
        >,
    >;
    onUpdate: | undefined
    | null
    | OnUpdateCallback<
        Lightning.Element<
            Lightning.Element.TemplateSpecLoose,
            Lightning.Element.TypeConfigLoose,
        >,
    >;
    paddingX: number;
    paddingY: number;
    passSignals: __PassSignals<Lightning.Component.SignalMap>;
    pivot: number;
    pivotX: number;
    pivotY: number;
    rect: boolean;
    ref: undefined | string;
    renderOffscreen: boolean;
    renderToTexture: boolean;
    rotation: number;
    rtt: boolean;
    rttLazy: boolean;
    scale: number;
    scaleX: number;
    scaleY: number;
    shader:
        | null
        | Lightning.types.Shader
        | Lightning.types.Shader.SettingsLoose;
    signals: __Signals<Lightning.Component.SignalMap>;
    smooth: SmoothTemplate<Lightning.Element.TemplateSpec>;
    src: undefined | string;
    tagRoot: boolean;
    text: null | string | Lightning.textures.TextTexture.Settings;
    texture: null | Lightning.Texture.SettingsLoose | Lightning.Texture;
    transitions: TransitionsTemplate<Lightning.Element.TemplateSpec>;
    visible: boolean;
    w: number | (parentWidth: number) => number;
    x: number | (parentWidth: number) => number;
    y: number | (parentHeight: number) => number;
    zIndex: number;
}

Type Parameters

ContentType extends Lightning.Element = Lightning.Element

Hierarchy (View Summary)

Lightning.Component.TemplateSpec
- TemplateSpec

Properties

alpha

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).

Remarks

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.

Default Value

1.0

amount

amount: number

Sets the amount of blur. A value between 0 and 4. Goes up exponentially for blur. Best results for non-fractional values.

boundsMargin

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.

Remarks

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.

Default Value

null

children

children:
    | Lightning.Element<
        Lightning.Element.TemplateSpecLoose,
        Lightning.Element.TypeConfigLoose,
    >[]
    | { [id: string]: any }[]

Set the children of this Element

clipbox

clipbox: boolean

Clipbox

Remarks

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.

Default Value

true

clipping

clipping: boolean

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

Remarks

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.

Default Value

false

collision

collision: boolean

Mouse pointer collision

Remarks

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

color

color: number

Rectangle Color

Remarks

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

colorBl: number

Bottom-left Corner Rectangle Color

See

color

colorBottom

colorBottom: number

Bottom Side Rectangle Color

See

color

colorBr

colorBr: number

Bottom-right Corner Rectangle Color

See

color

colorizeResultTexture

colorizeResultTexture: boolean

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

Remarks

This property has no effect if rtt is not enabled.

colorLeft

colorLeft: number

Left Side Rectangle Color

See

color

colorRight

colorRight: number

Right Side Rectangle Color

See

color

colorTop

colorTop: number

Top Side Rectangle Color

See

color

colorUl

colorUl: number

Upper-left Corner Rectangle Color

See

color

colorUr

colorUr: number

Upper-right Corner Rectangle Color

See

color

content

content: PatchTemplate<Lightning.Element.ExtractTemplateSpec<ContentType>>

Content can be any Element / Component

It is patched into the BloomComponent

cursor

cursor: undefined | string

Hover cursor

Remarks

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

See PR #356 for more information on this feature.

Default Value

undefined (no cursor)

flex

flex: Flex

Flexbox container properties

Remarks

See Flexbox documentation for more information.

flexItem

flexItem: false | FlexItem

Flexbox item properties

Remarks

See Flexbox documentation for more information.

forceZIndexContext

forceZIndexContext: boolean

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

Remarks

See Z-Indexing for more information.

Default Value

false

h

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

Height of this Element

Remarks

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

Default Value

mh

mh: number

The maximum expected texture source height.

Remarks

Used for within bounds determination while texture is not yet loaded.

If not set, 2048 is used by ElementCore.update()

mount

mount: number

Texture mountpoint

Remarks

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

Default

mountX

mountX: number

Texture mountpoint on horizontal axis

Remarks

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

Default Value

0.0

mountY

mountY: number

Texture mountpoint on vertical axis

Remarks

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

Default Value

0.0

mw

mw: number

The maximum expected texture source width.

Remarks

Used for within bounds determination while texture is not yet loaded.

If not set, 2048 is used by ElementCore.update()

onAfterCalcs

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

???

Remarks

After Calcs may change render coords, scissor and/or recBoundsMargin.

onAfterUpdate

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

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

onUpdate

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

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

paddingX

paddingX: number

X Padding

paddingY

paddingY: number

Y Padding

passSignals

passSignals: __PassSignals<Lightning.Component.SignalMap>

Gets/sets the Pass Signals for this Component.

Remarks

See Pass Signals for more information.

pivot

pivot: number

Rotational Pivot Position

Remarks

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

Default Value

0.5

pivotX

pivotX: number

Rotational Pivot Position (horizonal axis)

Remarks

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

Default Value

0.5

pivotY

pivotY: number

Rotational Pivot Position (vertical axis)

Remarks

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

Default Value

0.5

rect

rect: boolean

Rectangle texture mode

Remarks

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.

Default Value

false

See

ref

ref: undefined | string

Element's reference key

renderOffscreen

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.

Remarks

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

renderToTexture: boolean

See

rtt

rotation

rotation: number

Rotation Transform (in radians)

Remarks

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)

Default Value

0.0

rtt

rtt: boolean

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

Remarks

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).

Default Value

false

rttLazy

rttLazy: boolean

Determines if the texture is always updated or only when necessary

Default Value

false

scale

scale: number

Scale Tranform

Remarks

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

Default Value

1.0

scaleX

scaleX: number

Scale Horizontal Tranform

Remarks

Stretches or shrinks this Element along the horizontal axis.

Default Value

1.0

scaleY

scaleY: number

Scale Vertical Tranform

Remarks

Stretches or shrinks this Element along the vertical axis.

Default Value

1.0

shader

shader: null | Lightning.types.Shader | Lightning.types.Shader.SettingsLoose

Set a shader on this Element

signals

signals: __Signals<Lightning.Component.SignalMap>

Sets the Signals for this Component.

Remarks

See (Signals)[https://lightningjs.io/docs/#/lightning-core-reference/Communication/Signal?id=signal] for more information.

smooth

smooth: SmoothTemplate<Lightning.Element.TemplateSpec>

Starts a smooth transition for all the included properties of the object

Remarks

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

src

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.

Remarks

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

See Texture Types for more information.

tagRoot

tagRoot: boolean

Creates a tag context

Remarks

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

Default Value

false

text

text: null | string | Lightning.textures.TextTexture.Settings

Text settings / texture

Remarks

When set, the Element adopts a TextTexture and renders the text / settings laid out in this property.

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

See Texture Types for more information.

texture

texture: null | Lightning.Texture.SettingsLoose | Lightning.Texture

Set this Element's texture

Remarks

See Texture Types for more information.

transitions

transitions: TransitionsTemplate<Lightning.Element.TemplateSpec>

Setup one or more transitions

Remarks

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

visible

visible: boolean

Defines the visibility of this Element and its descendents.

Remarks

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.

Default Value

true

w

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

Width of this Element

Remarks

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

Default Value

x

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

X position of this Element

Remarks

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

Default Value

y

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

Y position of this Element

Remarks

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

Default Value

zIndex

zIndex: number

Z-index

Remarks

See Z-Indexing for more information.