Ultralight

The Ultralight Developer Hub

Welcome to the Ultralight developer hub. You'll find comprehensive guides and documentation to help you start working with Ultralight as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Writing Your First App

Ultralight enables you to build your application's GUI with web pages and C/C++.

This gives you the best of both worlds-- beautiful, fast, modern web UI with the power and performance of native code.

1. Install the prerequisites

Install the prequisites for your platform if you haven't already done so.

2. Clone and build the Quick Start repository

Clone and build the code in the ultralight-ux/ultralight-quick-start repository.

git clone https://github.com/ultralight-ux/ultralight-quick-start
cd ultralight-quick-start
mkdir build
cd build
cmake ..
cmake --build . --config Release

Building 64-bit projects on Windows

If you run the command cmake .. without any generators on Windows, it will usually select the default 32-bit Visual Studio version you have installed. To force CMake to generate 64-bit projects instead, use cmake .. -DCMAKE_GENERATOR_PLATFORM=x64 instead of cmake ..

3. Run the app

On macOS and Linux

Navigate to ultralight-quick-start/build and run MyApp to launch the program.

On Windows

Navigate to ultralight-quick-start/build/Release and run MyApp to launch the program.

4. Understanding the folder layout

The quick start project is organized with the following structure:

ultralight-quick-start/
  ├── assets/           # HTML resources to bundle with app
  ├── cmake/            # CMake scripts to automate build
  ├── src/              # C/C++ source files
  └── CMakeLists.txt    # CMake project file, edit this to customize your app

Assets Folder

You should place all your web-page resources (eg, HTML files, JS files, CSS files, images, etc.) inside the assets folder. Anything in this directory will be bundled with the application post-build.

You can access these resources via file:/// in your C++ and HTML code, for example:

void MyApp::InitializeView() {
  // Load "app.html" from the "assets" directory
  myView->LoadURL("file:///app.html");
}

5. Customizing the application name

Open up CMakeLists.txt in your favorite text editor, you should see:

project(MyApp C CXX)
cmake_minimum_required(VERSION 2.8.12)

include(cmake/App.cmake)

set(SOURCES "src/MyApp.h"
            "src/MyApp.cpp"
            "src/main.cpp")

add_app("${SOURCES}")

The add_app() function

If you've used CMake before, you probably won't recognize the add_app() function.

This is a special function provided by App.cmake that generates a cross-platform Ultralight app-- it automatically pulls down the latest Ultralight SDK, builds an executable from a list of C++ source files, copies assets, and bundles a custom Info.plist on macOS (you can modify the base template in cmake/Info.plist.in).

By default, add_app() uses the name of the project as the name of the executable, therefore, to change the name of the app all you have to do is rename the project() declaration:

# Change our app name to CoolApp
project(CoolApp C CXX)

After you've done that, regenerate CMake build scripts and rebuild:

cd build
cmake ..
cmake --build . --config Release --clean-first

6. Customizing the window title

To change the title of the window, we will need to dive into the C++ source code for our app.

Open up src/MyApp.cpp and find the following lines:

  ///
  /// Set the title of our window.
  ///
  window_->SetTitle("MyApp");

Change the string to something like "My Awesome App!" and save the file:

  ///
  /// Set the title of our window.
  ///
  window_->SetTitle("My Awesome App!");

After you've done that, rebuild the app to see your changes:

cd build
cmake --build . --config Release --clean-first

6. Editing the HTML assets

Let's start editing our HTML assets.

Open up assets/app.html and find the following lines:

  <body>
    <h1>Hello World!</h1>
  </body>

Change the HTML to display another welcome message, like "Welcome to My App!":

  <body>
    <h1>Welcome to My App!</h1>
  </body>

After you've done that, rebuild the app to see your changes:

cd build
cmake --build . --config Release --clean-first

Updated 2 months ago


What's Next

Now that you've got a simple app working, you can start learning more complex API topics by trying the samples:

Trying the Samples

Writing Your First App


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.