🖥️ WebUI

Class for spawning a web browser in the screen.

info

🟧 Authority: This class can only be spawned on Client.

tip

This HTML implementation is built upon same core as WebKit/Safari using Ultralight library, a next-generation HTML Renderer.

caution

We are using a beta build of Ultralight, which now supports Audio and Video. Although it is still very unstable and some crashes may happen! Also the Audio currently plays only in 2D.

User Interfacecore-concepts/scripting/user-interfaceBasic HUD (HTML)getting-started/tutorials-and-examples/basic-hud-html

Usage

Client/Index.lua

-- Using a local file
my_ui = WebUI(
    "Awesome UI",            -- Name
    "file:///UI/index.html", -- Path relative to this package (Client/)
    true,                    -- Is Visible
)

-- Using a Web URL
my_browser = WebUI(
    "Awesome Site",       -- Name
    "https://nanos.world", -- Web's URL
    true,                 -- Is Visible
)

-- Using a local file from another package folder
my_ui = WebUI(
    "Awesome UI from Another Package", -- Name
    "file:///UI/index.html",           -- Path relative to this package (Client/)
    true,                              -- Is Visible
    true,
    true,
    0,
    0
)

Communicating between Lua and JS (WebUI)

Client/Index.lua

my_ui = WebUI("Awesome UI", "file:///UI/index.html")

local param1 = 123
local param2 = "hello"

-- Calls a JS event
my_ui:CallEvent("MyEvent", param1, param2)

-- Subscribes to receive JS events
my_ui:Subscribe("MyAnswer", function(param1)
    Package.Log("Received back! %s", param1)
    -- Will output 'Received back! Hey there!'
end)

// Register for "MyEvent" from Lua
Events.Subscribe("MyEvent", function(param1, param2) {
    console.log("Triggered! " + param1 + " " + param2);
    // Will output 'Triggered! 123 hello'

    // Triggers "MyAnswer" on Lua
    Events.Call("MyAnswer", "Hey there!");
})

Constructor Parameters

Type	Name	Default	Description
string	name		Currently not used
string	path		URL or file:///my_file.html or HTML Special Path
boolean	is_visible	true	if WebUI is visible by default
boolean	is_transparent	true	if WebUI background is transparent
boolean	auto_resize	true	if should auto resize when screen changes it's size (useful OFF when you are painting meshes with WebUI)
number	width	0	size of the WebUI when you are not using auto_resize
number	height	0	size of the WebUI when you are not using auto_resize

tip

Loading a .html file supports the following searchers, which are looked in the following order:

1. Relative to current-file-path/
2. Relative to current-package/Client/
3. Relative to current-package/
4. Relative to Packages/

Functions

Returns	Name	Description
	BringToFront	Puts this WebUI in the front of all WebUIs
	CallEvent	Calls an Event on the Browser’s JavaScript
	Destroy	Destroys this Browser
	LoadURL	Loads a new File/URL in this Browser
	SetFocus	Forces Focus on this Browser
	SetFreeze	Freezes the WebUI Rendering to the surface
	SetVisible	Toggles the visibility
boolean	IsValid	Returns if this entity is Valid
number	GetID	Gets the network ID of this entity
string	GetType	Returns the type of this Entity
boolean	IsVisible	Returns if this WebUI is currently visible
function	Subscribe	Subscribes for an Event
	Unsubscribe	Unsubscribes from all subscribed Events in this Entity and in this Package

BringToFront

Puts this WebUI in the front of all WebUIs

my_webui:BringToFront()

CallEvent

Calls an Event on the Browser's JavaScript

my_webui:CallEvent(event_name, arguments...)

Type	Parameter	Description
string	event_name
any	arguments...

Destroy

Destroys this Browser

my_webui:Destroy()

LoadURL

Loads a new File/URL in this Browser

Returns

my_webui:LoadURL(url)

Type	Parameter	Description
string	url

SetFocus

Enables the focus on this browser (i.e. can receive Keyboard input). You must call it when you want to enable Keyboard Input on WebUIs (after disabling Client's Input)

Note: Only one browser can have focus per time.

my_webui:SetFocus()

SetFreeze

Freezes the WebUI Rendering to the surface (it will still execute the JS under the hood)

my_webui:SetFreeze()

SetVisible

Toggles the visibility

my_webui:SetVisible(is_visible)

Type	Parameter	Description
boolean	is_visible

IsValid

Gets if this entity is Valid

Returns boolean

my_webui:IsValid()

GetID

Gets the network ID of this entity

Returns number

my_webui:GetID()

GetType

Returns the type of this Entity

Returns string

my_webui:GetType()

IsVisible

Returns if this WebUI is currently visible

Returns boolean

my_webui:IsVisible()

Subscribe

Subscribes for an Event

Returns the function callback itself

my_webui:Subscribe(event_name, callback)

Type	Parameter	Default Value	Description
string	event_name
function	function

Unsubscribe

Unsubscribes from all subscribed Events in this Entity and in this Package, optionally passing the function to unsubscribe only that callback

my_webui:Unsubscribe(event_name, callback)

Type	Parameter	Default Value	Description
string	event_name
function	function	nil

Events

Name	Description
Failed	When this page fails to load
Ready	When this page is fully loaded (DOM and JavaScript)

Failed

Triggered when this page fails to load

my_webui:Subscribe("Failed", function(error_code, message)
    -- Load failed
end)

Type	Parameter	Description
number	error_code
string	message

Ready

Triggered when this page is fully loaded

my_webui:Subscribe("Ready", function()
    -- When this page is fully loaded \(DOM and JavaScript\)
end)