Writing Your First App

Ultralight enables you to build your C/C++ app's front-end with HTML/JS/CSS.

This gives you the best of both worlds-- fast, beautiful, 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
cmake -B build
cmake --build build --config Release

👍
Make sure to use Clang when compiling on Linux
If you run into compilation issues on Linux, make sure you've selected Clang instead of GCC as your default compiler.
Set your CC and CXX environment variables before running CMake again (you may need to delete your build directory)
export CC=/usr/bin/clang
export CXX=/usr/bin/clang++

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:

cmake --build 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:

cmake --build 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:

cmake --build build --config Release --clean-first