DOCSEARCHbyAlgolia
Submit Docs

WebUI Documentation

repository·main·Indexed 26 days ago

https://github.com/webui-dev/webui

WebUI is a lightweight, portable library for creating GUI applications using web technologies (HTML/CSS/JS) as the frontend and C/C++ as the backend. It controls existing web browsers or WebViews rather than embedding a heavy engine. The library includes a WebUI Bridge for WebSocket communication, a virtual file system for embedding assets into single executables, and starter kits for C and C++ development across Windows, Linux, and macOS.

Tokens
4K
Snippets
8
Records
33
Agent score
89%

What's inside WebUI

  1. Overview of WebUI

    main
    WebUI is a lightweight, portable library that allows you to use any installed web browser or WebView as a GUI for your application. It enables developers to use modern web technologies (HTML5, CSS, JavaScript) for the frontend while using their preferred language (C, C++, etc.) for the backend. Unlike Electron or Tauri, WebUI does not embed a heavy browser engine, making it highly portable and small in size, as it relies on the user's existing web browser.

  2. Available WebUI C examples

    main

    The following C examples demonstrate various integration patterns with WebUI:

    • minimal: A minimal WebUI application.
    • call_c_from_js: Demonstrates calling C functions from JavaScript.
    • call_js_from_c: Demonstrates calling JavaScript functions from C.
    • serve_a_folder: Serves a folder containing .html, .css, .js, or .ts files.
    • custom_web_server: Integrates WebUI with an external web server like NGINX or Apache to serve a folder.
    • chatgpt_api: Demonstrates calling the ChatGPT API from C.
    • frameless: Shows how to create a frameless window.
    • public_network_access: Configures the application to allow network access from external devices.
    • react: Demonstrates using React with WebUI.
    • virtual_file_system: Shows how to embed files using a virtual file system.
    • test_index_redirect: Tests index fallback and custom entry behavior for paths like /, /sub, and /sub/foo.
    • web_app_multi_client: Demonstrates handling multiple clients.
    • text-editor: A lightweight, portable text editor written in C using WebUI as the GUI library.

  4. Customize the C++ Starter Kit

    main

    You can customize several aspects of the application:

    • App name: Edit APP_NAME in Makefile or GNUmakefile.
    • Frontend: Edit any files in the ui/ directory. Files are automatically re-packed into the executable on every build.
    • Backend: Add C++ functions in src/main.cpp and expose them using win.bind(). Bound functions become global async JavaScript functions.
    • HTTP Routes: Modify http_handler() in src/main.cpp to add custom routes, headers, or dynamic responses. Note that using a custom handler disables WebUI's cookie-based client authentication.
    • Icons:
      • ui/favicon.ico: The Windows executable icon (used by Explorer, taskbar, and WebView).
      • ui/icon.png: The HTML favicon, Linux window/taskbar/launcher icon, and macOS app icon.
    • Window Style: To use a standard OS window instead of a frameless/transparent one, remove the win.set_frameless() and win.set_transparent() calls in src/main.cpp. For browser mode, call win.show() instead of win.show_wv().

  5. Ensure interoperability when updating the Civetweb submodule

    main

    When updating the Civetweb submodule in a project that uses wrappers, you must apply specific preprocessor directives to prevent compiler warnings (such as those for malloc or snprintf) from being triggered by code usage outside of the Civetweb core. This ensures full direct interoperability for the wrappers.

    Apply the following header guards at the beginning of the Civetweb source files to treat them as system headers, which suppresses warnings for the compiler (MSVC, Clang, or GCC).

    + // Disable All Warnings
+ #ifdef _MSC_VER
+ #pragma warning(push, 0)
+ #pragma warning(disable: 4996)
+ #elif defined(__clang__)
+ #pragma clang system_header
+ #elif defined(__GNUC__)
+ #pragma GCC system_header
+ #endif

/* Copyright (c) 2013-2024 the Civetweb developers

  6. Build the WebUI Bridge

    main
    The WebUI Bridge connects the UI (Web Browser) with the backend application via WebSocket. To build it, you must transpile the TypeScript source (webui.ts) to JavaScript using ESBuild to produce webui.js, and then use the js2c.js Node script to convert that JavaScript into the C header webui_bridge.h.

  8. Build the WebUI Library

    main

    You can build the WebUI library from source using various compilers depending on your operating system.

    Windows

    • GCC: Use mingw32-make.
    • MSVC: Use nmake.

    Linux

    • GCC: Use make.
    • Clang: Use make CC=clang.

    macOS

    • Default: Use make.

  9. Build WebUI C examples

    main

    To build any of the C examples, navigate to the specific example's directory and use the appropriate build command for your operating system and compiler:

    Windows

    • GCC (MinGW): Use mingw32-make.
    • MSVC: Use nmake.

    Linux

    • GCC: Use make.
    • Clang: Use make CC=clang.

    macOS

    • Use make.

  11. Customize the WebUI C Starter Kit

    main

    You can customize several aspects of the application:

    • App Name: Edit the APP_NAME variable at the top of Makefile or GNUmakefile.
    • Frontend: Add or modify files in the ui/ directory. These are automatically re-packed into the executable on every build.
    • Backend (C Bindings): Add C functions in src/main.c and expose them using webui_bind(). Bound functions are accessible in JavaScript as global async functions (e.g., const reply = await my_c_function('arg');).
    • Icons:
      • ui/favicon.ico: Used as the Windows executable icon (via icon.rc).
      • ui/icon.png: Used as the HTML favicon, the Linux window/launcher icon, and the macOS app icon.
    • HTTP Handling: Custom routes, headers, or dynamic responses can be added by modifying http_handler() in src/main.c. Note that using a custom file handler disables WebUI's built-in cookie-based client authentication.
    • Window Appearance: By default, src/main.c opens a frameless, transparent WebView. To use a standard OS window, remove the webui_set_frameless() and webui_set_transparent() calls. To run in browser mode, call webui_show() instead of webui_show_wv().

  12. Use the React WebUI Example

    main

    The React WebUI example demonstrates how to use WebUI with React to create a portable single executable program. WebUI runs an internal web server and uses the system's installed web browser as the GUI.

    To rebuild the React project and compile the C source code, run the provided build script: