Optionalproperties: Readonly<DOMRootProperties>Protected_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.
PrivatedomThis root's canvas element's context. Used for painting
ReadonlydomThis root's canvas element. Add this to the HTML body
Private OptionaldomA function that controls the size of the DOM element of this UI root. Optional.
ProtecteddriversThe list of drivers registered to this root
ReadonlytabCan 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.
ProtectedviewportThe internal viewport. Manages drawing
The Root#viewport's 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.
The Root#child's dimensions
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.
Is this root enabled? If not enabled, painting, updating or resolving layout will do nothing. Drivers will also be notified by calling Driver#onEnable or Driver#onDisable, pointer style will be reset and all foci will be cleared (Root#clearFocus).
Is this root enabled? If not enabled, painting, updating or resolving layout will do nothing. Drivers will also be notified by calling Driver#onEnable or Driver#onDisable, pointer style will be reset and all foci will be cleared (Root#clearFocus).
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.
Unregisters 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.
Optionalsource: unknownStop requesting all pointer styles from a specific widget.
Destroy this Root. Disables the Root, clears all drivers, detaches the Root#child Widget and resets Root#textInputHandler.
Root must not be used after calling this method. Doing so will cause exceptions to be thrown. There is no way to un-destroy a destroyed Root.
Call this if you are no longer going to use this Root.
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.
Gets 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.
OptionalselectStart: numberOptionalselectEnd: numberIf Root#textInputHandler is set, returns a new instance, otherwise, returns null.
ProtectedhandleDispose 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).
ProtectedhandleHandle 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
Was 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
Should 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.
Does nothing if the widget is inactive or doesn't belong to this UI root.
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.
Does nothing if the widget is inactive or doesn't belong to this UI root.
Optionalsource: unknownRe-scale the DOM element of this UI root. You only need to manually call this if you use a DOMRoot#domSizeController and an external factor would affect the result of your custom size.
Counters Root viewport scaling with an opposite CSS scale (via width and height, not CSS transforms), and applies size given by domSizeController, if any is supplied.
Resolve 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.
Update DOMRoot.
If root is disabled, DOMRoot#domElem's display style is set to 'none', hiding it.
Calls Root#preLayoutUpdate, Root#resolveLayout, Root#postLayoutUpdate and Root#paint.
PrivateupdateDOMDimsUpdate the width and height of DOMRoot#domElem
StaticmakeInternalCreates 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.
Optionalproperties: Readonly<RootProperties>Returns a new CanvasViewport (or child class instance) for the Root
Like Root, but for easy use in an HTML page.
Instead of calling each individual update method, simply call DOMRoot#update on every animation frame. Drivers still need to be manually registered.