RmlUi Documentation

https://mikke89.github.io/RmlUiDoc
Admin
RmlUi is a C++ user interface library based on HTML and CSS standards, offering a powerful way to...
Tokens:132,972
Snippets:1,548
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Filter Parameter Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/interfaces/render.html

Example of how to fetch a filter parameter, specifically the 'value' for brightness. A value of 1 has no effect.

```cpp
float brightness = Rml::Get(parameters, "value", 0.f);

```

--------------------------------

### Animate and Add Animation Key Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/animations_transforms.html

Demonstrates starting an animation with specific transform properties and then adding another keyframe to extend it. Uses Elastic tweening for both.

```cpp
auto p1 = Transform::MakeProperty({ Transforms::Rotate2D{10.f}, Transforms::TranslateX{100.f} });
auto p2 = Transform::MakeProperty({ Transforms::Scale2D{3.f} });
el->Animate("transform", p1, 1.8f, Tween( Tween::Elastic, Tween::InOut ), -1, true);
el->AddAnimationKey("transform", p2, 1.3f, Tween( Tween::Elastic, Tween::InOut ));
```

--------------------------------

### Basic Font Loading Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/fonts.html

A simple example demonstrating how to load a font file using its path. The font's properties will be inferred from the file itself.

```cpp
Rml::LoadFontFace("data/trilobyte.ttf");
```

--------------------------------

### Basic Conic Gradient Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/conic_gradient.html

Provides basic examples of conic gradients with different configurations. These illustrate simple color transitions and angle/position settings.

```rcss
.gradient1 {
    decorator: conic-gradient(red, yellow);
}
.gradient2 {
    decorator: conic-gradient(from 90deg at 75% 50%, red, yellow);
}
.gradient3 {
    decorator: conic-gradient(from 45deg, white, black, white);
}
```

--------------------------------

### Create Build Directory

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Create a build directory and navigate into it to start the CMake configuration process.

```bash
mkdir Build
cd Build
```

--------------------------------

### Install Dependencies with vcpkg

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Install necessary dependencies like FreeType and GLFW using vcpkg. This is a prerequisite for building RmlUi with specific backends and samples.

```bash
vcpkg install freetype glfw

```

--------------------------------

### Install Custom File Interface - RmlUi

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/interfaces.html

Instantiate and install a custom file interface before RmlUi initialization. Ensure the interface remains alive until Rml::Shutdown() and is cleaned up afterwards.

```cpp
auto file_interface = std::make_unique<CustomFileInterface>();
Rml::SetFileInterface(file_interface.get());

/* ... */

Rml::Initalise();

/* ... */

Rml::Shutdown();

file_interface.reset();

```

--------------------------------

### Margin Shorthand Registration Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/rcss.html

An example of registering the 'margin' shorthand property in C++. This maps the 'margin' shorthand to its individual directional properties.

```cpp
Rml::StyleSheetSpecification::RegisterShorthand("margin", "margin-top, margin-right, margin-bottom, margin-left");
```

--------------------------------

### Getting the Data Model Handle

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/model.html

Retrieves a handle to the data model, which can be used for further interaction after setup.

```cpp
DataModelHandle DataModelConstructor::GetModelHandle() const;

```

--------------------------------

### Tiled Box Decorator Example with Spritesheet

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/tiled_box.html

An example demonstrating the use of the tiled-box decorator with a spritesheet to create a resizable window background. It defines sprite regions and applies them to the decorator.

```rcss
@spritesheet demo-sheet
{
	src: /assets/invader.tga;

	window-tl: 0px 0px 133px 140px;
	window-t:  134px 0px 1px 140px;
	window-tr: 136px 0px 10px 140px;
	window-l:  0px 139px 10px 1px;
	window-c:  11px 139px 1px 1px;
	window-r:  10px 139px -10px 1px; /* mirrored left */
	window-bl: 0px 140px 11px 11px;
	window-b:  11px 140px 1px 11px;
	window-br: 136px 140px 10px 11px;
}

.tiled-box {
	decorator: tiled-box(
		window-tl, window-t, window-tr,
		window-l, window-c, window-r,
		window-bl, window-b, window-br
	);
}

```

--------------------------------

### Install RmlUi via vcpkg

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Install RmlUi using the vcpkg package manager. This command handles downloading and building the library along with its dependencies.

```bash
vcpkg install rmlui

```

--------------------------------

### Scalar Type Conversion Example

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/model.html

Example of registering Rml::Colourb as a Scalar type, including custom getter and setter functions for string conversion.

```cpp
constructor.RegisterScalar<Rml::Colourb>(
	[](const Rml::Colourb& color, Rml::Variant& variant) {
		variant = "rgba(" + Rml::ToString(color) + ')';
	},
	[](Rml::Colourb& color, const Rml::Variant& variant) {
		Rml::String str = variant.Get<Rml::String>();
		bool success = false;
		if (str.size() > 6 && str.substr(0, 5) == "rgba(")
			success = Rml::TypeConverter<Rml::String, Rml::Colourb>::Convert(str.substr(5), color);
		if (!success)
			Rml::Log::Message(Rml::Log::LT_WARNING, "Invalid color specified: '%s'. Use syntax rgba(R,G,B,A).", str.c_str());
	}
);
```

