Class ElementComponent

ElementComponents are used to construct user interfaces. The ElementComponent#type property can be configured in 3 main ways: as a text element, as an image element or as a group element. If the ElementComponent has a ScreenComponent ancestor in the hierarchy, it will be transformed with respect to the coordinate system of the screen. If there is no ScreenComponent ancestor, the ElementComponent will be transformed like any other entity.

You should never need to use the ElementComponent constructor. To add an ElementComponent to a Entity, use Entity#addComponent:

// Add an element component to an entity with the default options
const entity = pc.Entity();
entity.addComponent("element"); // This defaults to a 'group' element

To create a simple text-based element:

entity.addComponent("element", {
    anchor: new pc.Vec4(0.5, 0.5, 0.5, 0.5), // centered anchor
    fontAsset: fontAsset,
    fontSize: 128,
    pivot: new pc.Vec2(0.5, 0.5),            // centered pivot
    text: "Hello World!",
    type: pc.ELEMENTTYPE_TEXT
});

Once the ElementComponent is added to the entity, you can set and get any of its properties:

entity.element.color = pc.Color.RED; // Set the element's color to red

console.log(entity.element.color);   // Get the element's color and print it

Relevant 'Engine-only' examples:

Hierarchy (view full)

Constructors

constructor

Properties

entity screen system

Accessors

aabb alignment anchor autoFitHeight autoFitWidth autoHeight autoWidth batchGroupId bottom calculatedHeight calculatedWidth canvasCorners color drawOrder enableMarkup enabled fitMode font fontAsset fontSize height key layers left lineHeight margin mask material materialAsset maxFontSize maxLines minFontSize opacity outlineColor outlineThickness pivot pixelsPerUnit rangeEnd rangeStart rect right rtlReorder screenCorners shadowColor shadowOffset spacing sprite spriteAsset spriteFrame text textHeight textWidth texture textureAsset top type unicodeConverter useInput width worldCorners wrapLines

Methods

fire hasEvent off on once

Events

EVENT_CLICK EVENT_MOUSEDOWN EVENT_MOUSEENTER EVENT_MOUSELEAVE EVENT_MOUSEMOVE EVENT_MOUSEUP EVENT_MOUSEWHEEL EVENT_TOUCHCANCEL EVENT_TOUCHEND EVENT_TOUCHMOVE EVENT_TOUCHSTART

Constructors

constructor

Properties

entity

entity: Entity

The Entity that this Component is attached to.

screen

screen: Entity

The Entity with a ScreenComponent that this component belongs to. This is automatically set when the component is a child of a ScreenComponent.

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Accessors

aabb

alignment

anchor

  • get anchor(): number[] | Vec4

  • Gets the anchor for this element component.

    Returns number[] | Vec4

  • set anchor(value): void

  • Sets the anchor for this element component. Specifies where the left, bottom, right and top edges of the component are anchored relative to its parent. Each value ranges from 0 to 1. e.g. a value of [0, 0, 0, 0] means that the element will be anchored to the bottom left of its parent. A value of [1, 1, 1, 1] means it will be anchored to the top right. A split anchor is when the left-right or top-bottom pairs of the anchor are not equal. In that case, the component will be resized to cover that entire area. For example, a value of [0, 0, 1, 1] will make the component resize exactly as its parent.

    Parameters

    • value: number[] | Vec4

    Returns void

    Example

    this.entity.element.anchor = new pc.Vec4(Math.random() * 0.1, 0, 1, 0);

    Example

    this.entity.element.anchor = [Math.random() * 0.1, 0, 1, 0];

autoFitHeight

autoFitWidth

autoHeight

autoWidth

batchGroupId

bottom

calculatedHeight

calculatedWidth

canvasCorners

color

drawOrder

enableMarkup

enabled

fitMode

font

fontAsset

fontSize

height

key

layers

left

lineHeight

margin

mask

material

materialAsset

maxFontSize

maxLines

minFontSize

opacity

outlineColor

outlineThickness

pivot

  • get pivot(): number[] | Vec2

  • Gets the position of the pivot of the component relative to its anchor.

    Returns number[] | Vec2

  • set pivot(value): void

  • Sets the position of the pivot of the component relative to its anchor. Each value ranges from 0 to 1 where [0, 0] is the bottom left and [1, 1] is the top right.

    Parameters

    • value: number[] | Vec2

    Returns void

    Example

    this.entity.element.pivot = [Math.random() * 0.1, Math.random() * 0.1];

    Example

    this.entity.element.pivot = new pc.Vec2(Math.random() * 0.1, Math.random() * 0.1);

pixelsPerUnit

rangeEnd

rangeStart

rect

right

rtlReorder

screenCorners

shadowColor

shadowOffset

spacing

sprite

spriteAsset

spriteFrame

text

  • get text(): string

  • Gets the text to render.

    Returns string

  • set text(arg): void

  • Sets the text to render. Only works for ELEMENTTYPE_TEXT types. To override certain text styling properties on a per-character basis, the text can optionally include markup tags contained within square brackets. Supported tags are:

    1. color - override the element's color property. Examples:
      • [color="#ff0000"]red text[/color]
      • [color="#00ff00"]green text[/color]
      • [color="#0000ff"]blue text[/color]
    2. outline - override the element's outlineColor and outlineThickness properties. Example:
      • [outline color="#ffffff" thickness="0.5"]text[/outline]
    3. shadow - override the element's shadowColor and shadowOffset properties. Examples:
      • [shadow color="#ffffff" offset="0.5"]text[/shadow]
      • [shadow color="#000000" offsetX="0.1" offsetY="0.2"]text[/shadow]

    Note that markup tags are only processed if the text element's enableMarkup property is set to true.

    Parameters

    • arg: string

    Returns void

textHeight

textWidth

texture

textureAsset

top

type

unicodeConverter

useInput

width

worldCorners

wrapLines

Methods

fire

  • fire(name, arg1?, arg2?, arg3?, arg4?, arg5?, arg6?, arg7?, arg8?): EventHandler

  • Fire an event, all additional arguments are passed on to the event listener.

    Parameters

    • name: string

      Name of event to fire.

    • Optionalarg1: any

      First argument that is passed to the event handler.

    • Optionalarg2: any

      Second argument that is passed to the event handler.

    • Optionalarg3: any

      Third argument that is passed to the event handler.

    • Optionalarg4: any

      Fourth argument that is passed to the event handler.

    • Optionalarg5: any

      Fifth argument that is passed to the event handler.

    • Optionalarg6: any

      Sixth argument that is passed to the event handler.

    • Optionalarg7: any

      Seventh argument that is passed to the event handler.

    • Optionalarg8: any

      Eighth argument that is passed to the event handler.

    Returns EventHandler

    Self for chaining.

    Example

    obj.fire('test', 'This is the message');

hasEvent

  • hasEvent(name): boolean

  • Test if there are any handlers bound to an event name.

    Parameters

    • name: string

      The name of the event to test.

    Returns boolean

    True if the object has handlers bound to the specified event name.

    Example

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

off

  • off(name?, callback?, scope?): EventHandler

  • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

    Parameters

    • Optionalname: string

      Name of the event to unbind.

    • Optionalcallback: HandleEventCallback

      Function to be unbound.

    • Optionalscope: object

      Scope that was used as the this when the event is fired.

    Returns EventHandler

    Self for chaining.

    Example

    const handler = function () {
    };
    obj.on('test', handler);

    obj.off(); // Removes all events
    obj.off('test'); // Removes all events called 'test'
    obj.off('test', handler); // Removes all handler functions, called 'test'
    obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

on

  • on(name, callback, scope?): EventHandle

  • Attach an event handler to an event.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    Can be used for removing event in the future.

    Example

    obj.on('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Example

    const evt = obj.on('test', function (a, b) {
        console.log(a + b);
    });
    // some time later
    evt.off();

once

  • once(name, callback, scope?): EventHandle

  • Attach an event handler to an event. This handler will be removed after being fired once.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    • can be used for removing event in the future.

    Example

    obj.once('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    obj.fire('test', 1, 2); // not going to get handled

Events

StaticEVENT_CLICK

EVENT_CLICK: string = 'click'

Fired when the mouse is pressed and released on the component or when a touch starts and ends on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent or ElementTouchEvent.

Example

entity.element.on('click', (event) => {
    console.log(`Click event on entity ${entity.name}`);
});

StaticEVENT_MOUSEDOWN

EVENT_MOUSEDOWN: string = 'mousedown'

Fired when the mouse is pressed while the cursor is on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mousedown', (event) => {
    console.log(`Mouse down event on entity ${entity.name}`);
});

StaticEVENT_MOUSEENTER

EVENT_MOUSEENTER: string = 'mouseenter'

Fired when the mouse cursor enters the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mouseenter', (event) => {
    console.log(`Mouse enter event on entity ${entity.name}`);
});

StaticEVENT_MOUSELEAVE

EVENT_MOUSELEAVE: string = 'mouseleave'

Fired when the mouse cursor leaves the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mouseleave', (event) => {
    console.log(`Mouse leave event on entity ${entity.name}`);
});

StaticEVENT_MOUSEMOVE

EVENT_MOUSEMOVE: string = 'mousemove'

Fired when the mouse cursor is moved on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mousemove', (event) => {
    console.log(`Mouse move event on entity ${entity.name}`);
});

StaticEVENT_MOUSEUP

EVENT_MOUSEUP: string = 'mouseup'

Fired when the mouse is released while the cursor is on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mouseup', (event) => {
    console.log(`Mouse up event on entity ${entity.name}`);
});

StaticEVENT_MOUSEWHEEL

EVENT_MOUSEWHEEL: string = 'mousewheel'

Fired when the mouse wheel is scrolled on the component. Only fired when useInput is true. The handler is passed an ElementMouseEvent.

Example

entity.element.on('mousewheel', (event) => {
    console.log(`Mouse wheel event on entity ${entity.name}`);
});

StaticEVENT_TOUCHCANCEL

EVENT_TOUCHCANCEL: string = 'touchcancel'

Fired when a touch is canceled on the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchcancel', (event) => {
    console.log(`Touch cancel event on entity ${entity.name}`);
});

StaticEVENT_TOUCHEND

EVENT_TOUCHEND: string = 'touchend'

Fired when a touch ends on the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchend', (event) => {
    console.log(`Touch end event on entity ${entity.name}`);
});

StaticEVENT_TOUCHMOVE

EVENT_TOUCHMOVE: string = 'touchmove'

Fired when a touch moves after it started touching the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchmove', (event) => {
    console.log(`Touch move event on entity ${entity.name}`);
});

StaticEVENT_TOUCHSTART

EVENT_TOUCHSTART: string = 'touchstart'

Fired when a touch starts on the component. Only fired when useInput is true. The handler is passed an ElementTouchEvent.

Example

entity.element.on('touchstart', (event) => {
    console.log(`Touch start event on entity ${entity.name}`);
});

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods
Events