ElementComponent
Extends: Component
ElementComponents are used to construct user interfaces. An ElementComponent's 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
let 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:
- Basic text rendering
- Rendering text outlines
- Adding drop shadows to text
- Coloring text with markup
- Wrapping text
- Typewriter text
Summary
Properties
alignment | The horizontal and vertical alignment of the text. |
anchor | Specifies where the left, bottom, right and top edges of the component are anchored relative to its parent. |
autoFitHeight | When true the font size and line height will scale so that the text fits inside the height of the Element. |
autoFitWidth | When true the font size and line height will scale so that the text fits inside the width of the Element. |
autoHeight | Automatically set the height of the component to be the same as the textHeight. |
autoWidth | Automatically set the width of the component to be the same as the textWidth. |
batchGroupId | Assign element to a specific batch group (see BatchGroup). |
bottom | The distance from the bottom edge of the anchor. |
calculatedHeight | The height at which the element will be rendered. |
calculatedWidth | The width at which the element will be rendered. |
canvasCorners | An array of 4 Vec2s that represent the bottom left, bottom right, top right and top left corners of the component in canvas pixels. |
color | The color of the image for ELEMENTTYPE_IMAGE types or the color of the text for ELEMENTTYPE_TEXT types. |
drawOrder | The draw order of the component. |
enableMarkup | Flag for enabling markup processing. |
fitMode | Set how the content should be fitted and preserve the aspect ratio of the source texture or sprite. |
font | The font used for rendering the text. |
fontAsset | The id of the font asset used for rendering the text. |
fontSize | The size of the font. |
height | The height of the element as set in the editor. |
key | The localization key to use to get the localized text from Application#i18n. |
layers | An array of layer IDs (Layer#id) to which this element should belong. |
left | The distance from the left edge of the anchor. |
lineHeight | The height of each line of text. |
margin | The distance from the left, bottom, right and top edges of the anchor. |
mask | Switch Image Element into a mask. |
material | The material to use when rendering an image. |
materialAsset | The id of the material asset to use when rendering an image. |
maxFontSize | The maximum size that the font can scale to when autoFitWidth or autoFitHeight are true. |
maxLines | The maximum number of lines that the Element can wrap to. |
minFontSize | The minimum size that the font can scale to when autoFitWidth or autoFitHeight are true. |
opacity | The opacity of the image for ELEMENTTYPE_IMAGE types or the text for ELEMENTTYPE_TEXT types. |
outlineColor | The text outline effect color and opacity. |
outlineThickness | The width of the text outline effect. |
pivot | The position of the pivot of the component relative to its anchor. |
pixelsPerUnit | The number of pixels that map to one PlayCanvas unit. |
rangeEnd | Index of the last character to render. |
rangeStart | Index of the first character to render. |
rect | Specifies which region of the texture to use in order to render an image. |
right | The distance from the right edge of the anchor. |
rtlReorder | Reorder the text for RTL languages using a function registered
by |
screen | The Entity with a ScreenComponent that this component belongs to. |
screenCorners | An array of 4 Vec3s that represent the bottom left, bottom right, top right and top left corners of the component relative to its parent ScreenComponent. |
shadowColor | The text shadow effect color and opacity. |
shadowOffset | The text shadow effect shift amount from original text. |
spacing | The spacing between the letters of the text. |
sprite | The sprite to render. |
spriteAsset | The id of the sprite asset to render. |
spriteFrame | The frame of the sprite to render. |
text | The text to render. |
textHeight | The height of the text rendered by the component. |
textWidth | The width of the text rendered by the component. |
texture | The texture to render. |
textureAsset | The id of the texture asset to render. |
top | The distance from the top edge of the anchor. |
type | The type of the ElementComponent. |
unicodeConverter | Convert unicode characters using a function registered by
|
useInput | If true then the component will receive Mouse or Touch input events. |
width | The width of the element as set in the editor. |
worldCorners | An array of 4 Vec3s that represent the bottom left, bottom right, top right and top left corners of the component in world space. |
wrapLines | Whether to automatically wrap lines based on the element width. |
Events
click | Fired when the mouse is pressed and released on the component or when a touch starts and ends on the component. |
mousedown | Fired when the mouse is pressed while the cursor is on the component. |
mouseenter | Fired when the mouse cursor enters the component. |
mouseleave | Fired when the mouse cursor leaves the component. |
mousemove | Fired when the mouse cursor is moved on the component. |
mouseup | Fired when the mouse is released while the cursor is on the component. |
mousewheel | Fired when the mouse wheel is scrolled on the component. |
touchcancel | Fired when a touch is canceled on the component. |
touchend | Fired when a touch ends on the component. |
touchmove | Fired when a touch moves after it started touching the component. |
touchstart | Fired when a touch starts on the component. |
Inherited
Properties
enabled | Enables or disables the component. |
entity | The Entity that this Component is attached to. |
system | The ComponentSystem used to create this Component. |
Methods
fire | Fire an event, all additional arguments are passed on to the event listener. |
hasEvent | Test if there are any handlers bound to an event name. |
off | Detach an event handler from an event. |
on | Attach an event handler to an event. |
once | Attach an event handler to an event. |
Details
Constructor
ElementComponent(system, entity)
Create a new ElementComponent instance.
Parameters
system | ElementComponentSystem | The ComponentSystem that created this Component. |
entity | Entity | The Entity that this Component is attached to. |
Properties
The horizontal and vertical alignment of the text. Values range from 0 to 1 where [0,0] is the bottom left and [1,1] is the top right. Only works for ELEMENTTYPE_TEXT types.
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. e.g. a value of [0, 0, 1, 1] will make the component resize exactly as its parent.
pc.app.root.findByName("Inventory").element.anchor = new pc.Vec4(Math.random() * 0.1, 0, 1, 0);
pc.app.root.findByName("Inventory").element.anchor = [Math.random() * 0.1, 0, 1, 0];
When true the font size and line height will scale so that the text fits inside the height of the Element. The font size will be scaled between minFontSize and maxFontSize. The value of autoFitHeight will be ignored if autoHeight is true.
When true the font size and line height will scale so that the text fits inside the width of the Element. The font size will be scaled between minFontSize and maxFontSize. The value of autoFitWidth will be ignored if autoWidth is true.
Automatically set the height of the component to be the same as the textHeight. Only works for ELEMENTTYPE_TEXT types.
Automatically set the width of the component to be the same as the textWidth. Only works for ELEMENTTYPE_TEXT types.
Assign element to a specific batch group (see BatchGroup). Default is -1 (no group).
The distance from the bottom edge of the anchor. Can be used in combination with a split anchor to make the component's top edge always be 'top' units away from the top.
The height at which the element will be rendered. In most cases this will be the same as
height
. However, in some cases the engine may calculate a different height for the element,
such as when the element is under the control of a LayoutGroupComponent. In these
scenarios, calculatedHeight
may be smaller or larger than the height that was set in the
editor.
The width at which the element will be rendered. In most cases this will be the same as
width
. However, in some cases the engine may calculate a different width for the element,
such as when the element is under the control of a LayoutGroupComponent. In these
scenarios, calculatedWidth
may be smaller or larger than the width that was set in the
editor.
An array of 4 Vec2s that represent the bottom left, bottom right, top right and top left corners of the component in canvas pixels. Only works for screen space element components.
The color of the image for ELEMENTTYPE_IMAGE types or the color of the text for ELEMENTTYPE_TEXT types.
The draw order of the component. A higher value means that the component will be rendered on top of other components.
Flag for enabling markup processing. Only works for ELEMENTTYPE_TEXT types. Defaults to false.
Set how the content should be fitted and preserve the aspect ratio of the source texture or sprite. Only works for ELEMENTTYPE_IMAGE types.
The id of the font asset used for rendering the text. Only works for ELEMENTTYPE_TEXT types.
The height of the element as set in the editor. Note that in some cases this may not reflect
the true height at which the element is rendered, such as when the element is under the
control of a LayoutGroupComponent. See calculatedHeight
in order to ensure you are
reading the true height at which the element will be rendered.
The localization key to use to get the localized text from Application#i18n. Only works for ELEMENTTYPE_TEXT types.
An array of layer IDs (Layer#id) to which this element should belong. Don't push, pop, splice or modify this array, if you want to change it - set a new one instead.
The distance from the left edge of the anchor. Can be used in combination with a split anchor to make the component's left edge always be 'left' units away from the left.
The distance from the left, bottom, right and top edges of the anchor. For example if we are using a split anchor like [0,0,1,1] and the margin is [0,0,0,0] then the component will be the same width and height as its parent.
Switch Image Element into a mask. Masks do not render into the scene, but instead limit child elements to only be rendered where this element is rendered.
The material to use when rendering an image. Only works for ELEMENTTYPE_IMAGE types.
The id of the material asset to use when rendering an image. Only works for ELEMENTTYPE_IMAGE types.
The maximum size that the font can scale to when autoFitWidth or autoFitHeight are true.
The maximum number of lines that the Element can wrap to. Any leftover text will be appended to the last line. Set this to null to allow unlimited lines.
The minimum size that the font can scale to when autoFitWidth or autoFitHeight are true.
The opacity of the image for ELEMENTTYPE_IMAGE types or the text for ELEMENTTYPE_TEXT types.
The text outline effect color and opacity. Only works for ELEMENTTYPE_TEXT types.
The width of the text outline effect. Only works for ELEMENTTYPE_TEXT types.
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.
pc.app.root.findByName("Inventory").element.pivot = [Math.random() * 0.1, Math.random() * 0.1];
pc.app.root.findByName("Inventory").element.pivot = new pc.Vec2(Math.random() * 0.1, Math.random() * 0.1);
The number of pixels that map to one PlayCanvas unit. Only works for ELEMENTTYPE_IMAGE types who have a sliced sprite assigned.
Specifies which region of the texture to use in order to render an image. Values range from 0 to 1 and indicate u, v, width, height. Only works for ELEMENTTYPE_IMAGE types.
The distance from the right edge of the anchor. Can be used in combination with a split anchor to make the component's right edge always be 'right' units away from the right.
Reorder the text for RTL languages using a function registered
by app.systems.element.registerUnicodeConverter
.
The Entity with a ScreenComponent that this component belongs to. This is automatically set when the component is a child of a ScreenComponent.
An array of 4 Vec3s that represent the bottom left, bottom right, top right and top left corners of the component relative to its parent ScreenComponent.
The text shadow effect shift amount from original text. Only works for ELEMENTTYPE_TEXT types.
The sprite to render. Only works for ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.
The id of the sprite asset to render. Only works for ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.
The frame of the sprite to render. Only works for ELEMENTTYPE_IMAGE types who have a sprite assigned.
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:
color
- override the element'scolor
property. Examples:
[color="#ff0000"]red text[/color]
[color="#00ff00"]green text[/color]
[color="#0000ff"]blue text[/color]
outline
- override the element'soutlineColor
andoutlineThickness
properties. Example:
[outline color="#ffffff" thickness="0.5"]text[/outline]
shadow
- override the element'sshadowColor
andshadowOffset
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.
The height of the text rendered by the component. Only works for ELEMENTTYPE_TEXT types.
The width of the text rendered by the component. Only works for ELEMENTTYPE_TEXT types.
The distance from the top edge of the anchor. Can be used in combination with a split anchor to make the component's bottom edge always be 'bottom' units away from the bottom.
The type of the ElementComponent. Can be:
- ELEMENTTYPE_GROUP: The component can be used as a layout mechanism to create groups of ElementComponents e.g. panels.
- ELEMENTTYPE_IMAGE: The component will render an image
- ELEMENTTYPE_TEXT: The component will render text
Convert unicode characters using a function registered by
app.systems.element.registerUnicodeConverter
.
The width of the element as set in the editor. Note that in some cases this may not reflect
the true width at which the element is rendered, such as when the element is under the
control of a LayoutGroupComponent. See calculatedWidth
in order to ensure you are
reading the true width at which the element will be rendered.
An array of 4 Vec3s that represent the bottom left, bottom right, top right and top left corners of the component in world space. Only works for 3D element components.
Whether to automatically wrap lines based on the element width. Only works for ELEMENTTYPE_TEXT types, and when autoWidth is set to false.
Events
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.
Parameters
event | ElementMouseEvent, ElementTouchEvent | The event. |
mousedown
Fired when the mouse is pressed while the cursor is on the component. Only fired when useInput is true.
Parameters
event | ElementMouseEvent | The event. |
mouseenter
Fired when the mouse cursor enters the component. Only fired when useInput is true.
Parameters
event | ElementMouseEvent | The event. |
mouseleave
Fired when the mouse cursor leaves the component. Only fired when useInput is true.
Parameters
event | ElementMouseEvent | The event. |
mousemove
Fired when the mouse cursor is moved on the component. Only fired when useInput is true.
Parameters
event | ElementMouseEvent | The event. |
mouseup
Fired when the mouse is released while the cursor is on the component. Only fired when useInput is true.
Parameters
event | ElementMouseEvent | The event. |
mousewheel
Fired when the mouse wheel is scrolled on the component. Only fired when useInput is true.
Parameters
event | ElementMouseEvent | The event. |
touchcancel
Fired when a touch is canceled on the component. Only fired when useInput is true.
Parameters
event | ElementTouchEvent | The event. |
touchend
Fired when a touch ends on the component. Only fired when useInput is true.
Parameters
event | ElementTouchEvent | The event. |
touchmove
Fired when a touch moves after it started touching the component. Only fired when useInput is true.
Parameters
event | ElementTouchEvent | The event. |
touchstart
Fired when a touch starts on the component. Only fired when useInput is true.
Parameters
event | ElementTouchEvent | The event. |
Inherited
Properties
Methods
fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])
Fire an event, all additional arguments are passed on to the event listener.
obj.fire('test', 'This is the message');
Parameters
name | string | Name of event to fire. |
arg1 | * | First argument that is passed to the event handler. |
arg2 | * | Second argument that is passed to the event handler. |
arg3 | * | Third argument that is passed to the event handler. |
arg4 | * | Fourth argument that is passed to the event handler. |
arg5 | * | Fifth argument that is passed to the event handler. |
arg6 | * | Sixth argument that is passed to the event handler. |
arg7 | * | Seventh argument that is passed to the event handler. |
arg8 | * | Eighth argument that is passed to the event handler. |
Returns
EventHandlerSelf for chaining.
hasEvent(name)
Test if there are any handlers bound to an event name.
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
Parameters
name | string | The name of the event to test. |
Returns
booleanTrue if the object has handlers bound to the specified event name.
off([name], [callback], [scope])
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.
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
Parameters
name | string | Name of the event to unbind. |
callback | HandleEventCallback | Function to be unbound. |
scope | object | Scope that was used as the this when the event is fired. |
Returns
EventHandlerSelf for chaining.
on(name, callback, [scope])
Attach an event handler to an event.
obj.on('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
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. |
scope | object | Object to use as 'this' when the event is fired, defaults to current this. |
Returns
EventHandlerSelf for chaining.
once(name, callback, [scope])
Attach an event handler to an event. This handler will be removed after being fired once.
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
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. |
scope | object | Object to use as 'this' when the event is fired, defaults to current this. |
Returns
EventHandlerSelf for chaining.