--------------------------------

### Repeating Conic Gradient Button Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/conic_gradient.html

Demonstrates a button styled with a repeating conic gradient. This example showcases setting the gradient angle, colors, and their positions.

```rcss
button {
    decorator: repeating-conic-gradient(from 90deg, #ffd700, #f06, #ffd700 180deg);
    box-sizing: border-box;
    width: 200px;
    height: 100px;
    line-height: 100px;
    border-radius: 15px;
    border: 3px #ffd700;
    padding: 10px 35px;
    font-size: 30px;
    color: white;
    font-weight: bold;
    letter-spacing: 1px;
    font-effect: glow(3px #ff6a), outline(2px #0003);
}
```

--------------------------------

### Serve Compiled Samples

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Start a local Python 3 HTTP server to serve the compiled RmlUi samples for web browser access.

```bash
python3 -m http.server
```

--------------------------------

### Box Shadow Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/colours_backgrounds.html

Demonstrates various ways to apply box shadows, including single, multiple, inset, stacked, and colorful shadows.

```rcss
/* Single box shadow */
box-shadow: #000a 5px 5px 5px;
```

```rcss
/* Multiple box shadows */
box-shadow: #f008 40px 30px 0px 0px, #00f8 -40px -30px 0px 0px;
```

```rcss
/* Inset box shadow */
box-shadow: #000a 5px 5px 5px inset;
```

```rcss
/* Stacked box shadows */
box-shadow:
    #f66 30px 30px 0 0,
    #c88 60px 60px 0 0,
    #baa 90px 90px 0 0;
```

```rcss
/* Colorful box shadows */
box-shadow:
    #f00f  40px  30px 25px 0px,
    #00ff -40px -30px 45px 0px,
    #0f08 -60px  70px 60px 0px,
    #333a  0px  0px 30px 15px inset;
```

--------------------------------

### Configure CMake with Preset

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Configure CMake using a preset, for example, the 'dev-all' preset which enables testing and all samples.

```bash
cmake -B Build --preset <preset>
```

--------------------------------

### Image Decorator Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/image.html

Demonstrates various ways to use the image decorator with different properties like fit modes, alignment, and paint areas.

```rcss
.star {
    decorator: image("star.png" cover);
}
```

```rcss
.top-right-aligned-sprite {
    decorator: image(icon-invader scale-none 70% 30%);
}
```

```rcss
.repeat {
    decorator: image("/assets/alien_small.tga" repeat);
}
```

```rcss
.custom-border {
    border-width: 20px 10px;
    border-color: transparent;
    decorator: image("my-custom-border.png") border-box;
}
```

--------------------------------

### RML Label and Input Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rml/forms.html

Demonstrates associating a label with an input element. The first example shows an inline association, while the second uses explicit 'for' and 'id' attributes for a clearer separation.

```RML
<label><input type="checkbox" value="pizza"/> Pizza</label>

<div class="left">
	<input type="checkbox" value="pasta" id="pasta"/>
</div>
<div class="right">
	<label for="pasta">Pasta</label>
</div>
```

--------------------------------

### Instancing a Generic Div Element

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/elements.html

Example of instancing a basic 'div' element using the Factory. The parent is null, and the instancer and tag are both 'div'.

```cpp
Rml::ElementPtr div_element = Rml::Factory::InstanceElement(nullptr,
                                                                            "div",
                                                                            "div",
                                                                            Rml::XMLAttributes());

```

--------------------------------

### RML with English Strings

Source: https://mikke89.github.io/RmlUiDoc/pages/localisation.html

Example of RML content with hardcoded English strings before localisation.

```rml
<rml>
	<head>
		<title>Quit?</title>
	</head>
	<body>
		<p>Are you sure you want to end this game?</p>
		<button>Yes</button>
		<button>No!</button>
	</body>
</rml>


```

--------------------------------

### Setup Data Model in C++

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/examples.html

Initializes a data model in C++ by binding variables to a struct. This function should be called once before loading the RML document.

```cpp
using namespace Rml;

struct MyData {
	String title = "Hello World!";
	String animal = "dog";
	bool show_text = true;
} my_data;

bool SetupDataBinding(Context* context, DataModelHandle& my_model)
{
	DataModelConstructor constructor = context->CreateDataModel("my_model");
	if (!constructor)
		return false;

	constructor.Bind("title", &my_data.title);
	constructor.Bind("animal", &my_data.animal);
	constructor.Bind("show_text", &my_data.show_text);

	my_model = constructor.GetModelHandle();

	return true;
}

```

--------------------------------

### Image Color and Decorator Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/colours_backgrounds.html

Applies a semi-transparent color overlay to an image using the 'image-color' property and specifies an image decorator.

```rcss
image-color: rgba(255, 160, 160, 200);
decorator: image( background.png );
```

--------------------------------

### Expanded 'data-for' Loop Example

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/views_and_controllers.html

Illustrates how a 'data-for' loop expands into multiple elements, including a hidden element for empty arrays.

```html
<p data-class-selected="i == selected_subject">{{i + ': ' + subject}}</p>
<p data-class-selected="i == selected_subject">{{i + ': ' + subject}}</p>
<p data-class-selected="i == selected_subject">{{i + ': ' + subject}}</p>
<p style="display: none;"/>
```

--------------------------------

### Tiled Box Decorator Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators.html

Declares a tiled-box decorator using multiple sprite names for different parts of the tile.

```rcss
decorator: tiled-box(
	window-tl, window-t, window-tr,
	window-l, window-c, window-r,
	window-bl, window-b, window-br
);

```

--------------------------------

### RML Fragment Example for Block Elements

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/visual_formatting_model.html

Illustrates the structure of RML elements and how they are processed as block or inline, affecting box generation.

```RML
<div>
	<div>
	</div>
	<p>
		<img />
	</p>
</div>

```

--------------------------------

### Register Property with Default Value

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/rcss.html

Example of registering a new user-defined property named 'click-sound' with a default value of 'none' and no inheritance.

```cpp
Rml::StyleSheetSpecification::RegisterProperty("click-sound", "none", false);
```

--------------------------------

### Progress Bar RCSS Styling

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/element_packages/progress_bar.html

RCSS example demonstrating how to style different types of progress bars using spritesheets and decorators.

```rcss
@spritesheet progress_bars
{
	src: my_progress_bars.tga;
	gauge:             0px 271px 100px 86px;
	gauge-fill:        0px 356px 100px 86px;
	progress:        103px 267px  80px 34px;
	progress-fill-l: 110px 302px   6px 34px;
	progress-fill-c: 140px 302px   6px 34px;
	progress-fill-r: 170px 302px   6px 34px;
}
.gauge { 
	decorator: image( gauge );
	width: 100px;
	height: 86px;
	fill-image: gauge-fill;
}
.horizontal { 
	decorator: image( progress );
	width: 80px;
	height: 34px;
}
.horizontal fill {
	decorator: tiled-horizontal( progress-fill-l, progress-fill-c, progress-fill-r );
	margin: 0 7px;
	/* padding ensures that the decorator has a minimum width when the value is zero */
	padding-left: 14px;
}
.vertical {
	width: 30px;
	height: 80px;
	background-color: #E3E4E1;
	border: 4px #A90909;
}
.vertical fill {
	border: 3px #4D9137;
	background-color: #7AE857;
}
```

--------------------------------

### Registering a Custom Decorator Instancer

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/decorators.html

Example of how to create a unique pointer to a custom decorator instancer and register it with RmlUi using its name.

```cpp
// Keep instancer alive until after the call to Rml::Shutdown().
auto instancer = std::make_unique<CustomDecoratorInstancer>();
Rml::Factory::RegisterDecoratorInstancer("custom-decorator", instancer.get());

```

--------------------------------

### Registering Custom Property and Parser

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/rcss.html

Example of how to register a custom property with RCSS and associate it with a custom parser. This demonstrates the chaining of registration methods.

```cpp
Rml::StyleSheetSpecification::RegisterProperty("custom-property", "parameter-1", false)
	.AddParser("custom-parser", "parameter-1, parameter-2")

```

--------------------------------

### Initialize and Run RmlUi Application

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/main_loop.html

This snippet demonstrates the fundamental steps to initialize RmlUi, create a context, load a document, and run the main application loop. It includes input processing, application updates, RmlUi context updates, and rendering. Ensure custom render and system interfaces are set up before initialization.

