Update readme and changelog

Samples/readme.md

@@ -35,7 +35,9 @@ Lua version of the invaders sample. Only installed with the Lua plugin.
 
 #### `shell`
 
-The shell is mainly a wrapper around the [backends](../Backends/), used by all the samples to initialize the interfaces and open windows for rendering on the selected backend.
+The shell provides some common functionality that are specific to the included samples and tests, such as loading fonts and handling global keyboard shortcuts.
+
+Note that, the code for rendering, opening and closing windows, and providing inputs, is instead located in the [backends](../Backends/), however some extensions to these backends are found in the shell.
 
 #### `tutorial`
 

changelog.md

@@ -1,3 +1,4 @@
+* [RmlUi 5.0](#rmlui-50)
 * [RmlUi 4.4](#rmlui-44)
 * [RmlUi 4.3](#rmlui-43)
 * [RmlUi 4.2](#rmlui-42)
@@ -9,32 +10,46 @@
 * [RmlUi 3.0](#rmlui-30)
 * [RmlUi 2.0](#rmlui-20)
 
-## RmlUi 5.0 (WIP)
+## RmlUi 5.0
 
 ### Backends
 
-RmlUi 5.0 introduces the backends concept. This is a complete refactoring of the old sample shell, replacing most of it with a multitude of backends. A backend is a combination of a renderer and a platform. The shell is now only used for common functions specific to the included samples.
+RmlUi 5.0 introduces the backends concept. This is a complete refactoring of the old sample shell, replacing most of it with a multitude of backends. A backend is a combination of a renderer and a platform, and a light interface tying them together. The shell is now only used for common functions specific to the included samples.
 
 This change is beneficial in several aspects:
 
-- Makes it easier to integrate RmlUi as users can directly use the renderer and platform suited for their setup.
+- Makes it easier to integrate RmlUi, as users can directly use the renderer and platform suited for their setup.
 - Makes it a lot easier to add new backends and maintain existing ones.
 - Allows all the samples to run on any backend by choosing the desired backend during CMake configuration.
 
 All samples and tests have been updated to work with the [backends interface](Backends/RmlUi_Backend.h), which is a very light abstraction over all the different backends.
 
-The following new renderers and platforms are added:
+The following renderers and platforms are included:
 
 - A new OpenGL 3 renderer. #261
   - Including Emscripten support so RmlUi even runs in web browsers now.
-- A new Vulkan renderer. #236 #328 #360 (thanks @wh1t3lord)
+- A new Vulkan renderer. #236 #328 #360 #385 (thanks @wh1t3lord)
 - A new GLFW platform.
-- The OpenGL 2 and SDL native renderers are ported over from the old samples.
-- The Win32, X11, SFML, and SDL platforms are ported over from the old samples.
+- The OpenGL 2 and SDL native renderers ported from the old samples.
+- The Win32, X11, SFML, and SDL platforms ported from the old samples.
 
 The old macOS shell has been removed as it used a legacy API that is no longer working on modern Apple devices. Now the samples build again on macOS using one of the windowing libraries such as GLFW or SDL.
 
-See the [Backends section in the readme](readme.md#rmlui-backends) for all the combinations of renderers and platforms, and more details.
+See the [Backends section in the readme](readme.md#rmlui-backends) for all the combinations of renderers and platforms, and more details. The backend used for running the samples can be selected by setting the CMake option `SAMPLES_BACKEND` to any of the [supported backends](readme.md#rmlui-backends).
+
+### RCSS selectors
+
+- Implemented the next-sibling `+` and subsequent-sibling `~` [combinators](https://mikke89.github.io/RmlUiDoc/pages/rcss/selectors.html).
+- Implemented attribute selectors `[foo]`, `[foo=bar]`, `[foo~=bar]`, `[foo|=bar]`, `[foo^=bar]`, `[foo$=bar]`, `[foo*=bar]`. #240 (thanks @aquawicket)
+- Implemented the negation pseudo class `:not()`, including support for selector lists `E:not(s1, s2, ...)`.
+- Refactored structural pseudo classes for improved performance.
+- Selectors will no longer match any text elements, like in CSS.
+- Selectors now correctly consider all paths toward the root, not just the first greedy path.
+- Structural selectors are no longer affected by the element's display property, like in CSS.
+
+### RCSS properties
+
+- `max-width` and `max-height` properties now support the `none` keyword.
 
 ### Text editing
 
@@ -48,59 +63,77 @@ The `<textarea>` and `<input type="text">` elements have been improved in severa
 - Fixed operation of page up/down numpad keys being swapped.
 - The input method editor (IME) is now positioned at the caret during text editing on the Windows backend. #303 #305 (thanks @xland)
 - Fix slow input handling especially with CJK input on the Win32 backend. #311
-- Improve performance on construction and during text editing.
+- Improve performance on document load and during text editing.
 
-### RCSS selectors
-
-- Implemented the next-sibling `+` and subsequent-sibling `~` [combinators](https://mikke89.github.io/RmlUiDoc/pages/rcss/selectors.html).
-- Implemented attribute selectors `[foo]`, `[foo=bar]`, `[foo~=bar]`, `[foo|=bar]`, `[foo^=bar]`, `[foo$=bar]`, `[foo*=bar]`. #240 (thanks @aquawicket)
-- Implemented the negation pseudo class `:not()`, including support for selector lists `E:not(s1, s2, ...)`.
-- Refactored structural pseudo classes for improved performance.
-- Selectors will no longer match any text elements, like in CSS.
-- Selectors more correctly consider all paths toward the root, not just the first greedy path.
-- Structural selectors are no longer affected by the element's display property, like in CSS.
-
-### RCSS properties
+### Elements
 
-- `max-width` and `max-height` properties now support the `none` keyword.
+- Extend the functionality of `Element::ScrollIntoView`. #353 (thanks @eugeneko)
+- `<img>` element: Fix wrong dp-scaling being applied when an image is cloned through a parent element. #310
+- `<handle>` element: Fix move targets changing size when placed using the `top`/`right`/`bottom`/`left` properties.
 
 ### Data binding
 
 - Transform functions can now be called using C-like calling conventions, in addition to the previous pipe-syntax. Thus, the data expression `3.625 | format(2)` can now be identically expressed as `format(3.625, 2)`.
+- Handle null pointers when trying to access data variables. #377 (thanks @Dakror)
+- Enable registering a custom data variable definition. #367 (thanks @Dakror)
+
+### Context input
+
+- The hover state of any elements under the mouse will now automatically be updated during `Context::Update()`. #220
+- Added `Context::ProcessMouseLeave()` which ensures that the hovered state is removed from all elements and stops the context update from automatically hovering elements.
+- When `Context::ProcessMouseMove()` is called next the context update will start updating hover states again.
+- Added support for mouse leave events on all backends.
+
+### Layout improvements
+
+- Scroll and slider elements now use containing block's height instead of width to calculate height-relative values. #314 #321 (thanks @nimble0)
+- Generate warnings when directly nesting flexboxes and other unsupported elements in a top-level formatting context. #320
+- In some situations, changing the `top`/`right`/`bottom`/`left` properties may affect the element's size. These situations are now correctly handled so that the layout is updated when needed.
 
 ### Lua plugin
 
 - Add `QuerySelector` and `QuerySelectorAll` to the Lua Element API. #329 (thanks @Dakror)
+- Add input-related methods and `dp_ratio` to the Lua Context API. #381 #386 (thanks @shubin)
 - Lua objects representing C++ pointers now compare equal if they point to the same object. #330 (thanks @Dakror)
 - Add length to proxy for element children. #315 (thanks @nimble0)
-- Fix crash in Lua plugin during garbage collection. #340 (thanks @slipher)
+- Fix a crash in the Lua plugin during garbage collection. #340 (thanks @slipher)
 
-### Layout improvements
+### Debugger plugin
 
-- Scroll and slider elements now use containing block's height instead of width to calculate height-relative values. #314 #321 (thanks @nimble0)
-- Generate warnings when directly nesting flexboxes and other unsupported elements in a top-level formatting context. #320
-- In some situations, changing the `top`/`right`/`bottom`/`left` properties may affect the element's size. These situations are now correctly handled and the layout is updated when needed.
+- Show a more descriptive name for children in the element info window.
+- Fixed a crash when the debugger plugin was shutdown manually. #322 #323 (thanks @LoneBoco)
 
-### Context input
+### SVG plugin
 
-- The hover state of any elements under the mouse will now automatically be updated during `Context::Update()`. #220
-- Added `Context::ProcessMouseLeave()` which ensures that the hovered state is removed from all elements and stops the context update from automatically hovering elements.
-- When `Context::ProcessMouseMove()` is called next the context update will start updating hover states again.
-- Added support for mouse leave events on all backends.
+- Update texture when the `src` attribute changes. #361
+
+### General improvements
+
+- Small performance improvement when generating font effects.
+- Allow empty values in decorators and font-effects.
+- RCSS located within document `<style>` tags can now take comments containing xml tags. #341
+- Improve in-source function documentation. #334 (thanks @hobyst)
+- Invader sample: Rename event listener and instancer for clarity.
 
 ### General fixes
 
 - Font textures are no longer being regenerated when encountering new ascii characters, fixes a recent regression.
-- `<img>` element: Fix wrong dp-scaling being applied when an image is cloned through a parent element. #310
 - Logging a message without an installed system interface will now be written to cout instead of crashing the application.
-- Fixed a crash when the debugger plugin was shutdown manually. #322 #323 (thanks @LoneBoco)
+- Fix several static analyzer warnings and one possible case of undefined behavior.
+- SDL renderer: Fix images with no alpha channel not rendering. #239
+
+### Build fixes
+
 - Fix compilation on Emscripten CI. #335 (thanks @hobyst)
+- Fix compilation with EASTL. #350 (thanks @eugeneko)
 
 ### Breaking changes
 
 - Changed the signature of the keyboard activation in the system interface, it now passes the caret position and line height: `SystemInterface::ActivateKeyboard(Rml::Vector2f caret_position, float line_height)`.
+- Mouse and hover behavior may change in some situations as a result of the hover state automatically being updated on `Context::Update()`, even if the mouse is not moved. See above changes to context input.
 - Removed the boolean result returned from `Rml::Debugger::Shutdown()`.
-- RCSS selectors will no longer match text elements, structural pseudo selectors are no longer affected by the element's display property.
+- RCSS selectors will no longer match text elements.
+- RCSS structural pseudo selectors are no longer affected by the element's display property.
 - Data binding: The signature of transform functions has been changed from `Variant& first_argument_and_result, const VariantList& other_arguments -> bool success` to `const VariantList& arguments -> Variant result`.
 
 

readme.md

@@ -1,6 +1,6 @@
 # RmlUi - The HTML/CSS User Interface Library Evolved
 
-![RmlUi](https://github.com/mikke89/RmlUiDoc/raw/cc01edd834b003df6c649967bfd552bb0acc3d1e/assets/rmlui.png)
+![RmlUi logo](https://github.com/mikke89/RmlUiDoc/raw/c7253748d1bcf6dd33d97ab4fe8b6731a7ee3dac/assets/rmlui.png)
 
 RmlUi - now with added boosters taking control of the rocket, targeting *your* games and applications.
 
@@ -12,7 +12,7 @@ RmlUi - now with added boosters taking control of the rocket, targeting *your* g
 
 RmlUi is the C++ user interface package based on the HTML and CSS standards, designed as a complete solution for any project's interface needs. It is a fork of the [libRocket](https://github.com/libRocket/libRocket) project, introducing new features, bug fixes, and performance improvements. 
 
-RmlUi aims at being a light-weight and performant library with its own layouting engine and few dependencies. In essence, RmlUi takes your HTML/CSS-like source files and turns them into vertices, indices and draw commands, and then you bring your own renderer to draw them. And of course there is full access to the element hierarchy/DOM, event handling, and all the interactivity and customizability you would expect. All of this directly from C++, or optionally from scripting languages using plugins. The core library compiles down to fractions of the size it takes to integrate a fully fledged web browser as other libraries do in this space. 
+RmlUi aims at being a light-weight and performant library with its own layouting engine and few dependencies. In essence, RmlUi takes your HTML/CSS-like source files and turns them into vertices, indices and draw commands, and then you bring your own renderer to draw them. And of course there is full access to the element hierarchy/DOM, event handling, and all the interactivity and customizability you would expect. All of this directly from C++, or optionally from scripting languages using plugins. The core library compiles down to fractions of the size it takes to integrate a fully fledged web browser. 
 
 RmlUi is based around the XHTML1 and CSS2 standards while borrowing features from HTML5 and CSS3, and extends them with features suited towards real-time applications. Take a look at the [conformance](#conformance) and [enhancements](#enhancements) sections below for details.
 
@@ -101,7 +101,7 @@ cd RmlUi
 cmake -B Build -S . -DBUILD_SAMPLES=ON -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake"
 cmake --build Build
 ```
-Make sure to replace the path to vcpkg.
+Make sure to replace the path to vcpkg. When this completes, feel free to test the freshly built samples, such as the `invader` sample, and enjoy! The executables should be located somewhere in the `Build` directory.
 
 #### Conan
 
@@ -110,10 +110,10 @@ RmlUi is readily available from [ConanCenter](https://conan.io/center/rmlui).
 
 ## Integrating RmlUi
 
-Here are the general steps to integrate the library into a C++ application, have a look at the [documentation](https://mikke89.github.io/RmlUiDoc/) for details.
+Here are the general steps to integrate the library into a C++ application, have a look at the [integration documentation](https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html) for details.
 
-1. Build RmlUi as above or fetch the binaries, and [link it up](https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html) to your application.
-2. Implement the abstract [system interface](Include/RmlUi/Core/SystemInterface.h) and [render interface](Include/RmlUi/Core/RenderInterface.h).
+1. Build RmlUi as above or fetch the binaries, and [link it up](https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html#setting-up-the-build-environment) to your application.
+2. Implement the abstract [system interface](Include/RmlUi/Core/SystemInterface.h) and [render interface](Include/RmlUi/Core/RenderInterface.h), or fetch one of the backends listed below.
 3. Initialize RmlUi with the interfaces, create a context, provide font files, and load a document.
 4. Call into the context's update and render methods in a loop, and submit input events.
 5. Compile and run!
@@ -123,29 +123,27 @@ Several [samples](Samples/) demonstrate everything from basic integration to mor
 
 ## RmlUi Backends
 
-***Note: The backends concept is work-in-progress for RmlUi 5.0, everything here is subject to change and documentation is being worked on.***
-
-RmlUi comes with [many backends](Backends/) adding support for several renderers and platforms. The following terms are used here:
+To ease the integration of RmlUi, the library includes [many backends](Backends/) adding support for common renderers and platforms. The following terms are used here:
 
 - ***Renderer***: Implements the [render interface](https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/interfaces/render) for a given rendering API, and provides initialization code when necessary.
 - ***Platform***: Implements the [system interface](https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/interfaces/system.html) for a given platform (operating system or window library), and adds procedures for providing input to RmlUi contexts.
-- ***Backend***: Combines a renderer and a platform for a complete solution sample, implementing the basic [Backend interface](Backends/RmlUi_Backend.h).
+- ***Backend***: Combines a renderer and a platform for a complete windowing framework sample, implementing the basic [Backend interface](Backends/RmlUi_Backend.h).
 
-The provided renderers and platforms are intended to be usable as-is by client projects without modifications. We encourage users to only make changes here when they are useful to all users, and then contribute back to the project. Feedback is welcome, and finding the proper abstraction level is a work-in-progress. The provided system and render interfaces are designed such that they can be derived from and further customized by the backend or end user.
+The provided renderers and platforms are intended to be usable as-is by client projects without modifications, thereby circumventing the need to write custom interfaces. We encourage users to only make changes here when they are useful to all users, and then contribute back to the project. However, if they do not meet your needs it is also possible to copy them into your project for modifications. Feedback is welcome to find the proper abstraction level. The provided system and render interfaces are designed such that they can be derived from and further customized by the backend or end user.
 
-The provided backends on the other hand are not intended to be used directly by client projects, but rather copied and modified as needed. They are intentionally light-weight and implement just enough functionality to make the [included samples](Samples/) run, while being simple to understand and build upon by users.
+The provided backends on the other hand are not intended to be used directly by client projects, but rather copied and modified as needed. They are intentionally light-weight and implement just enough functionality to make the [included samples](Samples/) run, while being simple to understand and build upon by users. See the manual for [backend integration details](https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html#backends).
 
 ### Renderers
 
 | Renderer features | Basic rendering | Stencil | Transforms | Built-in image support                                                          |
 |-------------------|:---------------:|---------|:----------:|---------------------------------------------------------------------------------|
-| OpenGL 2          |        ✔️       |    ✔️    |      ✔️    | Uncompressed TGA                                                                |
-| OpenGL 3          |        ✔️       |    ✔️    |      ✔️    | Uncompressed TGA                                                                |
-| Vulkan            |        ✔️       |    ✔️    |      ✔️    | Uncompressed TGA                                                                |
+| OpenGL 2 (GL2)    |        ✔️       |    ✔️    |      ✔️    | Uncompressed TGA                                                                |
+| OpenGL 3 (GL3)    |        ✔️       |    ✔️    |      ✔️    | Uncompressed TGA                                                                |
+| Vulkan (VK)       |        ✔️       |    ✔️    |      ✔️    | Uncompressed TGA                                                                |
 | SDLrenderer       |        ✔️       |    ❌    |      ❌    | Based on [SDL_image](https://www.libsdl.org/projects/SDL_image/docs/index.html) |
 
 **Basic rendering**: Render geometry with colors, textures, and rectangular clipping (scissoring). Sufficient for basic 2d-layouts.\
-**Stencil**: Enables proper clipping when the `border-radius` property is set, and when transforms are enabled.\
+**Stencil**: Enables proper clipping when transforms are enabled.\
 **Transforms**: Enables the `transform` and `perspective` properties to take effect.\
 **Built-in image support**: This only shows the supported formats built-in to the renderer, users are encouraged to derive from and extend the render interface to add support for their desired image formats.
 
@@ -171,9 +169,13 @@ The provided backends on the other hand are not intended to be used directly by
 | X11                 |     ✔️     |           |          |             |
 | SFML                |     ✔️     |           |          |             |
 | GLFW                |     ✔️     |     ✔️    |     ✔️    |             |
-| SDL                 |     ✔️     |     ✔️¹   |     ✔️    |      ✔️     |
+| SDL¹                |     ✔️     |     ✔️²   |     ✔️    |      ✔️     |
+
+¹ SDL backends extend their respective renderers to provide image support based on SDL_image.\
+² Supports Emscripten compilation target.
+
+When building the samples, the backend can be selected by setting the CMake option `SAMPLES_BACKEND` to `<Platform>_<RendererShorthand>` for any of the above supported combinations of platforms and renderers, such as `SDL_GL3`.
 
-¹ Supports Emscripten compilation target.
 
 ## Example document