App

#include <AppCore/App.h>

Overview

Main application singleton (use this if you want to let the library manage window creation).

This convenience class sets up everything you need to display web-based content in a desktop application.

The App class initializes the Platform singleton with OS-specific defaults, creates a Renderer, and automatically manages window creation, run loop, input events, and painting.

Creating the App

Call App::Create() to initialize the library and create the App singleton.

auto app = App::Create();

Creating a Window

Call Window::Create() to create one or more windows during the lifetime of your app.

auto window = Window::Create(app->main_monitor(), 1024, 768, false,
                             WindowFlags::Titled | WindowFlags::Resizable);

Adding a Panel to a Window

A window's content is a layout of panels, each showing a View. A bare AddPanel() fills the whole window.

auto panel = window->AddPanel();

Each Panel has a View instance that you can use to load web content into.

panel->view()->LoadURL("https://google.com");

Running the App

Call App::Run() to start the main run loop.

#include <AppCore/AppCore.h>
 
using namespace ultralight;
 
int main() {
  // Initialize app, window, panels, etc. here...
 
  app->Run();
 
  return 0;
}

Shutting Down the App

Call App::Quit() to stop the main run loop and shut down the app.

app->Quit();

Note

This is optional, you can use the Renderer class directly if you want to manage your own windows and run loop.

Inheritance diagram for App:

Static Public Member Functions
static RefPtr< App >	Create (Settings settings=Settings(), Config config=Config())
	Create the App singleton.
static App *	instance ()
	Get the App singleton (nullptr before App::Create()).

Public Member Functions
virtual const Settings &	settings () const =0
	Get the settings this App was created with.
virtual void	set_listener (AppListener *listener)=0
	Set an AppListener to receive callbacks for app-related events.
virtual AppListener *	listener ()=0
	Get the AppListener (can be nullptr).
virtual bool	is_running () const =0
	Whether or not the App is running.
virtual Monitor *	main_monitor ()=0
	Get the main monitor (this is never NULL).
virtual uint32_t	monitor_count () const
	Get the number of connected monitors.
virtual Monitor *	monitor (uint32_t index)
	Get a monitor by index (from 0 to monitor_count() - 1).
virtual RefPtr< Renderer >	renderer ()=0
	Get the underlying Renderer instance.
virtual void	Run ()=0
	Run the main loop (this returns after Quit()).
virtual void	Quit ()=0
	Quit the application.
virtual bool	RunOnce (double max_wait_seconds=0.0)=0
	Advance the app by one iteration of the main loop, on behalf of your own run loop.
virtual void	PostTask (void(*task)(void *user_data), void *user_data, void(*destroy_user_data)(void *user_data)=nullptr)=0
	Post a task to run on the main thread during a future update of the app's loop.
virtual void	PostDelayedTask (double delay_ms, void(*task)(void *user_data), void *user_data, void(*destroy_user_data)(void *user_data)=nullptr)=0
	Post a task to run on the main thread once a delay has elapsed.
virtual TimerHandle	SetInterval (double interval_ms, void(*callback)(void *user_data), void *user_data, void(*destroy_user_data)(void *user_data)=nullptr)=0
	Create a repeating timer that fires on the main thread.
template<typename F, typename = std::enable_if_t<std::is_invocable_v<std::decay_t<F>&>>>
void	PostTask (F &&callback)
	Post a callable to run on the main thread during a future update of the app's loop.
template<typename F, typename = std::enable_if_t<std::is_invocable_v<std::decay_t<F>&>>>
void	PostDelayedTask (double delay_ms, F &&callback)
	Post a callable to run on the main thread once a delay has elapsed.
template<typename F, typename = std::enable_if_t<std::is_invocable_v<std::decay_t<F>&>>>
TimerHandle	SetInterval (double interval_ms, F &&callback)
	Create a repeating timer that invokes a callable on the main thread.
virtual bool	is_idle () const =0
	Whether or not the app is currently considered idle (low CPU utilization and no recent user input, sustained past the configured threshold).
virtual double	thread_utilization () const =0
	Get the current main-thread CPU utilization (0.0-1.0), averaged over the last ~1 second.
virtual bool	GetGPUMemoryStats (GPUMemoryStats &stats)
	Get GPU memory statistics from the App's GPU driver.
virtual bool	is_profiler_active () const =0
	Whether or not the built-in profiler is active (see Settings::enable_profiler).
virtual const char *	profiler_trace_path () const =0
	Get the file path of the active profiler trace file.
Public Member Functions inherited from RefCounted
virtual void	AddRef () const =0
	Increment the reference count (thread-safe).
virtual void	Release () const =0
	Decrement the reference count (thread-safe).
virtual int	ref_count () const =0
	Get the current reference count.
virtual WeakControlBlock *	weak_control_block () const
	Get the control block used to track weak references to this object.

Protected Member Functions
virtual	~App ()
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

~App()

virtual ~App ( )

protectedvirtual

Member Function Documentation

Create()

RefPtr< App > Create ( Settings settings = Settings(), Config config = Config() )

static

Create the App singleton.

Parameters

settings	Settings to customize App runtime behavior.
config	Config options for the Ultralight renderer.

Returns

Returns a ref-pointer to the created App instance.

Note

You should only create one App per application lifetime.

Note

App::Create() adjusts a few Config fields: it always sets Config::face_winding to FaceWinding::Clockwise, fills in Config::cache_path when you leave it empty, and picks Config::font_profile while Settings::auto_font_profile is on.

Note

A platform handler you set on Platform::instance() before App::Create() is kept (eg, your own FileSystem, FontLoader, Logger, or Clipboard). App::Create() only installs its default for a handler you left unset. A GPUDriver or SurfaceFactory you set beforehand is kept too, but AppCore windows can't present Views with it.

GetGPUMemoryStats()

virtual bool GetGPUMemoryStats ( GPUMemoryStats & stats )

inlinevirtual

Get GPU memory statistics from the App's GPU driver.

Statistics cover the GPU resources the library has allocated through the active GPU backend (textures, render targets, geometry, swap chains) plus process-wide video memory usage and budget reported by the operating system. See GPUMemoryStats for per-field details and accuracy notes.

Parameters

stats

Structure to fill. All fields are overwritten on success.

Returns

Returns true if stats was filled. Returns false when rendering with the CPU renderer or when the active GPU backend does not provide memory statistics.

Note

Among the stock GPU drivers, the Direct3D backends on Windows, the Metal backend on macOS, and the OpenGL backend on Linux implement this (OpenGL reports no process usage or budget).

instance()

App * instance ( )

static

Get the App singleton (nullptr before App::Create()).

is_idle()

virtual bool is_idle ( ) const

pure virtual

Whether or not the app is currently considered idle (low CPU utilization and no recent user input, sustained past the configured threshold).

Note

This reads true once idle conditions have held for at least Settings::idle_threshold, even before the first AppListener::OnIdle() callback fires.

is_profiler_active()

virtual bool is_profiler_active ( ) const

pure virtual

Whether or not the built-in profiler is active (see Settings::enable_profiler).

This is true when Settings::enable_profiler is set, you didn't set your own profiler with Platform::set_profiler(), and your edition includes the profiler (Pro or higher).

is_running()

virtual bool is_running ( ) const

pure virtual

Whether or not the App is running.

listener()

virtual AppListener * listener ( )

pure virtual

Get the AppListener (can be nullptr).

main_monitor()

virtual Monitor * main_monitor ( )

pure virtual

Get the main monitor (this is never NULL).

monitor()

virtual Monitor * monitor ( uint32_t index )

inlinevirtual

Get a monitor by index (from 0 to monitor_count() - 1).

Index 0 is always the main monitor.

You can pass the returned monitor to Window::Create() to open a window on that display.

Parameters

index

The index of the monitor to get.

Returns

Returns the monitor, or nullptr when index is out of range.

Note

The returned pointer is owned by the App and remains valid for the lifetime of the App. If a monitor is disconnected, it is no longer enumerated, but its pointer remains safe to use and its accessors return fallback values.

monitor_count()

virtual uint32_t monitor_count ( ) const

inlinevirtual

Get the number of connected monitors.

PostDelayedTask() [1/2]

template<typename F, typename = std::enable_if_t<std::is_invocable_v<std::decay_t<F>&>>>

void PostDelayedTask ( double delay_ms, F && callback )

inline

Post a callable to run on the main thread once a delay has elapsed.

Convenience overload of PostDelayedTask(). See PostTask() for the callable's lifetime.

Parameters

delay_ms	The delay before the callable runs, in milliseconds.
callback	The callable to invoke.

PostDelayedTask() [2/2]

virtual void PostDelayedTask ( double delay_ms, void(* task )(void *user_data), void * user_data, void(* destroy_user_data )(void *user_data) = nullptr )

pure virtual

Post a task to run on the main thread once a delay has elapsed.

The task runs on the first update tick after the delay elapses (ticks are about 2 ms apart).

Parameters

delay_ms	The delay before the task runs, in milliseconds.
task	Invoked once on the main thread.
user_data	Passed to task (can be nullptr).
destroy_user_data	Invoked exactly once after task runs, or without task running if the App is destroyed first (can be nullptr).

Note

Safe to call from any thread (it wakes the main loop like PostTask()).

See also

PostTask()

PostTask() [1/2]

template<typename F, typename = std::enable_if_t<std::is_invocable_v<std::decay_t<F>&>>>

void PostTask ( F && callback )

inline

Post a callable to run on the main thread during a future update of the app's loop.

Convenience overload of PostTask(). The callable is invoked once on the main thread, then destroyed (without being invoked if the App is destroyed first).

Parameters

callback

The callable to invoke. Capture by value when posting from another thread.

PostTask() [2/2]

virtual void PostTask ( void(* task )(void *user_data), void * user_data, void(* destroy_user_data )(void *user_data) = nullptr )

pure virtual

Post a task to run on the main thread during a future update of the app's loop.

Tasks run in posting order, sharing one queue with Renderer::PostTask().

Parameters

task	Invoked once on the main thread.
user_data	Passed to task (can be nullptr).
destroy_user_data	Invoked exactly once after task runs, or without task running if the App is destroyed first (can be nullptr).

Note

Safe to call from any thread. Posting wakes the main loop, so a task posted from another thread runs without waiting for the next timer tick.

profiler_trace_path()

virtual const char * profiler_trace_path ( ) const

pure virtual

Get the file path of the active profiler trace file.

Returns

Returns the path to the trace file, or an empty string when is_profiler_active() reads false.

Quit()

virtual void Quit ( )

pure virtual

Quit the application.

Stops the main loop so Run() returns; the process itself is not exited.

Note

On macOS, a Quit() issued while a modal loop is running (eg, a native message box or an interactive window drag) is absorbed by that inner loop and does not end Run()– call Quit() again once the modal loop has finished.

renderer()

virtual RefPtr< Renderer > renderer ( )

pure virtual

Get the underlying Renderer instance.

Run()

virtual void Run ( )

pure virtual

Run the main loop (this returns after Quit()).

RunOnce()

virtual bool RunOnce ( double max_wait_seconds = 0.0 )

pure virtual

Advance the app by one iteration of the main loop, on behalf of your own run loop.

This pumps pending OS events, updates the renderer, and refreshes the display and repaints windows once the display interval has elapsed. When no events are pending, it waits up to max_wait_seconds for one.

You should call this repeatedly from your own loop instead of calling Run().

Parameters

max_wait_seconds

The longest this call may block waiting for an event or timer tick. Pass 0.0 to return immediately after processing whatever is pending.

Returns

Returns whether or not the app is still running (false once Quit() has been called).

Note

On macOS this pumps the event queue manually rather than running the native run loop, so menu key-equivalent routing can differ from Run().

set_listener()

virtual void set_listener ( AppListener * listener )

pure virtual

Set an AppListener to receive callbacks for app-related events.

Parameters

listener

A user-defined AppListener implementation, ownership remains with the caller. Pass a nullptr to remove the current listener.

SetInterval() [1/2]

template<typename F, typename = std::enable_if_t<std::is_invocable_v<std::decay_t<F>&>>>

TimerHandle SetInterval ( double interval_ms, F && callback )

inlinenodiscard

Create a repeating timer that invokes a callable on the main thread.

Convenience overload of SetInterval(). The callable is destroyed when the timer is canceled or the App is destroyed.

Parameters

interval_ms	The time between fires, in milliseconds.
callback	The callable to invoke on each fire.

Returns

Returns a handle that owns the timer. Destroy it (or call TimerHandle::Cancel()) to stop the timer.

SetInterval() [2/2]

virtual TimerHandle SetInterval ( double interval_ms, void(* callback )(void *user_data), void * user_data, void(* destroy_user_data )(void *user_data) = nullptr )

nodiscardpure virtual

Create a repeating timer that fires on the main thread.

The timer fires on the first update tick after each interval elapses (ticks are about 2 ms apart). Fires missed while the loop was stalled are skipped– the timer resumes on its interval.

Parameters

interval_ms	The time between fires, in milliseconds.
callback	Invoked on each fire, on the main thread.
user_data	Passed to callback (can be nullptr).
destroy_user_data	Invoked exactly once when the timer is canceled or the App is destroyed, and never while callback is running (a timer may cancel itself from its own callback). Can be nullptr.

Returns

Returns a handle that owns the timer. Destroy it (or call TimerHandle::Cancel()) to stop the timer.

Note

Safe to call from any thread (it wakes the main loop like PostTask()).

settings()

virtual const Settings & settings ( ) const

pure virtual

Get the settings this App was created with.

thread_utilization()

virtual double thread_utilization ( ) const

pure virtual

Get the current main-thread CPU utilization (0.0-1.0), averaged over the last ~1 second.

You can use this to make adaptive scheduling decisions.

---

The documentation for this class was generated from the following file:

• AppCore/App.h