```cpp
#include <RmlUi/Core.h>
#include <RmlUi/Debugger.h>

class MyRenderInterface : public Rml::RenderInterface
{
	/* ... */
}

class MySystemInterface : public Rml::SystemInterface
{
	/* ... */
}


int main(int argc, char** argv)
{
	// Initialize the window and graphics API being used, along with your game or application.

	/* ... */

	// Instantiate the interfaces to RmlUi.
	MyRenderInterface render_interface;
	MySystemInterface system_interface;

	// Begin by installing the custom interfaces.
	Rml::SetRenderInterface(&render_interface);
	Rml::SetSystemInterface(&system_interface);

	// Now we can initialize RmlUi.
	Rml::Initialise();

	// Create a context next.
	Rml::Context* context = Rml::CreateContext("main", Rml::Vector2i(window_width, window_height));
	if (!context)
	{
		Rml::Shutdown();
		return -1;
	}

	// If you want to use the debugger, initialize it now.
	Rml::Debugger::Initialise(context);

	// Fonts should be loaded before any documents are loaded.
	Rml::LoadFontFace("my_font_file.otf");

	// Now we are ready to load our document.
	Rml::ElementDocument* document = context->LoadDocument("my_document.rml");
	if (!document)
	{
		Rml::Shutdown();
		return -1;
	}

	document->Show();

	bool exit_application = false;
	while (!exit_application)
	{
		// We assume here that we have some way of updating and retrieving inputs internally.
		my_input->Update();

		if (my_input->KeyPressed(KEY_ESC))
			exit_application = true;

		// Submit input events before the call to Context::Update().
		if (my_input->MouseMoved())
			context->ProcessMouseMove(mouse_pos.x, mouse_pos.y, 0);

		// Toggle the debugger with a key binding.
		if (my_input->KeyPressed(KEY_F8))
			Rml::Debugger::SetVisible(!Rml::Debugger::IsVisible());

		// This is a good place to update your game or application.
		my_application->Update();

		// Update any elements to reflect changed data.
		if (Rml::Element* el = document->GetElementById("score"))
			el->SetInnerRML("Current score: " + my_application->GetScoreAsString());

		// Update the context to reflect any changes resulting from input events, animations, modified and
		// added elements, or changed data in data bindings.
		context->Update();

		// After the context update, the properties and layout of all elements are properly resolved.
		// At this point, we should no longer change any elements, or submit input or other events until
		// after the call to Context::Render().

		// Render your game or application.
		my_application->Render();

		// Set up rendering states for RmlUi, use `Backend::BeginFrame` for the built-in backends.
		my_renderer->BeginUserInterface();

		// Render the user interface on top of the application.
		context->Render();

		// Present the rendered frame, use `Backend::PresentFrame` for the built-in backends.
		my_renderer->PresentFrame();
	}

	// Shutting down RmlUi releases all its resources, including elements, documents, and contexts.
	Rml::Shutdown();

	// It is now safe to destroy the custom interfaces previously passed to RmlUi.

	return 0;
}

```

--------------------------------

### Get Elapsed Time

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/interfaces/system.html

Retrieve the number of seconds elapsed since the application started. The default implementation uses C++ chrono utilities.

```cpp
// Get the number of seconds elapsed since the start of the application.
virtual double GetElapsedTime();

```

--------------------------------

### Animating Spinning Conic Gradient

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/conic_gradient.html

Defines an animation for a repeating conic gradient to create a spinning effect. This example uses keyframes to change the gradient's starting angle over time.

```rcss
@keyframes spinner {
    from { decorator: repeating-conic-gradient(from   0deg, #fff3 0 15deg, #fff0 0 30deg); }
    to   { decorator: repeating-conic-gradient(from 360deg, #fff3 0 15deg, #fff0 0 30deg); }
}
.repeating_spinning {
    background-color: #0ac;
    animation: 5s spinner infinite;
}
```

--------------------------------

### Initialize Win32 IME Handler in RmlUi

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/ime.html

Demonstrates how to install the default Win32 platform's text input handler for IME support. This is typically done during application initialization before RmlUi is fully set up. Ensure RmlUi is shut down properly to release resources.

```cpp
#include <Backends/RmlUi_Platform_Win32.h>

static Rml::Context *context = nullptr;
static Rml::UniquePtr<TextInputMethodEditor_Win32> text_input_method_editor;

// Local event handler for window and input events.
static LRESULT CALLBACK WindowProcedureHandler(HWND window_handle, UINT message, WPARAM w_param, LPARAM l_param)
{
    return RmlWin32::WindowProcedure(context, *text_input_method_editor, window_handle, message, w_param, l_param);
}

int APIENTRY WinMain(HINSTANCE instance_handle, HINSTANCE previous_instance_handle, char* command_line, int command_show)
{
    // Initialize the window and graphics API being used, along with the renderer, system, and other interfaces, ...

    // ...

    // Instantiate the text input handler managing the IME.
    text_input_method_editor = Rml::MakeUnique<TextInputMethodEditor_Win32>();

    // Install the custom interface.
    Rml::SetTextInputHandler(text_input_method_editor.get());

    // Now we can initialize RmlUi.
    Rml::Initialise();

    // Create a context next.
    context = Rml::CreateContext("main", Rml::Vector2i(window_width, window_height));
    if (context == nullptr)
    {
        Rml::Shutdown();
        return -1;
    }

    // Load documents, handle the application loop, ...

    // ...

    // Shutting down RmlUi releases all its resources, including contexts that work with the text input handler.
    Rml::Shutdown();

    // It is now safe to destroy the custom interfaces previously passed to RmlUi, such as the text input handler.
    text_input_method_editor.reset();

    return 0;
}

```

--------------------------------

### Build LunaSVG Dependency

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/svg.html

Commands to clone, build, and install the LunaSVG dependency using CMake. Ensure to adjust CMake arguments for your specific environment.

```bash
git clone --recurse-submodules --branch v3.2.1 https://github.com/sammycage/lunasvg
cd lunasvg
cmake -B build -S . -DBUILD_SHARED_LIBS=OFF -DLUNASVG_BUILD_EXAMPLES=OFF
cmake --build build --target lunasvg --config Debug
cmake --build build --target lunasvg --config Release

```

--------------------------------

### Basic Text Rendering

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/text.html

Renders 'Hello 🌎 world!' with a dark gray color.

```rcss
.decorator1 {
    decorator: text("Hello 🌎 world!" #333);
}
```

--------------------------------

### Configure and Build RmlUi with CMake and vcpkg

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Configure the RmlUi build using CMake, specifying the 'samples' preset, the GLFW_GL3 backend, and the vcpkg toolchain file. Then, build the project.

```bash
git clone https://github.com/mikke89/RmlUi.git
cd RmlUi
cmake -B Build -S . --preset samples -DRMLUI_BACKEND=GLFW_GL3 -DCMAKE_TOOLCHAIN_FILE=<vcpkg-path>/scripts/buildsystems/vcpkg.cmake
cmake --build Build

```

--------------------------------

### Configure CMake with Options

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Configure RmlUi to build with samples enabled, using the GLFW OpenGL 3 backend, and in debug mode.

```bash
cmake -B Build -S . -DRMLUI_SAMPLES=ON -DRMLUI_BACKEND=GLFW_GL3 -DCMAKE_BUILD_TYPE=DEBUG
```

--------------------------------

### Element Animate Function Signature

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/animations_transforms.html

Defines the signature for starting an animation on an element's property. This function interpolates between a start and target value over a specified duration.

```cpp
// Start an animation of the given property on this element.
// @return True if a new animation was added.
bool Element::Animate(
	const String& property_name,
	const Property& target_value,
	float duration,
	Tween tween = Tween{},
	int num_iterations = 1,
	bool alternate_direction = true,
	float delay = 0.0f,
	const Property* start_value = nullptr
);
```

--------------------------------

### Constructing and Setting Element Box

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/hidden_elements.html

This example demonstrates how to use Rml::ElementUtilities::BuildBox() to create a box based on element properties and then apply it to a hidden element.

```cpp
Rml::Box box;
Rml::ElementUtilities::BuildBox(box, GetBox().GetContentArea(), hidden_element);
hidden_element->SetBox(box);
```

--------------------------------

### Get Element Offset

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/elements.html

Retrieve the element's offset relative to its offset parent or the document root. Use Box::CONTENT to get the offset of the content area.

```cpp
// Returns the position of the top-left corner of one of the areas of this element's primary box, relative to its
// offset parent's top-left border corner.
// @param[in] area The desired area position.
// @return The relative offset.
Rml::Vector2f GetRelativeOffset(Rml::Box::Area area = Box::CONTENT) const;

// Returns the position of the top-left corner of one of the areas of this element's primary box, relative to
// the element root.
// @param[in] area The desired area position.
// @return The absolute offset.
Rml::Vector2f GetAbsoluteOffset(Rml::Box::Area area = Box::CONTENT) const;
```

--------------------------------

### RCSS Click Sound Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/rcss.html

Demonstrates setting the 'click-sound' property in RCSS. It shows how keywords like 'beep' are used directly, while custom sound files are specified as strings.

```rcss
button
{
	click-sound: beep;
}

button.siren
{
	click-sound: siren.wav;
}
```

--------------------------------

### Tiled Horizontal Decorator Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/tiled_horizontal.html

Applies the tiled-horizontal decorator to different elements using sprite definitions from a spritesheet. Includes examples for radio buttons, checkboxes, and title bars.

```rcss
@spritesheet demo-sheet
{
	src: /assets/invader.tga;

	title-bar-l: 147px 0px 82px 85px;
	title-bar-c: 229px 0px  1px 85px;
	title-bar-r: 231px 0px 15px 85px;

	demo-radio-l: 407px 0px 14px 30px;
	demo-radio-m: 421px 0px  2px 30px;
	demo-radio-r: 423px 0px 14px 30px;

	demo-checkbox-l: 407px 60px 14px 30px;
	demo-checkbox-m: 421px 60px  2px 30px;
	demo-checkbox-r: 423px 60px 14px 30px;
}

.radio {
    decorator: tiled-horizontal( demo-radio-l, demo-radio-m, demo-radio-r );
}
.checkbox {
    decorator: tiled-horizontal( demo-checkbox-l, demo-checkbox-m, demo-checkbox-r );
}
.title-bar {
    decorator: tiled-horizontal( title-bar-l, title-bar-c, title-bar-r );
}

```

--------------------------------

### Build Emscripten Targets

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Build the WebAssembly targets for RmlUi samples using emmake.

```bash
emmake make -j8
```

--------------------------------

### Basic Data Binding Example

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/examples.html

Demonstrates basic data binding with `data-model`, `{{variable}}` for text replacement, `data-if` for conditional display, and `data-value` for two-way binding.

```html
<h1>Simple data binding example</h1>
<div data-model="my_model">
	<h2>{{title}}</h2>
	<p data-if="show_text">The quick brown fox jumps over the lazy {{animal}}.</p>
	<input type="text" data-value="animal"/>
</div>

```

--------------------------------

### Setting RmlUi root path in CMake

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html

Specify the RmlUi installation or build directory when configuring CMake to help it locate the library. This is useful for in-source builds or when RmlUi is not installed in a standard location.

```bash
cmake -B Build -S . -DRmlUi_ROOT="<path-to-rmlui>"
```

--------------------------------

### Compound Selector Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/selectors.html

Matches a div element with a specific ID that is currently being hovered.

```rcss
div#level_list:hover
```

--------------------------------

### Custom System Interface for IME Activation

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/ime.html

Override Rml::SystemInterface::ActivateKeyboard to position the IME candidate window relative to the caret. This example uses Windows IMM32 API.

```cpp
#include <RmlUi/Core/SystemInterface.h>

class SampleSystemInterface : public Rml::SystemInterface {
private:
    void ActivateKeyboard(Rml::Vector2f caret_position, float line_height) override;

private:
    HWND window_handle;
};

void SampleSystemInterface::ActivateKeyboard(Rml::Vector2f caret_position, float line_height)
{
    HIMC himc = ImmGetContext(window_handle);
    if (himc == NULL)
        return;

    constexpr LONG BottomMargin = 2;

    // Adjust the position of the input method editor (IME) to the caret.
    const LONG x = static_cast<LONG>(caret_position.x);
    const LONG y = static_cast<LONG>(caret_position.y);
    const LONG w = 1;
    const LONG h = static_cast<LONG>(line_height) + BottomMargin;

    COMPOSITIONFORM comp = {};
    comp.dwStyle = CFS_FORCE_POSITION;
    comp.ptCurrentPos = {x, y};
    ImmSetCompositionWindow(himc, &comp);

    CANDIDATEFORM cand = {};
    cand.dwStyle = CFS_EXCLUDE;
    cand.ptCurrentPos = {x, y};
    cand.rcArea = {x, y, x + w, y + h};
    ImmSetCandidateWindow(himc, &cand);

    ImmReleaseContext(window_handle, himc);
}

```

--------------------------------

### Image Decorator Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators.html

Declares an image decorator using a sprite name for the icon.

```rcss
decorator: image( icon-invader );

```

--------------------------------

### Accessing Attributes

Source: https://mikke89.github.io/RmlUiDoc/pages/lua_manual/elements.html

Accesses element attributes like a map. The example prints the 'value' attribute.

```APIDOC
## Accessing Attributes

### Description
Accesses element attributes like a map. The example prints the 'value' attribute.

### Code Example
```lua
print(element.attributes.value)
```
```

--------------------------------

### Setting Density-Independent Pixel Ratio

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/syntax.html

Provides an example of how to set the global density-independent pixel (dp) ratio for a context in C++. This allows for scalable user interfaces.

```c++
float dp_ratio = 1.5f;
context->SetDensityIndependentPixelRatio(dp_ratio);
```

--------------------------------

### Build RmlUi and Samples on macOS/Linux

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Use this command to configure, build RmlUi, and enable samples on macOS and Linux. The `-j` flag enables parallel builds.

```bash
cmake -B Build -S . -DRMLUI_SAMPLES=ON
cmake --build Build -j

```

--------------------------------

### Document Identification

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/documents.html

Functions to get and set the document's title, and to retrieve its source URL.

```APIDOC
## SetTitle

### Description
Sets the document's title.

### Signature
void SetTitle(Rml::String& title)

### Parameters
- **title** (Rml::String&) - The new title of the document.
```

```APIDOC
## GetTitle

### Description
Returns the title of this document.

### Signature
const Rml::String& GetTitle() const

### Returns
- The document's title.
```

```APIDOC
## GetSourceURL

### Description
Returns the source address of this document, usually a file name.

### Signature
const Rml::String& GetSourceURL() const

### Returns
- The source of this document.
```

--------------------------------

### RML with Localisation Tokens

Source: https://mikke89.github.io/RmlUiDoc/pages/localisation.html

Example of RML content modified to use localisation tokens for string substitution.

```rml
<rml>
	<head>
		<title>[QUIT_TITLE]</title>
	</head>
	<body>
		<p>[QUIT_CONFIRM]</p>
		<button>[CONFIRM]</button>
		<button>[DENY]</button>
	</body>
</rml>


```

--------------------------------

### Expression Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/expressions.html

Demonstrates various data expression use cases including comparisons, string concatenation, formatting, conditional logic, and event data access.

```rml
rating < 80
```

```rml
radius + 'm'
```

```rml
(radius | format(2)) + 'm'
```

```rml
radius < 10.5 ? 'small' : 'large'
```

```rml
'hot' + 'dog' | to_upper
```

```rml
'x: ' + ev.mouse_x + '<br/>y: ' + ev.mouse_y
```

```rml
true || false ? (true && 3==1+2 ? 'Absolutely!' : 'well..') : 'no'
```

--------------------------------

### RML Select Box Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/element_packages/form.html

Declares a simple drop-down select box with options and a pre-selected value.

```rml
<select name="graphics">
	<option value="bad">Bad</option>
	<option value="ok">OK</option>
	<option value="good" selected>good</option>
</select>

```

--------------------------------

### Get Number of Options in Select Control

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/element_packages/form.html

Retrieves the total number of options available in a select control.

```cpp
// Returns the number of options in the select control.
// @return The number of options.
int GetNumOptions() const;

```

--------------------------------

### Initialize RmlUi Debugger

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/debugger.html

Initializes the debug plugin and loads it into the specified RmlUi context. Returns true on successful initialization.

```cpp
// Initialises the debug plugin. The debugger will be loaded into the given context.
// @param[in] context The RmlUi context to load the debugger into.
// @return True if the debugger was successfully initialised
bool Initialise(Rml::Context* context);
```

--------------------------------

### RCSS Sibling Combinator Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/selectors.html

Demonstrates the use of next-sibling (+) and subsequent-sibling (~) combinators to style adjacent or following elements.

```rcss
p + img { margin-top: 0; }
```

```rcss
p.content ~ p { font-size: 0.9em; }
```

--------------------------------

### Implement Text Input Method Editor

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/interfaces/text_input_handler.html

This C++ code demonstrates an implementation of a text input method editor using the Rml::TextInputContext. It handles setting and confirming text compositions.

```cpp
class TextInputMethodEditor {
public:
    void SetComposition(Rml::StringView composition);
    void ConfirmComposition(Rml::StringView composition);

private:
    // An actively used text input method context.
    Rml::TextInputContext* input_context;

    // Composition range (character position) relative to the text input value.
    int composition_range_start;
    int composition_range_end;
};

void TextInputMethodEditor::SetComposition(Rml::StringView composition)
{
    // Retrieve the composition range if it is missing.
    if (composition_range_start == 0 && composition_range_end == 0)
        input_context->GetSelectionRange(composition_range_start, composition_range_end);

    // First, modify the text value of the text area to insert the current composition string.
    input_context->SetText(composition, composition_range_start, composition_range_end);

    // Calculate the new end of the composition range, as the string has changed.
    size_t length = Rml::StringUtilities::LengthUTF8(composition);
    composition_range_end = composition_range_start + (int)length;

    // Once we are finished with text modifications, apply the composition range for visual feedback.
    input_context->SetCompositionRange(composition_range_start, composition_range_end);
}

void TextInputMethodEditor::ConfirmComposition(Rml::StringView composition)
{
    // First, set the composition range, which will be used for inserting the composition string.
    input_context->SetCompositionRange(composition_range_start, composition_range_end);
    // Once the range is set, insert the composition string into the text field.
    input_context->CommitComposition(Rml::String(composition));

    // Move the cursor to the end of the string.
    input_context->SetCursorPosition(composition_range_end);

    // End the composition, clean up the state, ...

    // ...

}

```

--------------------------------

### Button with Radial Gradient

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/radial_gradient.html

Example of applying a radial gradient to a button element, setting its background and other visual properties.

```rcss
button {
    decorator: radial-gradient(circle farthest-side at center, #ff6b6b, #fec84d, #4ecdc4);
    border-radius: 50px;
    border: 4px #fff;
    box-shadow: #000a 0 4px 12px, #000a 0 1px 3px;
}
```

--------------------------------

### Set and Get Selection Index for Select Control

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/element_packages/form.html

Manages the currently selected item in a select control by its index.

```cpp
// Sets the index of the selection. If the new index lies outside of the bounds, it will be clamped.
// @param[in] selection The new selection index.
void SetSelection(int selection);

// Returns the index of the currently selected item.
// @return The index of the currently selected item.
int GetSelection() const;

```

--------------------------------

### Run RmlUi Invaders Sample on macOS/Linux

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/building_with_cmake.html

Execute the invaders sample after building RmlUi on macOS or Linux. Ensure you are in the RmlUi directory.

```bash
Build/rmlui_sample_invaders

```

--------------------------------

### List All Contexts

Source: https://mikke89.github.io/RmlUiDoc/pages/lua_manual/contexts.html

Iterate over all available RmlUi contexts and print their names.

```lua
for i,context in ipairs(rmlui.contexts) do
	print('Context ' .. i .. ': ' .. context.name)
end

```

--------------------------------

### Get Specific Option Element from Select Control

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/element_packages/form.html

Retrieves a specific option element from a select control by its index.

```cpp
// Returns one of the select control's option elements.
// @param[in] The index of the desired option.
// @return The option element or nullptr if the index was out of bounds.
Rml::Element* GetOption(int index);

```

--------------------------------

### Overflow Shorthand Example

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/rcss.html

Demonstrates the 'Replicate' ShorthandType with the 'overflow' shorthand. The single value 'auto' is applied to both 'overflow-x' and 'overflow-y'.

```rcss
overflow: auto;
```

--------------------------------

### Theming with RCSS Custom Properties and Media Queries

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/custom_properties.html

Illustrates implementing themes by defining custom properties for background and foreground colors, overriding them within a @media (theme: dark) block, and referencing them throughout the stylesheet.

```rcss
body {
	--bg: #f0ebd8;
	--fg: #1d1d1d;
}
@media (theme: dark) {
	body {
		--bg: #18181b;
		--fg: #f4f4f5;
	}
}
body {
	background-color: var(--bg);
	color: var(--fg);
}
```

--------------------------------

### Number Value Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/syntax.html

Demonstrates the usage of a simple number as a value for a property in RCSS. Numbers can be integers or real numbers.

```rcss
z-index: 16;
```

--------------------------------

### Registering a Custom Context Instancer

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/contexts.html

Demonstrates how to register a custom context instancer with the RmlUi factory. Ensure the instancer object's lifetime exceeds the RmlUi shutdown call.

```cpp
// The custom_instancer must be kept alive until after the call to Rml::Shutdown()
auto custom_instancer = std::make_unique<CustomContextInstancer>();
Rml::Factory::RegisterContextInstancer(custom_instancer.get());

```

--------------------------------

### RCSS Descendant Combinator Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/selectors.html

Illustrates a complex descendant selector requiring multiple conditions to be met in the RML hierarchy.

```rcss
div#level_list input.select option:nth-child(even)
```

--------------------------------

### Basic Glow Effect Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/font_effects/glow.html

Applies a simple glow effect to an h1 element with a specified outline width and color.

```css
h1
{
	font-effect: glow( 3px #ee9 );
}

```

--------------------------------

### Load and Show RmlUi Document

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html

Load an Rml document into an existing context and make it visible. Ensure event listeners are handled correctly to avoid destruction issues.

```cpp
Rml::ElementDocument* document = context->LoadDocument("../../assets/demo.rml");
if (document)
	document->Show();
```

--------------------------------

### Decorator Override Example

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators.html

Demonstrates how decorators can be overridden. An h1 element initially has an image decorator, but it's removed on hover.

```rcss
h1 {
	decorator: image( cat.png );
}

h1:hover {
	decorator: none;
}

```

--------------------------------

### Various Radial Gradient Examples

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/radial_gradient.html

Demonstrates different configurations of radial gradients, including custom positions, sizes, color stop percentages, and paint areas.

```rcss
.gradient1 {
    decorator: radial-gradient(circle closest-side at 100px 30px, red, yellow, green);
}
```

```rcss
.gradient2 {
    decorator: radial-gradient(30% 60%, red 50%, yellow 50%, green);
}
```

```rcss
.gradient3 {
    background-color: yellow;
    decorator: radial-gradient(40px, #4ecdc4, white 40% 60%, #ff6b6b) content-box;
}
```

```rcss
.gradient4 {
    decorator: repeating-radial-gradient(50px 80px, #f00, #ff0, #f00);
}
```

```rcss
.gradient5 {
    decorator: repeating-radial-gradient(circle closest-side, yellow, red 2px, yellow);
}
```

--------------------------------

### Move document with <handle>

Source: https://mikke89.github.io/RmlUiDoc/pages/rml/controls.html

A handle can be configured to move the entire document using `move_target="#document"`.

```RML
<handle move_target="#document">
	<div id="title">My document</div>
</handle>
```

--------------------------------

### Applying a Shader Effect

Source: https://mikke89.github.io/RmlUiDoc/pages/rcss/decorators/shader.html

Example of an RCSS rule applying a shader decorator with the 'creation' value and setting border properties.

```rcss
.creation {
    decorator: shader("creation");
    border-radius: 20px;
    border: 3px #ddd;
}
```

--------------------------------

### If Data View Example

Source: https://mikke89.github.io/RmlUiDoc/pages/data_bindings/views_and_controllers.html

Conditionally renders an element by toggling its 'display' property. Use when the element should not occupy space when hidden.

```Rml
<div data-if="rating > 50">
	Thanks for the <span data-if="rating >= 80">awesome</span> rating!
</div>
```

--------------------------------

### FindNextTabElement

Source: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/documents.html

Finds the next tabbable element in the document tree, starting at the given element, possibly wrapping around the document.

```APIDOC
## FindNextTabElement

### Description
Finds the next tabbable element in the document tree, starting at the given element, possibly wrapping around the document.

### Parameters
#### Path Parameters
- **current_element** (Element*) - The element to start from.
- **forward** (bool) - True to search forward, false to search backward.

### Return Value
- **Element*** - The next tabbable element, or nullptr if none could be found.
```
Tokens:
Raw