Ultralight C++ API 1.3.0
Loading...
Searching...
No Matches
App.h
Go to the documentation of this file.
1/******************************************************************************
2 * This file is a part of Ultralight, an ultra-portable web-browser engine. *
3 * *
4 * See <https://ultralig.ht> for licensing and more. *
5 * *
6 * (C) 2023 Ultralight, Inc. *
7 *****************************************************************************/
8#pragma once
9#include "Defines.h"
10#include <Ultralight/RefPtr.h>
11#include <Ultralight/Renderer.h>
13
14namespace ultralight {
15
16class Monitor;
17class Window;
18
19///
20/// Interface for all App-related events. @see App::set_listener
21///
23public:
24 virtual ~AppListener() {}
25
26 ///
27 /// Called whenever the App updates. You should update all app logic here.
28 ///
29 /// @note This event is fired right before the run loop calls
30 /// Renderer::Update and Renderer::Render.
31 ///
32 virtual void OnUpdate() {}
33};
34
35///
36/// App-specific settings.
37///
39 ///
40 /// The name of the developer of this app.
41 ///
42 /// This is used to generate a unique path to store local application data
43 /// on the user's machine.
44 ///
45 String developer_name = "MyCompany";
46
47 ///
48 /// The name of this app.
49 ///
50 /// This is used to generate a unique path to store local application data
51 /// on the user's machine.
52 ///
53 String app_name = "MyApp";
54
55 ///
56 /// The root file path for our file system. You should set this to the
57 /// relative path where all of your app data is.
58 ///
59 /// This will be used to resolve all file URLs, eg file:///page.html
60 ///
61 /// @note This relative path is resolved using the following logic:
62 /// - Windows: relative to the executable path
63 /// - Linux: relative to the executable path
64 /// - macOS: relative to YourApp.app/Contents/Resources/
65 ///
66 String file_system_path = "./assets/";
67
68 ///
69 /// Whether or not we should load and compile shaders from the file system
70 /// (eg, from the /shaders/ path, relative to file_system_path).
71 ///
72 /// If this is false (the default), we will instead load pre-compiled shaders
73 /// from memory which speeds up application startup time.
74 ///
75 bool load_shaders_from_file_system = false;
76
77 ///
78 /// We try to use the GPU renderer when a compatible GPU is detected.
79 ///
80 /// Set this to true to force the engine to always use the CPU renderer.
81 ///
82 bool force_cpu_renderer = false;
83};
84
85///
86/// Main application singleton (use this if you want to let the library manage window creation).
87///
88/// This convenience class automatically sets up the Renderer, creates a run loop, and handles all
89/// painting and platform-specific operations for you.
90///
91class AExport App : public RefCounted {
92public:
93 ///
94 /// Create the App singleton.
95 ///
96 /// @param settings Settings to customize App runtime behavior.
97 ///
98 /// @param config Config options for the Ultralight renderer.
99 ///
100 /// @return Returns a ref-pointer to the created App instance.
101 ///
102 /// @note You should only create one of these per application lifetime.
103 ///
104 /// @note Certain Config options may be overridden during App creation,
105 /// most commonly Config::face_winding and Config::cache_path.
106 ///
107 static RefPtr<App> Create(Settings settings = Settings(), Config config = Config());
108
109 ///
110 /// Get the App singleton.
111 ///
112 static App* instance();
113
114 ///
115 /// Get the settings this App was created with.
116 ///
117 virtual const Settings& settings() const = 0;
118
119 ///
120 /// Set an AppListener to receive callbacks for app-related events.
121 ///
122 /// @note Ownership remains with the caller.
123 ///
124 virtual void set_listener(AppListener* listener) = 0;
125
126 ///
127 /// Get the AppListener, if any.
128 ///
129 virtual AppListener* listener() = 0;
130
131 ///
132 /// Whether or not the App is running.
133 ///
134 virtual bool is_running() const = 0;
135
136 ///
137 /// Get the main monitor (this is never NULL).
138 ///
139 /// @note We'll add monitor enumeration later.
140 ///
141 virtual Monitor* main_monitor() = 0;
142
143 ///
144 /// Get the underlying Renderer instance.
145 ///
147
148 ///
149 /// Run the main loop.
150 ///
151 virtual void Run() = 0;
152
153 ///
154 /// Quit the application.
155 ///
156 virtual void Quit() = 0;
157
158protected:
159 virtual ~App();
160};
161
162} // namespace ultralight
#define AExport
Definition Defines.h:42
Main application singleton (use this if you want to let the library manage window creation).
Definition App.h:91
virtual Monitor * main_monitor()=0
Get the main monitor (this is never NULL).
virtual void set_listener(AppListener *listener)=0
Set an AppListener to receive callbacks for app-related events.
virtual ~App()
virtual void Quit()=0
Quit the application.
virtual bool is_running() const =0
Whether or not the App is running.
virtual AppListener * listener()=0
Get the AppListener, if any.
static App * instance()
Get the App singleton.
static RefPtr< App > Create(Settings settings=Settings(), Config config=Config())
Create the App singleton.
virtual RefPtr< Renderer > renderer()=0
Get the underlying Renderer instance.
virtual void Run()=0
Run the main loop.
virtual const Settings & settings() const =0
Get the settings this App was created with.
Interface for all App-related events.
Definition App.h:22
virtual void OnUpdate()
Called whenever the App updates.
Definition App.h:32
virtual ~AppListener()
Definition App.h:24
Monitor class, represents a platform monitor.
Definition Monitor.h:16
Interface for all ref-counted objects that will be managed using the RefPtr<> smart pointer.
Definition RefPtr.h:47
A nullable smart pointer.
Definition RefPtr.h:79
UTF-8 String container with conversions for UTF-16 and UTF-32.
Definition String.h:21
Window class, represents a platform window.
Definition Window.h:87
Definition App.h:14
Global config for Ultralight.
Definition Config.h:72
App-specific settings.
Definition App.h:38