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

Constructors

Properties

entity: Entity

The Entity that this Component is attached to.

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.

The ComponentSystem used to create this Component.

Accessors

  • get anchor(): number[] | Vec4
  • Gets the anchor for this element component.

    Returns number[] | Vec4

  • set anchor(value: number[] | Vec4): 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

    this.entity.element.anchor = new pc.Vec4(Math.random() * 0.1, 0, 1, 0);
    
    this.entity.element.anchor = [Math.random() * 0.1, 0, 1, 0];
    
  • get text(): string
  • Gets the text to render.

    Returns string

  • set text(arg: string): 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

Methods

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

    obj.fire('test', 'This is the message');
    
  • 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.

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false
  • 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.

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

    obj.on('test', function (a, b) {
    console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    const evt = obj.on('test', function (a, b) {
    console.log(a + b);
    });
    // some time later
    evt.off();
  • 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.
    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

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.

entity.element.on('click', (event) => {
console.log(`Click event on entity ${entity.name}`);
});
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.

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

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

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

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

entity.element.on('mouseleave', (event) => {
console.log(`Mouse leave event on entity ${entity.name}`);
});
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.

entity.element.on('mousemove', (event) => {
console.log(`Mouse move event on entity ${entity.name}`);
});
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.

entity.element.on('mouseup', (event) => {
console.log(`Mouse up event on entity ${entity.name}`);
});
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.

entity.element.on('mousewheel', (event) => {
console.log(`Mouse wheel event on entity ${entity.name}`);
});
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.

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

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

entity.element.on('touchend', (event) => {
console.log(`Touch end event on entity ${entity.name}`);
});
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.

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

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

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