Class: TextView
Defined in: src/ui/components/TextView.ts:84
A view for displaying text in 3D. It features a dual-rendering system:
- SDF Text (Default): Uses
troika-three-textto render crisp, high-quality text using Signed Distance Fields. This is ideal for most use cases. The library is loaded dynamically on demand. - HTML Canvas Fallback: If
troika-three-textfails to load or is disabled viauseSDFText: false, it renders text to an HTML canvas and applies it as a texture to a plane.
Extends
View<TextViewEventMap>
Extended by
Constructors
Constructor
new TextView(
options,geometry?,material?):TextView
Defined in: src/ui/components/TextView.ts:171
TextView can render text using either Troika SDF text or HTML canvas.
Parameters
options
TextViewOptions = {}
Configuration options for the TextView.
geometry?
BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>
Optional geometry for the view's background mesh.
material?
Optional material for the view's background mesh.
Returns
TextView
Overrides
Properties
anchorX
anchorX:
number|"left"|"right"|"center"|`${number}%`='center'
Defined in: src/ui/components/TextView.ts:110
Horizontal anchor point ('left', 'center', 'right').
anchorY
anchorY:
number|"middle"|`${number}%`|"top"|"top-baseline"|"top-cap"|"top-ex"|"bottom-baseline"|"bottom"='middle'
Defined in: src/ui/components/TextView.ts:112
Vertical anchor point ('top', 'middle', 'bottom').
aspectRatio
aspectRatio:
number=1.0
Defined in: src/ui/core/View.ts:72
The calculated aspect ratio (width / height) of this view.
Inherited from
canvas?
optionalcanvas:HTMLCanvasElement
Defined in: src/ui/components/TextView.ts:141
Fallback HTML canvas to render legacy text.
ctx?
optionalctx:CanvasRenderingContext2D
Defined in: src/ui/components/TextView.ts:143
Fallback HTML canvas context to render legacy text.
font
font:
string=FONT_FAMILIES.Roboto
Defined in: src/ui/components/TextView.ts:95
The font file to use. Defaults to Roboto.
fontColor
fontColor:
string|number=0xffffff
Defined in: src/ui/components/TextView.ts:100
The color of the font.
fontSize?
optionalfontSize:number
Defined in: src/ui/components/TextView.ts:97
The size of the font in world units.
fontSizeDp?
optionalfontSizeDp:number
Defined in: src/ui/components/TextView.ts:98
height
height:
number=1
Defined in: src/ui/components/TextView.ts:138
Relative local height.
Overrides
imageOffsetX
imageOffsetX:
number=0
Defined in: src/ui/components/TextView.ts:127
The horizontal offset for the imageOverlay texture.
imageOffsetY
imageOffsetY:
number=0
Defined in: src/ui/components/TextView.ts:129
The vertical offset for the imageOverlay texture.
imageOverlay?
optionalimageOverlay:string
Defined in: src/ui/components/TextView.ts:125
An optional image URL to use as an overlay texture on the text.
isQuad
isQuad:
boolean=true
Defined in: src/ui/core/View.ts:27
Flag indicating View behaves as a 2D quad in layout calculations.
Inherited from
isRoot
isRoot:
boolean=false
Defined in: src/ui/components/TextView.ts:88
TextView resides in a panel by default.
Overrides
isView
isView:
boolean=true
Defined in: src/ui/core/View.ts:31
Type identifier for easy checking with instanceof.
Inherited from
isXRScript
isXRScript:
boolean=true
Defined in: src/core/Script.ts:54
Inherited from
lineCount
lineCount:
number=0
Defined in: src/ui/components/TextView.ts:147
The total number of lines after text wrapping.
lineHeight
lineHeight:
number=0
Defined in: src/ui/components/TextView.ts:145
The calculated height of a single line of text.
maxWidth
maxWidth:
number=1.0
Defined in: src/ui/components/TextView.ts:106
The maximum width the text can occupy before wrapping. To fit a long TextView within a container, this value should be its container's height / width to avoid it getting rendered outside.
mesh?
optionalmesh:Mesh<BufferGeometry<NormalBufferAttributes,BufferGeometryEventMap>,Material|Material[],Object3DEventMap>
Defined in: src/ui/core/View.ts:70
The underlying THREE.Mesh if the view has a visible geometry.
Inherited from
mode
mode:
string='fitWidth'
Defined in: src/ui/components/TextView.ts:108
Layout mode. 'fitWidth' scales text to fit the view's width.
name
name:
string='TextView'
Defined in: src/ui/components/TextView.ts:90
Default description of this view in Three.js DevTools.
Overrides
opacity
opacity:
number=1.0
Defined in: src/ui/core/View.ts:68
The overall opacity of the view and its children.
Inherited from
paddingX
paddingX:
number=0
Defined in: src/ui/core/View.ts:59
Horizontal padding, as a 0-1 ratio of the parent's width.
Inherited from
paddingY
paddingY:
number=0
Defined in: src/ui/core/View.ts:61
Vertical padding, as a 0-1 ratio of the parent's height.
Inherited from
paddingZ
paddingZ:
number=0
Defined in: src/ui/core/View.ts:63
Depth padding, for z-axis adjustment to prevent z-fighting.
Inherited from
selectable
selectable:
boolean=true
Defined in: src/ui/core/View.ts:33
Determines if this view can be targeted by user input.
Inherited from
textAlign
textAlign:
string='center'
Defined in: src/ui/components/TextView.ts:123
Horizontal alignment ('left', 'center', 'right').
textObj?
optionaltextObj:Mesh<BufferGeometry<NormalBufferAttributes,BufferGeometryEventMap>,Material|Material[],Object3DEventMap> |Text
Defined in: src/ui/components/TextView.ts:93
The underlying renderable object (either a Troika Text or a Plane.
useSDFText
useSDFText:
boolean=true
Defined in: src/ui/components/TextView.ts:86
Determines which rendering backend to use. Defaults to SDF text.
ux
ux:
UX
Defined in: src/core/Script.ts:53
Inherited from
weight
weight:
number=0.5
Defined in: src/ui/core/View.ts:38
Proportional size used in layouts like Row or Col.
Inherited from
width
width:
number=1
Defined in: src/ui/components/TextView.ts:136
Relative local width.
Overrides
x
x:
number=0
Defined in: src/ui/components/TextView.ts:132
Relative local offset in X.
Overrides
y
y:
number=0
Defined in: src/ui/components/TextView.ts:134
Relative local offset in Y.
Overrides
z
z:
number=0
Defined in: src/ui/core/View.ts:57
The local z-coordinate within the parent's layout. For root view (Panel), this will be addition to the global positioning.
Inherited from
Accessors
rangeX
Get Signature
get rangeX():
number
Defined in: src/ui/core/View.ts:79
Gets the effective horizontal range for child elements, normalized to 1.0 for the smaller dimension.
Returns
number
The horizontal layout range.
Inherited from
rangeY
Get Signature
get rangeY():
number
Defined in: src/ui/core/View.ts:88
Gets the effective vertical range for child elements, normalized to 1.0 for the smaller dimension.
Returns
number
The vertical layout range.
Inherited from
text
Get Signature
get text():
string
Defined in: src/ui/components/TextView.ts:161
Returns
string
Set Signature
set text(
text):void
Defined in: src/ui/components/TextView.ts:151
Parameters
text
string
Returns
void
Methods
_initializeText()
protected_initializeText():void
Defined in: src/ui/components/TextView.ts:350
Private method to perform the actual initialization after the async import has resolved.
Returns
void
add()
add(...
children):TextView
Defined in: src/ui/core/View.ts:222
Overrides THREE.Object3D.add to automatically trigger a layout update
when a new View is added as a child.
Parameters
children
...Object3D<Object3DEventMap>[]
Returns
TextView
Inherited from
createTextSDF()
protectedcreateTextSDF():void
Defined in: src/ui/components/TextView.ts:237
Creates the text object using Troika Three Text for SDF rendering.
This method should only be called from _initializeText() when useSDFText
is true and the troika-three-text module has been successfully imported.
Returns
void
dispose()
dispose():
void
Defined in: src/ui/components/TextView.ts:406
Disposes of resources used by the TextView, such as event listeners.
Returns
void
Overrides
dpToLocalUnits()
dpToLocalUnits(
dp):number
Defined in: src/ui/core/View.ts:125
Converts a value from Density-Independent Pixels (DP) to local units.
Parameters
dp
number
The value in density-independent pixels.
Returns
number
The equivalent value in local units.
Inherited from
hide()
hide():
void
Defined in: src/ui/core/View.ts:139
Makes the view and all its descendants invisible.
Returns
void
Inherited from
init()
init(
_?):Promise<void>
Defined in: src/ui/components/TextView.ts:199
Initializes the TextView. It waits for the Troika module to be imported and then creates the text object, sets up aspect ratio, and loads overlays.
Parameters
_?
object
Returns
Promise<void>
Overrides
initPhysics()
initPhysics(
_physics):void|Promise<void>
Defined in: src/core/Script.ts:73
Enables depth-aware interactions with physics. See /demos/ballpit
Parameters
_physics
Returns
void | Promise<void>
Inherited from
onHoverEnter()
onHoverEnter(
_controller):void
Defined in: src/core/Script.ts:158
Called when the controller starts hovering over this object with reticle.
Parameters
_controller
An XR controller.
Returns
void
Inherited from
onHoverExit()
onHoverExit(
_controller):void
Defined in: src/core/Script.ts:163
Called when the controller hovers over this object with reticle.
Parameters
_controller
An XR controller.
Returns
void
Inherited from
onHovering()
onHovering(
_controller):void
Defined in: src/core/Script.ts:168
Called when the controller hovers over this object with reticle.
Parameters
_controller
An XR controller.
Returns
void
Inherited from
onKeyDown()
onKeyDown(
_event):void
Defined in: src/core/Script.ts:110
Called on keyboard keypress.
Parameters
_event
Event containing .code to read the keyboard key.
Returns
void
Inherited from
onKeyUp()
onKeyUp(
_event):void
Defined in: src/core/Script.ts:111
Parameters
_event
Returns
void
Inherited from
onObjectGrabbing()
onObjectGrabbing(
_event):void
Defined in: src/core/Script.ts:188
Called every frame a hand is grabbing this object.
Parameters
_event
Returns
void
Inherited from
onObjectGrabEnd()
onObjectGrabEnd(
_event):void
Defined in: src/core/Script.ts:192
Called when a hand stops grabbing this object.
Parameters
_event
Returns
void
Inherited from
onObjectGrabStart()
onObjectGrabStart(
_event):void
Defined in: src/core/Script.ts:184
Called when a hand starts grabbing this object (touching + pinching).
Parameters
_event
Returns
void
Inherited from
onObjectSelectEnd()
onObjectSelectEnd(
_event):boolean
Defined in: src/core/Script.ts:151
Called when the controller stops selecting this object the script represents, e.g. View, ModelView.
Parameters
_event
event.target holds its controller.
Returns
boolean
Whether the event was handled
Inherited from
onObjectSelectStart()
onObjectSelectStart(
_event):boolean
Defined in: src/core/Script.ts:142
Called when the controller starts selecting this object the script represents, e.g. View, ModelView.
Parameters
_event
event.target holds its controller.
Returns
boolean
Whether the event was handled
Inherited from
onObjectTouchEnd()
onObjectTouchEnd(
_event):void
Defined in: src/core/Script.ts:180
Called when a hand's index finger stops touching this object.
Parameters
_event
Returns
void
Inherited from
onObjectTouching()
onObjectTouching(
_event):void
Defined in: src/core/Script.ts:176
Called every frame that a hand's index finger is touching this object.
Parameters
_event
Returns
void
Inherited from
onObjectTouchStart()
onObjectTouchStart(
_event):void
Defined in: src/core/Script.ts:172
Called when a hand's index finger starts touching this object.
Parameters
_event
Returns
void
Inherited from
onSelect()
onSelect(
_event):void
Defined in: src/core/Script.ts:99
Called whenever pinch / mouse click successfully completes, globally.
Parameters
_event
event.target holds its controller.
Returns
void
Inherited from
onSelectEnd()
onSelectEnd(
_event):void
Defined in: src/core/Script.ts:93
Called whenever pinch / mouse click discontinues, globally.
Parameters
_event
event.target holds its controller
Returns
void
Inherited from
onSelecting()
onSelecting(
_event):void
Defined in: src/core/Script.ts:104
Called whenever pinch / mouse click is happening, globally.
Parameters
_event
Returns
void
Inherited from
onSelectStart()
onSelectStart(
_event):void
Defined in: src/core/Script.ts:87
Called whenever pinch / mouse click starts, globally.
Parameters
_event
event.target holds its controller
Returns
void
Inherited from
onSimulatorStarted()
onSimulatorStarted():
void
Defined in: src/core/Script.ts:79
Returns
void
Inherited from
onSqueeze()
onSqueeze(
_event):void
Defined in: src/core/Script.ts:133
Called whenever gamepad trigger successfully completes, globally.
Parameters
_event
event.target holds its controller.
Returns
void
Inherited from
onSqueezeEnd()
onSqueezeEnd(
_event):void
Defined in: src/core/Script.ts:122
Called whenever gamepad trigger stops, globally.
Parameters
_event
event.target holds its controller.
Returns
void
Inherited from
onSqueezeStart()
onSqueezeStart(
_event):void
Defined in: src/core/Script.ts:117
Called whenever gamepad trigger starts, globally.
Parameters
_event
event.target holds its controller.
Returns
void
Inherited from
onSqueezing()
onSqueezing(
_event):void
Defined in: src/core/Script.ts:127
Called whenever gamepad is being triggered, globally.
Parameters
_event
Returns
void
Inherited from
onSyncComplete()
onSyncComplete():
void
Defined in: src/ui/components/TextView.ts:318
Callback executed when Troika's text sync is complete. It captures layout data like total height and line count.
Returns
void
onTriggered()
onTriggered(
_id):void
Defined in: src/ui/core/View.ts:237
Hook called on a complete select action (e.g., a click) when this view is the target. Intended for override by subclasses.
Parameters
_id
number
The ID of the controller that triggered the action.
Returns
void
Inherited from
onXRSessionEnded()
onXRSessionEnded():
void
Defined in: src/core/Script.ts:77
Returns
void
Inherited from
onXRSessionStarted()
onXRSessionStarted(
_session?):void
Defined in: src/core/Script.ts:76
Parameters
_session?
Returns
void
Inherited from
physicsStep()
physicsStep():
void
Defined in: src/core/Script.ts:74
Returns
void
Inherited from
resetLayout()
resetLayout():
void
Defined in: src/ui/core/View.ts:202
Resets the layout state of this view. Intended for override by subclasses.
Returns
void
Inherited from
resetLayouts()
resetLayouts():
void
Defined in: src/ui/core/View.ts:205
Resets the layout state for this view and all its descendants.
Returns
void
Inherited from
setText()
setText(
text):void
Defined in: src/ui/components/TextView.ts:208
Sets the text content of the view.
Parameters
text
string
The text to be displayed.
Returns
void
setTextColor()
protectedsetTextColor(color):void
Defined in: src/ui/components/TextView.ts:397
Parameters
color
number
Returns
void
show()
show():
void
Defined in: src/ui/core/View.ts:131
Makes the view and all its descendants visible.
Returns
void
Inherited from
syncTextObj()
protectedsyncTextObj():void
Defined in: src/ui/components/TextView.ts:391
Returns
void
update()
update(
_time?,_frame?):void
Defined in: src/core/Script.ts:68
Runs per frame.
Parameters
_time?
number
_frame?
Returns
void
Inherited from
updateLayout()
updateLayout():
void
Defined in: src/ui/components/TextView.ts:215
Updates the layout of the text object, such as its render order.
Returns
void
Overrides
updateLayouts()
updateLayouts():
void
Defined in: src/ui/core/View.ts:178
Triggers a layout update for this view and all its descendants.
Returns
void
Inherited from
updateLayoutsBFS()
updateLayoutsBFS():
void
Defined in: src/ui/core/View.ts:186
Performs a Breadth-First Search (BFS) traversal to update the layout tree, ensuring parent layouts are calculated before their children.
Returns
void
Inherited from
dpToMeters()
staticdpToMeters(dp):number
Defined in: src/ui/core/View.ts:116
Converts a value from Density-Independent Pixels (DP) to meters.
Parameters
dp
number
The value in density-independent pixels.
Returns
number
The equivalent value in meters.