Class: ElementComponent

pc.ElementComponent

Enables an Entity to be positioned using anchors and screen coordinates under a pc.ScreenComponent or under other ElementComponents. Depending on its type it can be used to render images, text or just as a layout mechanism to build 2D and 3D user interfaces. If the component is a descendant of a pc.ScreenComponent, then the Entity's pc.Entity.setLocalPosition is in the pc.ScreenComponent's coordinate system.

Constructor

new ElementComponent(system, entity)

Parameters:
Name Type Description
system pc.ElementComponentSystem The ComponentSystem that created this Component
entity pc.Entity The Entity that this Component is attached to.
Properties:
Name Type Description
type String The type of the ElementComponent. Can be one of the following:
  • pc.ELEMENTTYPE_GROUP: The component can be used as a layout mechanism to create groups of ElementComponents e.g. panels.
  • pc.ELEMENTTYPE_IMAGE: The component will render an image
  • pc.ELEMENTTYPE_TEXT: The component will render text
screen pc.Entity The Entity with a pc.ScreenComponent that this component belongs to. This is automatically set when the component is a child of a ScreenComponent.
drawOrder Number The draw order of the component. A higher value means that the component will be rendered on top of other components.
anchor pc.Vec4 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.
pivot pc.Vec2 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.
margin pc.Vec4 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.
left Number 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.
right Number 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.
bottom Number 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.
top Number 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.
width Number 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 pc.LayoutGroupComponent. See calculatedWidth in order to ensure you are reading the true width at which the element will be rendered.
height Number 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 pc.LayoutGroupComponent. See calculatedHeight in order to ensure you are reading the true height at which the element will be rendered.
calculatedWidth Number 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 pc.LayoutGroupComponent. In these scenarios, calculatedWidth may be smaller or larger than the width that was set in the editor.
calculatedHeight Number 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 pc.LayoutGroupComponent. In these scenarios, calculatedHeight may be smaller or larger than the height that was set in the editor.
screenCorners Array.<pc.Vec3> An array of 4 pc.Vec3s that represent the bottom left, bottom right, top right and top left corners of the component relative to its parent pc.ScreenComponent.
worldCorners Array.<pc.Vec3> An array of 4 pc.Vec3s that represent the bottom left, bottom right, top right and top left corners of the component in world space. Only works for 3D ElementComponents.
canvasCorners Array.<pc.Vec2> An array of 4 pc.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 ElementComponents.
useInput Boolean If true then the component will receive Mouse or Touch input events.
color pc.Color The color of the image for pc.ELEMENTTYPE_IMAGE types or the color of the text for pc.ELEMENTTYPE_TEXT types.
opacity Number The opacity of the image for pc.ELEMENTTYPE_IMAGE types or the text for pc.ELEMENTTYPE_TEXT types.
outlineColor pc.Color The text outline effect color and opacity. Only works for pc.ELEMENTTYPE_TEXT types.
outlineThickness Number The width of the text outline effect. Only works for pc.ELEMENTTYPE_TEXT types.
shadowColor pc.Color The text shadow effect color and opacity. Only works for pc.ELEMENTTYPE_TEXT types.
shadowOffset pc.Vec2 The text shadow effect shift amount from original text. Only works for pc.ELEMENTTYPE_TEXT types.
textWidth Number The width of the text rendered by the component. Only works for pc.ELEMENTTYPE_TEXT types.
textHeight Number The height of the text rendered by the component. Only works for pc.ELEMENTTYPE_TEXT types.
autoWidth Number Automatically set the width of the component to be the same as the textWidth. Only works for pc.ELEMENTTYPE_TEXT types.
autoHeight Number Automatically set the height of the component to be the same as the textHeight. Only works for pc.ELEMENTTYPE_TEXT types.
fontAsset Number The id of the font asset used for rendering the text. Only works for pc.ELEMENTTYPE_TEXT types.
font pc.Font The font used for rendering the text. Only works for pc.ELEMENTTYPE_TEXT types.
fontSize Number The size of the font. Only works for pc.ELEMENTTYPE_TEXT types.
autoFitWidth Boolean 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.
autoFitHeight Boolean 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.
minFontSize Number The minimum size that the font can scale to when autoFitWidth or autoFitHeight are true.
maxFontSize Number The maximum size that the font can scale to when autoFitWidth or autoFitHeight are true.
spacing Number The spacing between the letters of the text. Only works for pc.ELEMENTTYPE_TEXT types.
lineHeight Number The height of each line of text. Only works for pc.ELEMENTTYPE_TEXT types.
wrapLines Boolean Whether to automatically wrap lines based on the element width. Only works for pc.ELEMENTTYPE_TEXT types, and when autoWidth is set to false.
maxLines Number 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.
alignment pc.Vec2 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 pc.ELEMENTTYPE_TEXT types.
text String The text to render. Only works for pc.ELEMENTTYPE_TEXT types.
key String The localization key to use to get the localized text from pc.Application#i18n. Only works for pc.ELEMENTTYPE_TEXT types.
textureAsset Number The id of the texture asset to render. Only works for pc.ELEMENTTYPE_IMAGE types.
texture pc.Texture The texture to render. Only works for pc.ELEMENTTYPE_IMAGE types.
spriteAsset Number The id of the sprite asset to render. Only works for pc.ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.
sprite pc.Sprite The sprite to render. Only works for pc.ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.
spriteFrame Number The frame of the sprite to render. Only works for pc.ELEMENTTYPE_IMAGE types who have a sprite assigned.
pixelsPerUnit Number The number of pixels that map to one PlayCanvas unit. Only works for pc.ELEMENTTYPE_IMAGE types who have a sliced sprite assigned.
materialAsset Number The id of the material asset to use when rendering an image. Only works for pc.ELEMENTTYPE_IMAGE types.
material pc.Material The material to use when rendering an image. Only works for pc.ELEMENTTYPE_IMAGE types.
rect pc.Vec4 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 pc.ELEMENTTYPE_IMAGE types.
rtlReorder Boolean Reorder the text for RTL languages using a function registered by app.systems.element.registerUnicodeConverter.
unicodeConverter Boolean Convert unicode characters using a function registered by app.systems.element.registerUnicodeConverter.
batchGroupId Number Assign element to a specific batch group (see pc.BatchGroup). Default value is -1 (no group).
layers Array An array of layer IDs (pc.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.
enableMarkup Boolean Flag for enabling markup processing. Only works for pc.ELEMENTTYPE_TEXT types.
rangeStart Number Index of the first character to render. Only works for pc.ELEMENTTYPE_TEXT types.
rangeEnd Number Index of the last character to render. Only works for pc.ELEMENTTYPE_TEXT types.
Source:

Extends

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:
Name Type Description
event pc.ElementMouseEvent | pc.ElementTouchEvent The event
Source:

mousedown

Fired when the mouse is pressed while the cursor is on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementMouseEvent The event
Source:

mouseenter

Fired when the mouse cursor enters the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementMouseEvent The event
Source:

mouseleave

Fired when the mouse cursor leaves the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementMouseEvent The event
Source:

mousemove

Fired when the mouse cursor is moved on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementMouseEvent The event
Source:

mouseup

Fired when the mouse is released while the cursor is on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementMouseEvent The event
Source:

mousewheel

Fired when the mouse wheel is scrolled on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementMouseEvent The event
Source:

touchcancel

Fired when a touch is cancelled on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementTouchEvent The event
Source:

touchend

Fired when a touch ends on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementTouchEvent The event
Source:

touchmove

Fired when a touch moves after it started touching the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementTouchEvent The event
Source:

touchstart

Fired when a touch starts on the component. Only fired when useInput is true.
Parameters:
Name Type Description
event pc.ElementTouchEvent The event
Source: