API Reference

Class List

pc.ElementComponent

Extends: pc.Component

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.

Summary

Properties

alignmentThe horizontal and vertical alignment of the text.
anchorSpecifies where the left, bottom, right and top edges of the component are anchored relative to its parent.
autoHeightAutomatically set the height of the component to be the same as the textHeight.
autoWidthAutomatically set the width of the component to be the same as the textWidth.
batchGroupIdAssign element to a specific batch group (see pc.BatchGroup).
bottomThe distance from the bottom edge of the anchor.
calculatedHeightThe height at which the element will be rendered.
calculatedWidthThe width at which the element will be rendered.
canvasCornersAn array of 4 pc.Vec2s that represent the bottom left, bottom right, top right and top left corners of the component in canvas pixels.
colorThe color of the image for pc.ELEMENTTYPE_IMAGE types or the color of the text for pc.ELEMENTTYPE_TEXT types.
drawOrderThe draw order of the component.
fontThe font used for rendering the text.
fontAssetThe id of the font asset used for rendering the text.
fontSizeThe size of the font.
heightThe height of the element as set in the editor.
layersAn array of layer IDs (pc.Layer#id) to which this element should belong.
leftThe distance from the left edge of the anchor.
lineHeightThe height of each line of text.
marginThe distance from the left, bottom, right and top edges of the anchor.
materialThe material to use when rendering an image.
materialAssetThe id of the material asset to use when rendering an image.
opacityThe opacity of the image for pc.ELEMENTTYPE_IMAGE types or the text for pc.ELEMENTTYPE_TEXT types.
pivotThe position of the pivot of the component relative to its anchor.
pixelsPerUnitThe number of pixels that map to one PlayCanvas unit.
rectSpecifies which region of the texture to use in order to render an image.
rightThe distance from the right edge of the anchor.
rtlReorderReorder the text for RTL languages using a function registered by app.
screenThe Entity with a pc.ScreenComponent that this component belongs to.
screenCornersAn 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.
spacingThe spacing between the letters of the text.
spriteThe sprite to render.
spriteAssetThe id of the sprite asset to render.
spriteFrameThe frame of the sprite to render.
textThe text to render.
textHeightThe height of the text rendered by the component.
textWidthThe width of the text rendered by the component.
textureThe texture to render.
textureAssetThe id of the texture asset to render.
topThe distance from the top edge of the anchor.
typeThe type of the ElementComponent.
unicodeConverterConvert unicode characters using a function registered by app.
useInputIf true then the component will receive Mouse or Touch input events.
widthThe width of the element as set in the editor.
worldCornersAn array of 4 pc.Vec3s that represent the bottom left, bottom right, top right and top left corners of the component in world space.
wrapLinesWhether to automatically wrap lines based on the element width.

Events

clickFired when the mouse is pressed and released on the component or when a touch starts and ends on the component.
mousedownFired when the mouse is pressed while the cursor is on the component.
mouseenterFired when the mouse cursor enters the component.
mouseleaveFired when the mouse cursor leaves the component.
mousemoveFired when the mouse cursor is moved on the component.
mouseupFired when the mouse is released while the cursor is on the component.
mousewheelFired when the mouse wheel is scrolled on the component.
touchcancelFired when a touch is cancelled on the component.
touchendFired when a touch ends on the component.
touchmoveFired when a touch moves after it started touching the component.
touchstartFired when a touch starts on the component.

Inherited

Properties

enabledEnables or disables the component.

Details

Constructor

ElementComponent(system, entity)

Parameters

systempc.ElementComponentSystemThe ComponentSystem that created this Component
entitypc.EntityThe Entity that this Component is attached to.

Properties

pc.Vec2alignment

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.

pc.Vec4anchor

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.

NumberautoHeight

Automatically set the height of the component to be the same as the textHeight. Only works for pc.ELEMENTTYPE_TEXT types.

NumberautoWidth

Automatically set the width of the component to be the same as the textWidth. Only works for pc.ELEMENTTYPE_TEXT types.

NumberbatchGroupId

Assign element to a specific batch group (see pc.BatchGroup). Default value is -1 (no group).

Numberbottom

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.

NumbercalculatedHeight

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.

NumbercalculatedWidth

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.

pc.Vec2[]canvasCorners

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.

pc.Colorcolor

The color of the image for pc.ELEMENTTYPE_IMAGE types or the color of the text for pc.ELEMENTTYPE_TEXT types.

NumberdrawOrder

The draw order of the component. A higher value means that the component will be rendered on top of other components.

pc.Fontfont

The font used for rendering the text. Only works for pc.ELEMENTTYPE_TEXT types.

NumberfontAsset

The id of the font asset used for rendering the text. Only works for pc.ELEMENTTYPE_TEXT types.

NumberfontSize

The size of the font. Only works for pc.ELEMENTTYPE_TEXT types.

Numberheight

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.

Arraylayers

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.

Numberleft

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.

NumberlineHeight

The height of each line of text. Only works for pc.ELEMENTTYPE_TEXT types.

pc.Vec4margin

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.

pc.Materialmaterial

The material to use when rendering an image. Only works for pc.ELEMENTTYPE_IMAGE types.

NumbermaterialAsset

The id of the material asset to use when rendering an image. Only works for pc.ELEMENTTYPE_IMAGE types.

Numberopacity

The opacity of the image for pc.ELEMENTTYPE_IMAGE types or the text for pc.ELEMENTTYPE_TEXT types.

pc.Vec2pivot

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.

NumberpixelsPerUnit

The number of pixels that map to one PlayCanvas unit. Only works for pc.ELEMENTTYPE_IMAGE types who have a sliced sprite assigned.

pc.Vec4rect

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.

BooleanrtlReorder

Reorder the text for RTL languages using a function registered by app.systems.element.registerUnicodeConverter.

pc.Entityscreen

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

pc.Vec3[]screenCorners

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.

Numberspacing

The spacing between the letters of the text. Only works for pc.ELEMENTTYPE_TEXT types.

pc.Spritesprite

The sprite to render. Only works for pc.ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.

NumberspriteAsset

The id of the sprite asset to render. Only works for pc.ELEMENTTYPE_IMAGE types which can render either a texture or a sprite.

NumberspriteFrame

The frame of the sprite to render. Only works for pc.ELEMENTTYPE_IMAGE types who have a sprite assigned.

Stringtext

The text to render. Only works for pc.ELEMENTTYPE_TEXT types.

NumbertextHeight

The height of the text rendered by the component. Only works for pc.ELEMENTTYPE_TEXT types.

NumbertextWidth

The width of the text rendered by the component. Only works for pc.ELEMENTTYPE_TEXT types.

pc.Texturetexture

The texture to render. Only works for pc.ELEMENTTYPE_IMAGE types.

NumbertextureAsset

The id of the texture asset to render. Only works for pc.ELEMENTTYPE_IMAGE types.

Numbertop

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.

Stringtype

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

BooleanunicodeConverter

Convert unicode characters using a function registered by app.systems.element.registerUnicodeConverter.

BooleanuseInput

If true then the component will receive Mouse or Touch input events.

Numberwidth

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.

pc.Vec3[]worldCorners

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.

BooleanwrapLines

Whether to automatically wrap lines based on the element width. Only works for pc.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

eventpc.ElementMouseEvent, pc.ElementTouchEventThe event

mousedown

Fired when the mouse is pressed while the cursor is on the component. Only fired when useInput is true.

Parameters

eventpc.ElementMouseEventThe event

mouseenter

Fired when the mouse cursor enters the component. Only fired when useInput is true.

Parameters

eventpc.ElementMouseEventThe event

mouseleave

Fired when the mouse cursor leaves the component. Only fired when useInput is true.

Parameters

eventpc.ElementMouseEventThe event

mousemove

Fired when the mouse cursor is moved on the component. Only fired when useInput is true.

Parameters

eventpc.ElementMouseEventThe event

mouseup

Fired when the mouse is released while the cursor is on the component. Only fired when useInput is true.

Parameters

eventpc.ElementMouseEventThe event

mousewheel

Fired when the mouse wheel is scrolled on the component. Only fired when useInput is true.

Parameters

eventpc.ElementMouseEventThe event

touchcancel

Fired when a touch is cancelled on the component. Only fired when useInput is true.

Parameters

eventpc.ElementTouchEventThe event

touchend

Fired when a touch ends on the component. Only fired when useInput is true.

Parameters

eventpc.ElementTouchEventThe event

touchmove

Fired when a touch moves after it started touching the component. Only fired when useInput is true.

Parameters

eventpc.ElementTouchEventThe event

touchstart

Fired when a touch starts on the component. Only fired when useInput is true.

Parameters

eventpc.ElementTouchEventThe event

Inherited

Properties

Booleanenabled

Enables or disables the component.