API documentation 1.2
Cheerp is a C++ compiler for the Web. As so it provides full access to all the capabilities provided by modern browsers. Cheerp is not a framework, so it does not provide any high level construct such as widgets or abstraction layers. You are free to build such capabilities on top of the browser APIs exposed by Cheerp.
This introductory page will show how to use Cheerp to code a client-side application to run on the browser. When using any browser API with Cheerp, you are directly accessing the implementation which provided by the browser. There is no implementation or abstraction layer inside Cheerp.
In the example above you can see that, in Cheerp,
webMain is the entry point of your application. On the other hand traditional C++ applications starts in the
main function, which is not only the entry point of the application, but actually contains the whole program execution, as the program terminates when main returns.
webMain instead is only the entry point of the application, as your program will be executing after webMain returns. In
webMain you should register callbacks for any event you might be interested on, then the browser will invoke the callbacks you registered when the relevant event happens.
If you are porting an existing application, be careful about any object allocated in your
webMain function. Contrarily to the ones allocated in
main they will not be alive for the whole life of the application, but will be destroyed when
Browser APIs are declared inside headers which are provided with Cheerp, namely
All classes, global variables and methods exposed by the browser are declared into the `
You can access the
document global object directly from C++ code. In the next example we will add an event handler to run our code after the DOM is fully loaded.
DOM/JS String can be used from Cheerp through the
client::String object. DOM Strings are immutable data types which are used to pass text to DOM APIs. Given that this is a browser-native implementation, it may be more efficient to manipulate text data using
client::String than equivalent
std::string or plain buffers of
client::String has a constructor which accepts C-style
const char* and can be used to create DOM Strings from C++ string literals or arrays of characters. This constructor will also be invoked implicitly whenever passing a
const char* where a DOM String is expected
Conversion between different string types are computationally intensive and should be avoided where possible. We suggest manipulating Strings from DOM or XMLHttpRequest directly (i.e. no conversion) where possible. Since
client::String is a native implementation, you may consider converting C strings to DOM String to benefit from the efficient implementations provided by the browser.
client::String to std::string is supported through an explicit conversion operator. This means that you need to explicitly tell the compiler you want a conversion to happen.
You can use
client::XMLHttpRequest to load data using HTTP, both in synchronous and asynchronous mode.
DOM objects created using
new, such as the
client::XMLHttpRequest objects in the example above or
client::String objects, do not need to be freed using the C++
delete operator. Generally speaking you should consider all types which are provided by the browser as being managed by the browser itself through the garbage collection mechanism.
The convention used by Cheerp is to declare all the functionalities provided by the browser in the
In the example above
XMLHttpRequest is a class (or an interface) implemented by the browser. All the methods offered by the class are exposed using C++ member functions, all the variables are exposed as getters and setters, recognizable by the
set_ prefix. Currently most of the Web APIs which are exposed in the
clientlib.h header are automatically generated from TypeScript headers.