-
Notifications
You must be signed in to change notification settings - Fork 146
7.x.x API Documentation
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.
ThreeMeshUI provides multiple kind of elements that can be used in our scenes.
This is the base of all other elements kind. We won't add them in the scene, as it won't do anything.
MeshUIBaseElement offers the base of all other elements.
Box elements are three-mesh-ui internal elements, and we should not use them as is.
It offer a base to different other element kinds.
Boxes can be added directly to the scene.
Boxes have bounds defined by: offsetWidth, offsetHeight, innerWidth, innerHeight, centerX, centerY
extends BoxElement
Blocks organize its children using a flex layouter flexbox by default, so you can add more Boxes inside a Block, and set their layout with flexDirection, alignItems and justifyContent, similarly to how you would use flex-direction, align-items, and justify-content in CSS.
extends BoxElement
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.
Inline component, they can only be added into a TextElement, it behaves just as a <span> added in a <p> in html.
WIP starts here
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.
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.
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).
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.
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
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.
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.
Optional callback that get called after any update.
Example here
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.
Distance on the Z direction between this component and its parent.
Width of the component.
Value in world units.
This attribute does not propagate to children.
Height of the component.
Value in world units.
This attribute does not propagate to children.
Font Size of the text content.
Height in world space.
Propagate to the children components.
Space between the component border and its content outer border.
Value in world units.
Space between the component border and outer or neighbours components outer border.
Value in world units.
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.
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.
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+ -
'top'contentDirectionis'row'or'row-reverse'. -
'bottom'contentDirectionis'row'or'row-reverse'. -
'left'contentDirectionis'column'or'column-reverse'. -
'right'contentDirectionis'column'or'column-reverse'.
This attribute does not propagate to children.
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.
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
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.
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'
Color of the background.
It does not propagate to children.
Opacity of the background.
It does not propagate to children.
THREE.Texture to be used for this background.
It does not propagate to children.
Similar to css background-size, Texture mapping of the panel.
Available values are :
'stretch''contain'-
'cover': default value
Example here.
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.
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.
A three.js Color.
Color of the border.
Only effective on Blocks and InlineBlocks.
String representing the text content of this component.
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
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)
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'
Similar to css white-space (documentation).
Available values are :
'normal'-
'pre-line': default value 'pre-wrap'-
'pre': v6.4.0+ -
'nowrap': v6.4.0+
Defines which character should be 'breakable' in a line.
Might be ignored according to whiteSpace value
Default value is : '- ,.:?!\n'
[THREE.Color] Color of the text.
Opacity of the text.
It does not propagate to children.
Activate or not the RotatedGridSuperSampling. Default is true
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