API documentation - michal-repo/three-mesh-ui GitHub Wiki
Updating things :
In order for the components to display a new state after you create, update, or add them to parents, you must call ThreeMeshUI.update()
.
This is typically placed in the render loop.
three-mesh-ui components :
Text:
Inline component, it cannot be added directly to the scene. You must add it to a Block
instance, because it is the parent Block that define its position
.
Block:
The basic building block of the library, it can be added directly to the THREE.Scene
, and you can set its position
, rotation
and scale
like any other THREE.Object3D
. It behaves like a flexbox by default, so you can add more Block
inside a Block
, and set their layout with contentDirection
, alignContent
and justifyContent
, similarly to how you would use flex-direction
, align-items
, and justify-content
in CSS.
InlineBlock:
It's like a Block
, but you can add it in a Block
along with some text, and it will position itself inline with the text, like a letter. It can be used for icons and emojis for instance.
Keyboard:
High-level component, it is constituted of Blocks
and Texts
components to provide a keyboard. To interact with the keys, you will want to use the setupState
and setState
methods of the keys. The Keyboard
component has two special properties, panels
and keys
, assigned with arrays filled with the keyboard's inner Blocks
.
MeshUIComponent
Internally, all components, whether Text
, Block
or Keyboard
have something important in common : they inherit from MeshUIComponent
.
MeshUIComponent is the core of this library, here we will look more closely into its methods (accessible from any component).
MeshUIComponent.update( updateParsing, updateLayout, updateInner )
Schedule an update for this component, which will only happen when you call ThreeMeshUI.update()
.
The three parameters are booleans, and correspond to the type of update that you want to schedule.
Usage of update
is advanced and not necessary for a basic usage of three-mesh-ui, since it is called internally by MeshUIComponent.set
.
MeshUIComponent.setupState( options )
Creates a state
with parameters, that is recorded internally and that you will later be able to set at runtime with setState
. It takes an object with the following parameters :
- state (string) : name of the new state
- attributes (object) : object containing attributes (
attributeName: value
) - onSet (function) : callback function, called when the state is set
MeshUIComponent.setState( state: string )
Set a saved state as this component's current state, and update its attributes with the attributes you passed in setupState
. When you call setState
, it calls the callback you passed in setupState
.
MeshUIComponent.set( options )
Set the component's attributes, then call updates according to the type of attributes you set. It takes an object, with key: value
corresponding to the possible attributes and their possible values. More about this bellow.
MeshUIComponent.onAfterUpdate
Optional callback that get called after any update.
Example here
Attributes
Attributes are a component's parameters. You should avoid setting them directly (component.attribute = value
), unless you manually call component.update
with the right parameters (see above). The easiest way to use this library is to set attributes with component.set
and/or component.setupState
+ component.setState
.
Common Attributes
offset
Distance on the Z direction between this component and its parent.
Block
Layout attributes
width
Width of the component.
Value in world units.
This attribute does not propagate to children.
height
Height of the component.
Value in world units.
This attribute does not propagate to children.
fontSize
Font Size of the text content.
Height in world space.
Propagate to the children components.
padding
Space between the component border and its content outer border.
Value in world units.
margin
Space between the component border and outer or neighbours components outer border.
Value in world units.
contentDirection
Similar to CSS flex-direction
, direction of the Block
children.
Available values are :
'row'
'row-reverse'
'column'
: default value'column-reverse'
This attribute does not propagate to children.
justifyContent
Similar to CSS justify-content
, Position the Block
children along the direction of contentDirection
.
Available values are :
'start'
: Please note that it acts as'flex-start'
in css'end'
: Please note that it acts as'flex-end'
in css'center'
: default value'space-between'
: v6.4.0+'space-around'
: v6.4.0+'space-evenly'
: v6.4.0+
This attribute does not propagate to children.
alignItems
v6.4.0+
Similar to CSS align-items
, align the Block
children along the direction of contentDirection
.
Available values are :
'start'
'end'
'center'
: default value'stretch'
: v6.4.0+: Deprecated from v6.4.0. Removed in v7.x.x. Requires'top'
contentDirection
is'row'
or'row-reverse'
.: Deprecated from v6.4.0. Removed in v7.x.x. Requires'bottom'
contentDirection
is'row'
or'row-reverse'
.: Deprecated from v6.4.0. Removed in v7.x.x. Requires'left'
contentDirection
is'column'
or'column-reverse'
.: Deprecated from v6.4.0. Removed in v7.x.x. Requires'right'
contentDirection
is'column'
or'column-reverse'
.
This attribute does not propagate to children.
interLine
Distance between each lines of inline components inside this component.
Not effective on an inline component, it is the parent component that compute the positions of inline components.
hiddenOverflow
Similar to CSS overflow: 'hidden'
, it crops the parts of children that are out of its inner limit (width - padding).
This feature uses three.js local clipping, so don't forget to enable local clipping with renderer.localClippingEnabled = true
Example here
alignContent
(!) Deprecated from v6.4.0 & Removed in v7.x.x ***
Rely on alignItems
and textAlign
instead
Position the Blocks
inside this components in the direction perpendicular to the direction of contentDirection
.
If contentDirection
is row
or row-reverse
, then alignContent
can be top
, center
or bottom
.
If contentDirection
is column
or column-reverse
, then alignContent
can be right
, center
or left
.
Not effective on inline components.
This attribute does not propagate to children.
Block
Style attributes
bestFit
v6.0.1+
Automatic changes of the fontSize to provide a more elegant display
Available values are :
'none'
: default value Feature is disabled'shrink'
: Allows the fontSize to be reduced in order to fit its parent layout'grow'
: Allows the fontSize to be incread in order to fit as much as possible its parent layout'auto'
: Combines'shrink'
&'grow'
backgroundColor
Color of the background.
It does not propagate to children.
backgroundOpacity
Opacity of the background.
It does not propagate to children.
backgroundTexture
THREE.Texture to be used for this background.
It does not propagate to children.
backgroundSize
Similar to css background-size
, Texture mapping of the panel.
Available values are :
'stretch'
'contain'
'cover'
: default value
Example here.
borderRadius
Radius of the rounded edges in worldUnits.
Single number or array of 4 numbers allowed : [topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius]
Only effective on Blocks
and InlineBlocks
.
borderWidth
Similar to css border-width
, width of the border.
This property do not affect the layout : borders are drawn inside the width
+ padding
of the component.
Only effective on Block
and InlineBlock
.
borderColor
A three.js Color.
Color of the border.
Only effective on Blocks
and InlineBlocks
.
Text
Layout attributes
content
String representing the text content of this component.
fontKerning
v6.0.0+
Similar to css kerning
, except for units, retrieve the space between each characters pairs stored in the font json.
Available values are :
'none'
'normal'
: default value
letterSpacing
v5.5.0+
Similar to css letter-spacing
, except for units, defines the constant space between each characters.
Unit is multiplier of the fontSize
. (ie: letterSpacing 1 = 1xFontSize, letterSpacing 0.01 = 0.01xfontSize)
textAlign
v6.4.0+
Similar to css text-align
Available values are :
'left'
'center'
: default value'right'
'justify'
: Acts as'justify-all'
in css (even the last line is justified)'justify-left'
: Acts as'justify'
except that last line is'left'
'justify-center'
: Acts as'justify'
except that last line is'center'
'justify-right'
: Acts as'justify'
except that last line is'right'
whiteSpace
v6.0.3+
Similar to css white-space
(documentation).
Available values are :
'normal'
'pre-line'
: default value'pre-wrap'
'pre'
: v6.4.0+'nowrap'
: v6.4.0+
breakOn
Defines which character should be 'breakable' in a line.
Might be ignored according to whiteSpace
value
Default value is : '- ,.:?!\n'
Text
Style attributes
fontColor
[THREE.Color] Color of the text.
fontOpacity
Opacity of the text.
It does not propagate to children.
fontSuperSampling
v6.1.0+
Activate or not the RotatedGridSuperSampling. Default is true
Impact of updates
The following attributes requires a full redraw and are therefore requires more computations.
- width
- height
- fontSize
- padding
- margin
- contentDirection
- alignItems
alignContent- textAlign
- letterSpacing
- kerning
- justifyContent
- content
- interLine
The attributes bellow will only trigger a paint update, which is faster than a layout update. If you want to animate your layouts at 60FPS, you should stick to updating these attributes.
- fontColor
- fontOpacity
- backgroundColor
- backgroundOpacity
- backgroundTexture
- backgroundSize
- borderRadius
- borderWidth
- borderColor
- offset
The attributes bellow will trigger no update at all.
- hiddenOverflow