webui

Search:
Group by:
Source   Edit  

Nim wrapper for WebUI

author:neroist
WebUI Version:2.5.0-Beta

See Nim Docs: https://yesdrx.github.io/nim-webui/

Example:

import webui

let window = newWindow() # Create a new Window
window.show("<html>Hello</html>") # Show the window with html content in any browser

wait() # Wait until the window gets closed

Types

Event = ref object
  internalImpl*: ptr bindings.Event
When you use bind(), your application will receive an event every time the user clicks on the specified HTML element. The event comes with the element, which is The HTML ID of the clicked element, for example, "MyButton", "MyInput", etc. The event also comes with the element ID & the unique window ID. Source   Edit   
Window = distinct int
Source   Edit  

Procs

proc `bind`(window: Window; element: string; func: proc ()) {....raises: [],
    tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (): bool) {....raises: [],
    tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (): float) {....raises: [],
    tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (): int) {....raises: [],
    tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (): string) {.
    ...raises: [], tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (e: Event)) {.
    ...raises: [], tags: [], forbids: [].}

Bind a specific html element and a JavaScript object with a backend function. Empty element will bind all events.

Each element can have only one function bound to it.

window:The window to bind the function onto.
element:The HTML element / JavaScript object to bind the function func to. For HTML elements, func will be called on click events. An empty element means func will be bound to all events.
func:The function to bind to element.
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (e: Event): bool) {.
    ...raises: [], tags: [], forbids: [].}
Bind func to element element and automatically pass return value of func to Javascript.
window:The window to bind the function onto.
element:The element to bind the function func to. func will be called on click events. An empty element means func will be called on all events.
func:The function to bind to element.
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (e: Event): float) {.
    ...raises: [], tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (e: Event): int) {.
    ...raises: [], tags: [], forbids: [].}
Source   Edit   
proc `bind`(window: Window; element: string; func: proc (e: Event): string) {.
    ...raises: [], tags: [], forbids: [].}
Source   Edit   
proc bindId(event: Event): int {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc browserExist(browser: bindings.WebuiBrowser): bool {....raises: [], tags: [],
    forbids: [].}

Check if a web browser is installed.

Returns true if the specified browser is available.

Source   Edit   
proc childProcessId(window: Window): int {....raises: [], tags: [], forbids: [].}
Get the ID of the last child process.
window:The window
Source   Edit   
proc clean() {....raises: [], tags: [], forbids: [].}
Free all memory resources. Should be called only at the end. Source   Edit   
proc clientId(event: Event): int {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc close(window: Window) {....raises: [], tags: [], forbids: [].}
Close a specific window only. The window object will still exist.
window:The window to close.
Source   Edit   
proc closeClient(event: Event) {....raises: [], tags: [], forbids: [].}
Close a specific client.
event:The event object.
Source   Edit   
proc connectionId(event: Event): int {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc cookies(event: Event): string {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc decode(str: string): string {....raises: [], tags: [], forbids: [].}
Base64 decoding. Use this to safely decode received Base64 text from the UI. If it fails it will return an empty string.
str:The string to decode.
Source   Edit   
proc deleteAllProfiles() {....raises: [], tags: [], forbids: [].}
Delete all local web-browser profiles folder. It should be called at the end. Source   Edit   
proc deleteProfile(window: Window) {....raises: [], tags: [], forbids: [].}
Delete a specific window web-browser local folder profile.
window:The window whose profile will be deleted
Source   Edit   
proc destroy(window: Window) {....raises: [], tags: [], forbids: [].}
Close a specific window and free all memory resources.
window:The window to destroy.
Source   Edit   
proc element(event: Event): string {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc encode(str: string): string {....raises: [], tags: [], forbids: [].}
Base64 encoding. Use this to safely send text based data to the UI. If it fails it will return an empty string.
str:The string to encode.
Source   Edit   
proc eventBlocking=(window: Window; status: bool) {....raises: [], tags: [],
    forbids: [].}
Control if UI events comming from this window should be processed one a time in a single blocking thread (true), or process every event in a new non-blocking thread (false). This function only affects a single window You may use setConfig(wcUiEventBlocking, ...) to update all windows.
window:The window to configure event blocking for.
status:Whether or not to process window events blockingly (single vs multi-threaded).
Source   Edit   
proc eventNumber(event: Event): int {....raises: [], tags: [], forbids: [].}
Source   Edit   
proc eventType(event: Event): bindings.WebuiEvent {....raises: [], tags: [],
    forbids: [].}
Source   Edit   
proc exit() {....raises: [], tags: [], forbids: [].}
Close all opened windows. wait() will break. Source   Edit   
proc fileHandler=(window: Window; handler: proc (filename: string): string) {.
    ...raises: [], tags: [], forbids: [].}
Set a custom handler to serve files. This custom handler should return the full HTTP headers and body.
window:The window to set the file handler.
runtime:The file handler callback/proc.
Source   Edit   
proc getBestBrowser(window: Window): bindings.WebuiBrowser {....raises: [],
    tags: [], forbids: [].}
Get the recommended web browser to use. If running show(), this function will return the same browser that is already being used.
window:The window to get the best browser for

Returns a value from the WebuiBrowser enum.

Source   Edit   
proc getBool(event: Event): bool {....raises: [], tags: [], forbids: [].}
Get the first argument as boolean
event:The event
Source   Edit   
proc getBool(event: Event; index: int): bool {....raises: [], tags: [], forbids: [].}
Get an argument as boolean at a specific index
event:The event
index:The argument position starting from 0
Source   Edit   
proc getCount(event: Event): int {....raises: [], tags: [], forbids: [].}
Get how many arguments there are in an event.
event:The event
Source   Edit   
proc getFloat(event: Event): float {....raises: [], tags: [], forbids: [].}
Get the first argument as a float
event:The event
Source   Edit   
proc getFloat(event: Event; index: int): float {....raises: [], tags: [],
    forbids: [].}
Get an argument as integer at a specific index
event:The event
index:The argument position starting from 0
Source   Edit   
proc getFreePort(): int {....raises: [], tags: [], forbids: [].}
Get an available and usable free network port. Source   Edit   
proc getInt(event: Event): int {....raises: [], tags: [], forbids: [].}
Get the first argument as integer
event:The event
Source   Edit   
proc getInt(event: Event; index: int): int {....raises: [], tags: [], forbids: [].}
Get an argument as integer at a specific index
event:The event
index:The argument position starting from 0
Source   Edit   
proc getMimeType(file: string): string {....raises: [], tags: [], forbids: [].}
Get the HTTP mime type of a file.
file:The name of the file (e.g. foo.png)
Source   Edit   
proc getNewWindowId(): int {....raises: [], tags: [], forbids: [].}

Get a free window number that can be used in conjuction with newWindow(int).

Returns the first available free window number, starting from 1.

Source   Edit   
proc getSize(event: Event): int {....raises: [], tags: [], forbids: [].}
Get size in bytes of the first argument
event:The event
Source   Edit   
proc getSize(event: Event; index: int): int {....raises: [], tags: [], forbids: [].}
Get the size in bytes of an argument at a specific index
event:The event
index:The argument position starting from 0
Source   Edit   
proc getString(event: Event): string {....raises: [], tags: [], forbids: [].}
Get the first argument as string
event:The event
Source   Edit   
proc getString(event: Event; index: int): string {....raises: [], tags: [],
    forbids: [].}
Get an argument as string at a specific index
event:The event
index:The argument position starting from 0
Source   Edit   
proc hidden=(window: Window; status: bool) {....raises: [], tags: [], forbids: [].}
Run the window in hidden mode
window:The window to hide or show.
status:Whether or not to hide the window. true to hide, false to show.
Source   Edit   
proc highContrast=(window: Window; status: bool) {....raises: [], tags: [],
    forbids: [].}
Setup the window with high-contrast support. Useful when you want to build a better high-contrast theme with CSS.
window:The window to set the high contrast theme support for.
status:Whether or not to support high contrast themes.
Source   Edit   
func impl(event: Event): ptr bindings.Event {....raises: [], tags: [], forbids: [].}
Returns the internal implementation of e Source   Edit   
func impl=(event: Event; be: ptr bindings.Event) {....raises: [], tags: [],
    forbids: [].}
Sets the internal implementation of e Source   Edit   
proc isHighContrast(): bool {....raises: [], tags: [], forbids: [].}

Get the OS's high contrast preference.

Returns true if the OS prefers a high contrast theme.

Source   Edit   
proc kiosk=(window: Window; status: bool) {....raises: [], tags: [], forbids: [].}
Set the window in Kiosk mode (full screen).
window:The window to enable or disable kiosk mode in.
status:Whether or not to enable kiosk mode. true to enable, false to disable.
Source   Edit   
proc newWindow(): Window {....raises: [], tags: [], forbids: [].}
Create a new WebUI window object. Source   Edit   
proc newWindow(windowNumber: int): Window {....raises: [], tags: [], forbids: [].}
Create a new webui window object using a specified window number.
windowNumber:The window ID (should be within the range of 0..<WEBUI_MAX_IDS)
Source   Edit   
proc openUrl(url: string) {....raises: [], tags: [], forbids: [].}
Open an URL in the native default web browser.
url:The URL to open
Source   Edit   
proc parentProcessId(window: Window): int {....raises: [], tags: [], forbids: [].}
Get the ID of the parent process (The web browser may re-create another new process).
window:The window
Source   Edit   
proc port(window: Window): int {....raises: [], tags: [], forbids: [].}

Get the network port of a running window.

This can be useful to determine the HTTP link of webui.js

window:The window
port:The web-server network port WebUI should use
Source   Edit   
proc port=(window: Window; port: int) {....raises: [], tags: [], forbids: [].}
Set a custom web-server network port to be used by WebUI. This can be useful to determine the HTTP link of webui.js in case you are trying to use WebUI with an external web-server like NGNIX
window:The window
port:The web-server network port WebUI should use
Source   Edit   
proc pos=(window: Window; pos: tuple[x, y: int]) {.
    ...deprecated: "Use `setPos` instead", raises: [], tags: [], forbids: [].}
Deprecated: Use `setPos` instead
Alias for setPos Source   Edit   
proc proxy=(window: Window; proxyServer: string) {....raises: [], tags: [],
    forbids: [].}
Set the web browser to use proxyServer. Must be called before show().
window:The window to set the proxy server for
proxyServer:The proxy server to use
Source   Edit   
proc public=(window: Window; status: bool) {....raises: [], tags: [], forbids: [].}
Allow a specific window address to be accessible from a public network
window:The window
status:Whether or not to set public. true to enable, false to disable.
Source   Edit   
proc returnBool(event: Event; b: bool) {....raises: [], tags: [], forbids: [].}
Return the response to JavaScript as a boolean.
event:The event to set the response for
b:The bool to return back to Javascript.
Source   Edit   
proc returnFloat(event: Event; f: float) {....raises: [], tags: [], forbids: [].}
Return the response to JavaScript as a float.
event:The event to set the response for
integer:The float to return back to Javascript.
Source   Edit   
proc returnInt(event: Event; integer: int) {....raises: [], tags: [], forbids: [].}
Return the response to JavaScript as a integer.
event:The event to set the response for
integer:The int to return back to Javascript.
Source   Edit   
proc returnString(event: Event; str: string) {....raises: [], tags: [], forbids: [].}
Return the response to JavaScript as a string.
event:The event to set the response for
str:The string to return back to Javascript.
Source   Edit   
proc rootFolder=(window: Window; path: string): bool {.discardable, ...raises: [],
    tags: [], forbids: [].}
Set the web-server root folder path.
window:The window to set the root folder for.
path:The path to the root folder.
Source   Edit   
proc run(window: Window; script: string) {....raises: [], tags: [], forbids: [].}
Run JavaScript quickly without waiting for the response. All clients.
window:The window to run the Javascript code in.
script:The Javascript code to execute.
Source   Edit   
proc runClient(event: Event; script: string) {....raises: [], tags: [], forbids: [].}
Run JavaScript quickly without waiting for the response. All clients.
event:The event.
script:The Javascript code to execute.
Source   Edit   
proc runtime=(window: Window; runtime: bindings.WebuiRuntime) {....raises: [],
    tags: [], forbids: [].}
Chose a runtime for .js and .ts files.
window:The window to set the runtime for.
runtime:The runtime to set.
Source   Edit   
proc script(window: Window; script: string; timeout: int = 0;
            bufferLen: static[int] = 1024 * 8): tuple[data: string, error: bool]

Run Javascript code script and return the result

Returns a tuple containing the response (data) and whether or not there was an error (error, true if an error occured, false otherwise). If an error occured, the error message will be held in data.

window:The window to run the Javascript code in.
script:The Javascript code to execute.
timeout:The execution timeout in seconds.
bufferLen:How large to make the buffer for the response. Default is 8 kibibytes. (For larger responses make bufferLen larger)
Source   Edit   
proc scriptClient(event: Event; script: string; timeout: int = 0;
                  bufferLen: static[int] = 1024 * 8): tuple[data: string,
    error: bool]

Run Javascript code script and return the result

Returns a tuple containing the response (data) and whether or not there was an error (error, true if an error occured, false otherwise). If an error occured, the error message will be held in data.

event:The event.
script:The Javascript code to execute.
timeout:The execution timeout in seconds.
bufferLen:How large to make the buffer for the response. Default is 8 kibibytes. (For larger responses make bufferLen larger)
Source   Edit   
proc sendRaw(window: Window; function: string; raw: pointer; size: uint) {.
    ...raises: [], tags: [], forbids: [].}
Safely send raw data to the UI. All clients.
window:The window to send the raw data to.
function:The JavaScript function to receive raw data: function myFunc(myData){}
raw:The raw data buffer.
size:The size of the raw data in bytes.
Source   Edit   
proc sendRawClient(event: Event; function: string; raw: pointer; size: uint) {.
    ...raises: [], tags: [], forbids: [].}
Safely send raw data to the UI. All clients.
event:The event.
function:The JavaScript function to receive raw data: function myFunc(myData){}
raw:The raw data buffer.
size:The size of the raw data in bytes.
Source   Edit   
proc setConfig(option: bindings.WebuiConfig; status: bool) {....raises: [],
    tags: [], forbids: [].}
Control WebUI's behaviour via setting configuration option option to either true or false. It's better to this call at the beginning of your program.
option:The desired option from the WebuiConfig enum
status:The status of the option, true or false
Source   Edit   
proc setConfig(options: openArray[bindings.WebuiConfig] or
    set[bindings.WebuiConfig]; status: bool)
Control WebUI's behaviour via setting configuration options options to either true or false. It's better to this call at the beginning of your program.
options:The desired options from the WebuiConfig enum
status:The desired status of all of the options, true or false
Source   Edit   
proc setDefaultRootFolder(path: string): bool {.discardable, ...raises: [],
    tags: [], forbids: [].}
Set the default web-server root folder path for all windows.
Note: Should be used before webui_show().
path:The path to the root folder.

Returns true on success.

Source   Edit   
proc setFileHandler(window: Window; handler: proc (filename: string): string) {.
    ...raises: [], tags: [], forbids: [].}
Same as fileHandler=, but targeted towards use with do notation Source   Edit   
proc setIcon(window: Window; icon, mime: string) {....raises: [], tags: [],
    forbids: [].}
Set the default embedded HTML favicon.
window:The window to set the icon for.
icon:The icon as string: <svg>...</svg>
mime:The MIME type of the icon
Source   Edit   
proc setPos(window: Window; x, y: int) {....raises: [], tags: [], forbids: [].}
Set the window position.
window:The window.
x:The window's X coordinate.
y:The window's Y coordinate.
Source   Edit   
proc setPosition(window: Window; x, y: int) {....raises: [], tags: [], forbids: [].}
Set window position
window:The window to set the size for.
x:What to set the window's X to.
y:What to set the window's Y to.
Source   Edit   
proc setProfile(window: Window; name, path: string) {....raises: [], tags: [],
    forbids: [].}
Set the web browser profile to use. An empty name and path means the default user profile.
Note: Needs to be called before webui_show().
window:The window to set the browser profile for.
name:The web browser profile name.
path:The web browser profile full path.

Example:

window.setProfile("Bar", "/Home/Foo/Bar")
window.setProfile("", "")
Source   Edit   
proc setSize(window: Window; width, height: int) {....raises: [], tags: [],
    forbids: [].}
Set the window size.
window:The window.
width:The window width.
height:The window height.
Source   Edit   
proc setTimeout(timeout: int) {....raises: [], tags: [], forbids: [].}
Set the maximum time in seconds to wait for the window to connect. This will affect show() and wait(). Setting the timeout to 0 will cause WebUI to wait forever.
timeout:The maximum time in seconds to wait for browser to start. Set to 0 to wait forever.
Source   Edit   
proc setTlsCertificate(certificate_pem, private_key_pem: string): bool {.
    ...raises: [], tags: [], forbids: [].}
Set the SSL/TLS certificate and the private key content, both in PEM format. This works only with webui-2-secure library. If set empty, WebUI will generate a self-signed certificate.
certificate_pem:The SSL/TLS certificate content in PEM format
private_key_pem:The private key content in PEM format

Returns true if the certificate and the key are valid.

Source   Edit   
proc show(window: Window; content: string): bool {.discardable, ...raises: [],
    tags: [], forbids: [].}
Show a window using embedded HTML, or a file. If the window is already open, it will be refreshed. This will refresh all windows in multi-client mode.
Important: Please include <script src="/webui.js"></script> in the HTML for proper window communication.
window:The window to show content in. If the window is already shown, the UI will get refreshed in the same window.
content:The content to show in window. Can be a file name, URL, or a static HTML script.

Returns true if showing the window is a success.

Source   Edit   
proc show(window: Window; content: string; browsers: openArray[
    bindings.WebuiBrowser] or
    set[bindings.WebuiBrowser]): bool {.discardable.}
Same as show(), but with a specific set of web browsers to use.
Important: Please include <script src="/webui.js"></script> in the HTML for proper window communication.
window:The window to show content in. If the window is already shown, the UI will get refreshed in the same window.
content:The content to show in window. Can be a file name, or a static HTML script.
browser:The browsers to open the window in.

Returns true if showing the window is a success.

Source   Edit   
proc show(window: Window; content: string; browser: bindings.WebuiBrowser): bool {.
    discardable, ...raises: [], tags: [], forbids: [].}
Same as show(), but with a specific web browser.
Important: Please include <script src="/webui.js"></script> in the HTML for proper window communication.
window:The window to show content in. If the window is already shown, the UI will get refreshed in the same window.
content:The content to show in window. Can be a file name, or a static HTML script.
browser:The browser to open the window in.

Returns true if showing the window is a success.

Source   Edit   
proc showClient(event: Event; content: string): bool {.discardable, ...raises: [],
    tags: [], forbids: [].}
Show a window using embedded HTML, or a file. If the window is already open, it will be refreshed. Single client.
Important: Please include <script src="/webui.js"></script> in the HTML for proper window communication.
event:The event to use.
content:The content to show. Can be a file name, URL, or a static HTML script.

Returns true if showing the window is a success.

Source   Edit   
proc shown(window: Window): bool {....raises: [], tags: [], forbids: [].}
Return if window window is still running
window:The window to return true if still running.
Source   Edit   
proc showWv(window: Window; content: string): bool {.discardable, ...raises: [],
    tags: [], forbids: [].}
Show a WebView window using embedded HTML, or a file. If the window is already open, it will be refreshed.
Note: On Windows, you will need WebView2Loader.dll.
window:The window to show content in. If the window is already shown, the UI will get refreshed in the same window.
content:The content to show in window. Can be a file name, or a static HTML script.

Returns true if showing the WebView window succeeded.

Source   Edit   
proc size=(window: Window; size: tuple[width, height: int]) {.
    ...deprecated: "Use `setSize` instead", raises: [], tags: [], forbids: [].}
Deprecated: Use `setSize` instead
Alias for setSize Source   Edit   
proc startServer(window: Window; path: string): string {....raises: [], tags: [],
    forbids: [].}

Same as show(), but it only starts the web server and returns the URL. This is useful for web apps.

No window will be shown.

window:The window to start the web server for
path:The full path to the local root folder

Returns the url of the window server.

Source   Edit   
proc url(window: Window): string {....raises: [], tags: [], forbids: [].}
Get the full current URL.
window:The window to get the URL from
Source   Edit   
proc wait() {....raises: [], tags: [], forbids: [].}
Wait until all opened windows get closed. Source   Edit   
proc window(event: Event): Window {....raises: [], tags: [], forbids: [].}
Source   Edit  

Macros

macro bindCb(window: untyped; cbFuncName: untyped; cbFunc: typed): untyped
Macro to bind a webui callback function with automatic wrapper generation. The function must be annotated with the webuiCb pragma. Source   Edit   
macro webuiCb(procDef: untyped): untyped

proc pragma to automatically create a WebUI callback wrapper function.

Supported argument types: primitives + Event:

   int : int, int8, int16, int32, int64,
         
         uint, uint, uint8, uint16, uint32, uint64,
         
         cint8, cint16, cint32, cint64,
         
         cshort, cushort, cint, cuint, clong, culong
         
         csize_t, byte
   
   float : float, float32, float64, cfloat, cdouble
   
   string : string, cstring, JsonNode
   
   bool : bool
   
   Event
Supported return types: primitives + void

Example:

import webui

proc getSystemInfo(some_argument : JsonNode): string {.webuiCb.} =
  echo "Received argument: ", some_argument.pretty
  return %*{"key1" : 123, "key2" : "value2"}

proc one() {.webuiCb.} =
  discard

proc two(e1, e2 : Event) {.webuiCb.} =
  discard

when isMainModule:
  let window = newWindow()
  window.bindCb("getInfo", getSystemInfo)
  let html = """
        <!DOCTYPE html>
        <html>  
          <head>
            <script src="/webui.js"></script>
          </head>
          <script>
            function fetchSystemInfo() {
                webui.call('getInfo', '{"a" : 1, "b" : "c"}').then(
                (response) => {
                    document.body.innerHTML = "<pre>" + response + "</pre>";
                }
              );
            }
            setInterval(fetchSystemInfo, 2000);
          </script>
        </html>
      """
  window.show(html)
  wait()
Source   Edit  

Made with Nim. Generated: 2025-12-10 22:23:24 UTC