The object where the mesh will be added.
The material to use for this root's mesh. The material will be cloned.
The root's child widget.
Optional properties: WLRootPropertiesProtected _enabledIs the Root enabled? For internal use only.
See Root#enabled
Protected _fociCurrent component foci (event targets for each focus type).
For internal use only.
See Root#requestFocus, Root#dropFocus, Root#clearFocus and Root#getFocus
Protected _fociLast capturer of each component focus (event targets for each focus type).
For internal use only.
Protected _pointerFor internal use only. Current value of Root#pointerStyleHandler.
Private boundProtected collisionPrivate curPrivate cursorProtected cursorPrivate downOptional ev: EventTypesProtected driversThe list of drivers registered to this root
Private hasPrivate keydownPrivate keyupPrivate lastPrivate lastProtected materialProtected meshProtected meshProtected meshPrivate moveOptional ev: EventTypesProtected oldProtected paintedReadonly tabCan tab controls be used in this UI root? True by default. Can only be set once when the UI is created.
Text input handler constructor for environments where getting keyboard input is hard, such as mobile and WebXR. If not null, widgets that need text may call this to get strings and cursor positions as text is typed.
Protected textureOptional texturePrivate unOptional ev: EventTypesPrivate upOptional ev: EventTypesProtected validProtected viewportThe internal viewport. Manages drawing
Private wlThe object where the mesh will be added.
Static Readonly defaultAre materials cloned by default?
Static Readonly defaultDefault collision groups, as a bitmask
Static Readonly defaultHow many pixels to over-extend the collision extents by default.
Static Readonly defaultShould the UI texture be destroyed by default when the root is disabled?
Static Readonly defaultDefault maximum canvas (texture) height. Smaller than lazy-widget's default value because Wonderland engine has much stricter texture limits due to the texture atlas system.
Static Readonly defaultDefault maximum canvas (texture) width. Smaller than lazy-widget's default value because Wonderland engine has much stricter texture limits due to the texture atlas system.
Static Readonly defaultShould the collision extents only be over-extended when the cursor is being captured by default?
Static Readonly defaultIs texture bleeding from the texture atlas prevented by default?
Static Readonly defaultIs texture bleeding from old content prevented by default?
Static Readonly defaultAre keyboard drivers auto-registered by default?
Static Readonly defaultAre pointer drivers auto-registered by default?
Static Readonly defaultThe resolution of the canvas. For example, if 2, then the resolution of the canvas will be doubled. If 0.5, then the resolution of the canvas will be halved.
Static Readonly defaultDefault units-per-pixel
The Root#viewport's CanvasViewport#canvas | canvas. The canvas must not be modified directly; consider it output-only.
The root widget of this UI tree. Equivalent to getting Root#viewport.Viewport#child.
The Root#viewport's constraints
The text input handler that is currently in use. null if none in use.
Get the scale used for the Root#viewport. The horizontal and/or vertical scale may not be 1 if Root#maxCanvasWidth or Root#maxCanvasHeight are exceeded.
Note that this is only valid after resolving Root#child's layout.
Equivalent to getting Viewport#effectiveScale on Root#viewport.
Shortcut for Root#viewport's CanvasViewport#maxCanvasHeight property
Shortcut for Root#viewport's CanvasViewport#maxCanvasWidth property
Pointer style handler, decides how to show the given pointer style. Normally a function which sets the CSS cursor style of the Root's canvas
Shortcut for Root#viewport's CanvasViewport#preventAtlasBleeding property.
Shortcut for Root#viewport's CanvasViewport#preventBleeding property.
Shortcut for Root#viewport's CanvasViewport#resolution property.
Note that, although the resolution is part of the CanvasViewport API, widgets will treat the resolution property as being per-Root, not per-Viewport (hence the lack of a Viewport.resolution property). The resolution property is part of the CanvasViewport class so that CanvasViewport is not circularly dependent on the Root class.
Static keyboardThe shared DOMKeyboardDriver instance. Getter only. The DOMKeyboardDriver will only be created when needed. Used for keyboard input.
Static pointerThe shared PointerDriver instance. Getter only. The PointerDriver will only be created when needed. Used for pointer (mouse & XR controller) input.
Static pointerIDsA Map mapping each cursor component to a PointerDriver's pointer ID.
Private _setupPrivate _testUnregisters all Root#drivers from the root, by calling Root#unregisterDriver.
Clears the current focus of a given type. If there was a focus set, Root#drivers are notified by calling Driver#onFocusChanged.
Stop requesting a pointer style.
Optional source: unknownStop requesting all pointer styles from a specific widget.
Destroy the texture used by this UI root, or do nothing if there is no texture created. The UI root will still be usable after calling this, as the texture is auto-created when needed.
Use this if you want to save atlas space for a disabled UI root. If this is your use-case, and the UI root is not frequently toggled, consider using the WLRoot#destroyTextureWhenDisabled option.
Dispatches a WidgetEvent to this root's Root#child by calling Widget#dispatchEvent. Updates foci capturers and notifies Root#drivers by calling Driver#onFocusCapturerChanged if the capturer changes. Does nothing if root is disabled.
Note that if an event with a focus is dispatched and no widget captures the event due to the widget not existing anymore or being disabled, the focus type of the event will be cleared in the root with Root#clearFocus.
Dispatching a single event can result in a chain of dispatched events. These extra events will be returned.
Returns a list of dispatched events and whether they were captured.
Clears all the foci that are set to a given Widget. Achieved by calling Root#dropFocus
Clears the current focus of a given type if it is currently set to a given widget. Achieved by calling Root#clearFocus.
Get the collision component used for detecting cursor input. Will be null if a WLRootProperties#collisionGroupsMask is not provided when creating this WLRoot.
Private getGets the last focus capturer of a given type.
Instantiate a text input handler. Used for mobile or WebXR where keyboard events are hard to get. Note that this will replace the current handler if there is any.
Optional initialInput: stringOptional selectStart: numberOptional selectEnd: numberIf Root#textInputHandler is set, returns a new instance, otherwise, returns null.
Protected handleDispose all resources associated with text input handler. You probably don't need to implement this method, unless you do something with the HTML elements returned by the input handler (such as listening to focus or blur events).
Protected handleHandle initialization of a text input handler. You probably don't need to implement this method, unless you do something with the HTML elements returned by the input handler (such as listening to focus or blur events).
Mark a widget as hovered (received a pointer event since the last check). Widgets will call this method automatically, there is no need to manually call this.
Remove an event listeners added with Root#on. Not chainable.
The WidgetEvent#"type" to stop listening to
The user-provided callback that was used in Root#on
Optional once: booleanWas the listener only meant to be invoked once? Must match what was used in Root#on
Remove an event listeners added with Root#onAny. Not chainable.
The user-provided callback that was used in Root#onAny
Listen to a specific event with a user listener. Chainable.
Only events that pass through the Root will be listened; all trickling events that start at the root will be listened, sticky events will only be listened if they are dispatched at the Root, and bubbling events will only be listened if none of the child widgets capture the event.
The WidgetEvent#"type" to listen to
The user-provided callback that will be invoked when the event is listened
Optional once: booleanShould the listener only be invoked once? False by default
Similar to Root#on, but any event type invokes the user-provided callback, the listener can't be invoked only once, and the listener is called with a lower priority than specific event listeners. Chainable.
The user-provided callback that will be invoked when a event is listened
Paint this root's next frame if needed. Does nothing if root is disabled.
Calls Root#viewport's Viewport#paint with Root#child.
Call this after calling Root#postLayoutUpdate.
Returns a list of dirty rectangles in the texture's coordinates, or null if the child widget was not repainted. Use this to tell an external 3D library whether to update a mesh's texture or not, and where to update the mesh's texture.
Do a post-layout update; calls Root#child's Widget#postLayoutUpdate. Does nothing if root is disabled.
Call this before calling Root#paint and after calling Root#resolveLayout
Do a pre-layout update; calls Root#drivers' Driver#update and Root#child's Widget#preLayoutUpdate. Does nothing if root is disabled.
Call this before calling Root#resolveLayout
Registers a Driver to the root, adding it to the Root#drivers list and calling Driver#onEnable. If the driver was already registered, nothing happens.
Sets the current focus of a given type to a given widget. If the focus changes, Root#clearFocus is called and Root#drivers are notified by calling Driver#onFocusChanged.
If the target widget doesn't capture the dispatched FocusEvent, then the focus is not changed.
Request that a specific ID is assigned to a specific Widget that is attached to this Root. Must not be called manually; Widget will automatically manage its ID when needed.
The wanted ID
The widget that the ID will be assigned to
Request a pointer style. If the pointer style has a lower priority than the current pointer style, it won't be displayed, but will still be queued up in case the higher-priority style is cleared.
Optional source: unknownResolve the layout of this root. Does nothing if root is disabled.
Calls Root#viewport's Viewport#resolveLayout with Root#child
Call this before calling Root#postLayoutUpdate and after calling Root#preLayoutUpdate
Returns true if the viewport was resized or re-scaled
Unregisters a Driver from the root, removing it from the Root#drivers list and calling Driver#onDisable. If the driver was not registered, nothing happens.
Private updateStatic getThe shared DOMKeyboardDriverGroup instance. Getter only. The DOMKeyboardDriverGroup will only be created when needed. Used for keyboard input.
Static getStatic makeInternal Creates a new CanvasViewport instance for a new Root. Normally it wouldn't make sense to separate this from the constructor, but this makes viewport creation hookable, allowing for the creation of debug overlay viewports.
Optional properties: Readonly<RootProperties>Returns a new CanvasViewport (or child class instance) for the Root
Generated using TypeDoc
A lazy-widgets Root which automatically manages a mesh and input. For an example on how to use this in a component, see example-components/test-ui-root.js
Note that the properties object can also contain optional parameters for the lazy-widgets Root constructor, and will be passed to it.
If texture bleeding prevention is not specified, then it will be enabled by default. Same applies for texture atlas bleeding prevention.
If a pointer style handler is not specified, then a default pointer style handler that changes the cursor style of the Wonderland Engine canvas will be be used.