Prechádzať zdrojové kódy

Add text decorator, solves #679

Michael Ragazzon 1 rok pred
rodič
commit
66d0b7c4d5

+ 1 - 1
Include/RmlUi/Core/FontEngineInterface.h

@@ -118,7 +118,7 @@ public:
 
 	/// Called by RmlUi to determine if the text geometry is required to be re-generated. Whenever the returned version
 	/// is changed, all geometry belonging to the given face handle will be re-generated.
-	/// @param[in] face_handle The font handle.
+	/// @param[in] handle The font handle.
 	/// @return The version required for using any geometry generated with the face handle.
 	virtual int GetVersion(FontFaceHandle handle);
 

+ 4 - 0
Source/Core/CMakeLists.txt

@@ -40,6 +40,8 @@ add_library(rmlui_core
 	DecoratorNinePatch.h
 	DecoratorShader.cpp
 	DecoratorShader.h
+	DecoratorText.cpp
+	DecoratorText.h
 	DecoratorTiled.cpp
 	DecoratorTiled.h
 	DecoratorTiledBox.cpp
@@ -50,6 +52,8 @@ add_library(rmlui_core
 	DecoratorTiledImage.h
 	DecoratorTiledVertical.cpp
 	DecoratorTiledVertical.h
+	DecoratorUtilities.cpp
+	DecoratorUtilities.h
 	DocumentHeader.cpp
 	DocumentHeader.h
 	EffectSpecification.cpp

+ 2 - 28
Source/Core/DecoratorGradient.cpp

@@ -149,32 +149,6 @@ static ColorStopList ResolveColorStops(Element* element, const float gradient_li
 	return stops;
 }
 
-// Compute a 2d-position property value into a percentage-length vector.
-static Vector2Numeric ComputePosition(const Property* p_position[2])
-{
-	Vector2Numeric position;
-	for (int dimension = 0; dimension < 2; dimension++)
-	{
-		NumericValue& value = position[dimension];
-		const Property& property = *p_position[dimension];
-		if (property.unit == Unit::KEYWORD)
-		{
-			enum { TOP_LEFT, CENTER, BOTTOM_RIGHT };
-			switch (property.Get<int>())
-			{
-			case TOP_LEFT: value = NumericValue(0.f, Unit::PERCENT); break;
-			case CENTER: value = NumericValue(50.f, Unit::PERCENT); break;
-			case BOTTOM_RIGHT: value = NumericValue(100.f, Unit::PERCENT); break;
-			}
-		}
-		else
-		{
-			value = property.GetNumericValue();
-		}
-	}
-	return position;
-}
-
 DecoratorStraightGradient::DecoratorStraightGradient() {}
 
 DecoratorStraightGradient::~DecoratorStraightGradient() {}
@@ -596,7 +570,7 @@ SharedPtr<Decorator> DecoratorRadialGradientInstancer::InstanceDecorator(const S
 	const Property* p_ending_shape = properties_.GetProperty(ids.ending_shape);
 	const Property* p_size_x = properties_.GetProperty(ids.size_x);
 	const Property* p_size_y = properties_.GetProperty(ids.size_y);
-	const Property* p_position[2] = {properties_.GetProperty(ids.position_x), properties_.GetProperty(ids.position_y)};
+	Array<const Property*, 2> p_position = {properties_.GetProperty(ids.position_x), properties_.GetProperty(ids.position_y)};
 	const Property* p_color_stop_list = properties_.GetProperty(ids.color_stop_list);
 
 	if (!p_ending_shape || !p_size_x || !p_size_y || !p_position[0] || !p_position[1] || !p_color_stop_list)
@@ -727,7 +701,7 @@ SharedPtr<Decorator> DecoratorConicGradientInstancer::InstanceDecorator(const St
 	const DecoratorInstancerInterface& /*interface_*/)
 {
 	const Property* p_angle = properties_.GetProperty(ids.angle);
-	const Property* p_position[2] = {properties_.GetProperty(ids.position_x), properties_.GetProperty(ids.position_y)};
+	Array<const Property*, 2> p_position = {properties_.GetProperty(ids.position_x), properties_.GetProperty(ids.position_y)};
 	const Property* p_color_stop_list = properties_.GetProperty(ids.color_stop_list);
 
 	if (!p_angle || !p_position[0] || !p_position[1] || !p_color_stop_list)

+ 1 - 2
Source/Core/DecoratorGradient.h

@@ -33,11 +33,10 @@
 #include "../../Include/RmlUi/Core/Decorator.h"
 #include "../../Include/RmlUi/Core/Geometry.h"
 #include "../../Include/RmlUi/Core/ID.h"
+#include "DecoratorUtilities.h"
 
 namespace Rml {
 
-using Vector2Numeric = Vector2<NumericValue>;
-
 /**
     Straight gradient.
 

+ 169 - 0
Source/Core/DecoratorText.cpp

@@ -0,0 +1,169 @@
+/*
+ * This source file is part of RmlUi, the HTML/CSS Interface Middleware
+ *
+ * For the latest information, see http://github.com/mikke89/RmlUi
+ *
+ * Copyright (c) 2008-2010 CodePoint Ltd, Shift Technology Ltd
+ * Copyright (c) 2019-2024 The RmlUi Team, and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+#include "DecoratorText.h"
+#include "../../Include/RmlUi/Core/ComputedValues.h"
+#include "../../Include/RmlUi/Core/Context.h"
+#include "../../Include/RmlUi/Core/Element.h"
+#include "../../Include/RmlUi/Core/FontEngineInterface.h"
+#include "../../Include/RmlUi/Core/Geometry.h"
+#include "../../Include/RmlUi/Core/PropertyDefinition.h"
+#include "../../Include/RmlUi/Core/RenderManager.h"
+#include "../../Include/RmlUi/Core/TextShapingContext.h"
+
+namespace Rml {
+
+DecoratorText::DecoratorText() {}
+
+DecoratorText::~DecoratorText() {}
+
+void DecoratorText::Initialise(String in_text, bool in_inherit_color, Colourb in_color, Vector2Numeric in_align)
+{
+	text = std::move(in_text);
+	inherit_color = in_inherit_color;
+	color = in_color;
+	align = in_align;
+}
+
+DecoratorDataHandle DecoratorText::GenerateElementData(Element* element, BoxArea paint_area) const
+{
+	ElementData* data = new ElementData{paint_area, {}, -1};
+
+	if (!GenerateGeometry(element, *data))
+	{
+		Log::Message(Log::LT_WARNING, "Could not construct text decorator with text %s on element %s", text.c_str(), element->GetAddress().c_str());
+		return {};
+	}
+
+	return reinterpret_cast<DecoratorDataHandle>(data);
+}
+
+void DecoratorText::ReleaseElementData(DecoratorDataHandle element_data) const
+{
+	delete reinterpret_cast<ElementData*>(element_data);
+}
+
+void DecoratorText::RenderElement(Element* element, DecoratorDataHandle element_data) const
+{
+	ElementData* data = reinterpret_cast<ElementData*>(element_data);
+	if (!GenerateGeometry(element, *data))
+		return;
+
+	const Vector2f translation = element->GetAbsoluteOffset(BoxArea::Border);
+
+	for (size_t i = 0; i < data->textured_geometry.size(); ++i)
+		data->textured_geometry[i].geometry.Render(translation, data->textured_geometry[i].texture);
+}
+
+bool DecoratorText::GenerateGeometry(Element* element, ElementData& element_data) const
+{
+	FontFaceHandle font_face_handle = element->GetFontFaceHandle();
+	if (font_face_handle == 0)
+		return false;
+
+	FontEngineInterface* font_engine_interface = GetFontEngineInterface();
+	const int new_version = font_engine_interface->GetVersion(font_face_handle);
+	if (new_version == element_data.font_handle_version)
+		return true;
+
+	const auto& computed = element->GetComputedValues();
+	const TextShapingContext text_shaping_context{computed.language(), computed.direction(), computed.letter_spacing()};
+
+	const int string_width = font_engine_interface->GetStringWidth(font_face_handle, text, text_shaping_context);
+
+	const FontMetrics& metrics = font_engine_interface->GetFontMetrics(font_face_handle);
+	const RenderBox render_box = element->GetRenderBox(element_data.paint_area);
+	const Vector2f text_size = {float(string_width), metrics.ascent + metrics.descent};
+	const Vector2f offset_to_align_area = render_box.GetFillOffset() + Vector2f{0, metrics.ascent};
+	const Vector2f size_of_align_area = render_box.GetFillSize() - text_size;
+	const Vector2f offset_within_align_area =
+		Vector2f{element->ResolveNumericValue(align.x, size_of_align_area.x), element->ResolveNumericValue(align.y, size_of_align_area.y)};
+
+	const Vector2f offset = offset_to_align_area + offset_within_align_area;
+	const float opacity = computed.opacity();
+	const ColourbPremultiplied text_color = (inherit_color ? computed.color() : color).ToPremultiplied(opacity);
+
+	RenderManager& render_manager = element->GetContext()->GetRenderManager();
+	TexturedMeshList mesh_list;
+	font_engine_interface->GenerateString(render_manager, font_face_handle, {}, text, offset, text_color, opacity, text_shaping_context, mesh_list);
+
+	if (mesh_list.empty())
+		return false;
+
+	Vector<TexturedGeometry> textured_geometry(mesh_list.size());
+	for (size_t i = 0; i < textured_geometry.size(); i++)
+	{
+		textured_geometry[i].geometry = render_manager.MakeGeometry(std::move(mesh_list[i].mesh));
+		textured_geometry[i].texture = mesh_list[i].texture;
+	}
+
+	element_data = ElementData{
+		element_data.paint_area,
+		std::move(textured_geometry),
+		font_engine_interface->GetVersion(font_face_handle),
+	};
+
+	return true;
+}
+
+DecoratorTextInstancer::DecoratorTextInstancer()
+{
+	ids = {};
+	ids.text = RegisterProperty("text", "").AddParser("string").GetId();
+	ids.color = RegisterProperty("color", "inherit-color").AddParser("keyword", "inherit-color").AddParser("color").GetId();
+	ids.align_x = RegisterProperty("align-x", "center").AddParser("keyword", "left, center, right").AddParser("length_percent").GetId();
+	ids.align_y = RegisterProperty("align-y", "center").AddParser("keyword", "top, center, bottom").AddParser("length_percent").GetId();
+
+	RegisterShorthand("decorator", "text, color, align-x, align-y, align-x", ShorthandType::FallThrough);
+}
+
+DecoratorTextInstancer::~DecoratorTextInstancer() {}
+
+SharedPtr<Decorator> DecoratorTextInstancer::InstanceDecorator(const String& /*name*/, const PropertyDictionary& properties,
+	const DecoratorInstancerInterface& /*instancer_interface*/)
+{
+	const Property* p_text = properties.GetProperty(ids.text);
+	const Property* p_color = properties.GetProperty(ids.color);
+	Array<const Property*, 2> p_align = {properties.GetProperty(ids.align_x), properties.GetProperty(ids.align_y)};
+	if (!p_text || !p_color || !p_align[0] || !p_align[1])
+		return nullptr;
+
+	String text = StringUtilities::DecodeRml(p_text->Get<String>());
+	if (text.empty())
+		return nullptr;
+
+	const bool inherit_color = (p_color->unit == Unit::KEYWORD);
+	const Colourb color = (p_color->unit == Unit::COLOUR ? p_color->Get<Colourb>() : Colourb{});
+	const Vector2Numeric align = ComputePosition(p_align);
+
+	auto decorator = MakeShared<DecoratorText>();
+	decorator->Initialise(std::move(text), inherit_color, color, align);
+	return decorator;
+}
+
+} // namespace Rml

+ 86 - 0
Source/Core/DecoratorText.h

@@ -0,0 +1,86 @@
+/*
+ * This source file is part of RmlUi, the HTML/CSS Interface Middleware
+ *
+ * For the latest information, see http://github.com/mikke89/RmlUi
+ *
+ * Copyright (c) 2008-2010 CodePoint Ltd, Shift Technology Ltd
+ * Copyright (c) 2019-2024 The RmlUi Team, and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+#ifndef RMLUI_CORE_DECORATORTEXT_H
+#define RMLUI_CORE_DECORATORTEXT_H
+
+#include "../../Include/RmlUi/Core/Decorator.h"
+#include "../../Include/RmlUi/Core/Geometry.h"
+#include "../../Include/RmlUi/Core/ID.h"
+#include "DecoratorUtilities.h"
+
+namespace Rml {
+
+class DecoratorText : public Decorator {
+public:
+	DecoratorText();
+	virtual ~DecoratorText();
+
+	void Initialise(String text, bool inherit_color, Colourb color, Vector2Numeric align);
+
+	DecoratorDataHandle GenerateElementData(Element* element, BoxArea paint_area) const override;
+	void ReleaseElementData(DecoratorDataHandle element_data) const override;
+
+	void RenderElement(Element* element, DecoratorDataHandle element_data) const override;
+
+private:
+	struct TexturedGeometry {
+		Geometry geometry;
+		Texture texture;
+	};
+	struct ElementData {
+		BoxArea paint_area;
+		Vector<TexturedGeometry> textured_geometry;
+		int font_handle_version;
+	};
+
+	bool GenerateGeometry(Element* element, ElementData& element_data) const;
+
+	String text;
+	bool inherit_color = false;
+	Colourb color;
+	Vector2Numeric align;
+};
+
+class DecoratorTextInstancer : public DecoratorInstancer {
+public:
+	DecoratorTextInstancer();
+	~DecoratorTextInstancer();
+
+	SharedPtr<Decorator> InstanceDecorator(const String& name, const PropertyDictionary& properties,
+		const DecoratorInstancerInterface& instancer_interface) override;
+
+private:
+	struct PropertyIds {
+		PropertyId text, color, align_x, align_y;
+	};
+	PropertyIds ids;
+};
+
+} // namespace Rml
+#endif

+ 59 - 0
Source/Core/DecoratorUtilities.cpp

@@ -0,0 +1,59 @@
+/*
+ * This source file is part of RmlUi, the HTML/CSS Interface Middleware
+ *
+ * For the latest information, see http://github.com/mikke89/RmlUi
+ *
+ * Copyright (c) 2008-2010 CodePoint Ltd, Shift Technology Ltd
+ * Copyright (c) 2019-2024 The RmlUi Team, and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+#include "DecoratorUtilities.h"
+#include "../../Include/RmlUi/Core/Property.h"
+
+namespace Rml {
+
+Vector2Numeric ComputePosition(Array<const Property*, 2> p_position)
+{
+	Vector2Numeric position;
+	for (int dimension = 0; dimension < 2; dimension++)
+	{
+		NumericValue& value = position[dimension];
+		const Property& property = *p_position[dimension];
+		if (property.unit == Unit::KEYWORD)
+		{
+			enum { TOP_LEFT, CENTER, BOTTOM_RIGHT };
+			switch (property.Get<int>())
+			{
+			case TOP_LEFT: value = NumericValue(0.f, Unit::PERCENT); break;
+			case CENTER: value = NumericValue(50.f, Unit::PERCENT); break;
+			case BOTTOM_RIGHT: value = NumericValue(100.f, Unit::PERCENT); break;
+			}
+		}
+		else
+		{
+			value = property.GetNumericValue();
+		}
+	}
+	return position;
+}
+
+} // namespace Rml

+ 43 - 0
Source/Core/DecoratorUtilities.h

@@ -0,0 +1,43 @@
+/*
+ * This source file is part of RmlUi, the HTML/CSS Interface Middleware
+ *
+ * For the latest information, see http://github.com/mikke89/RmlUi
+ *
+ * Copyright (c) 2008-2010 CodePoint Ltd, Shift Technology Ltd
+ * Copyright (c) 2019-2024 The RmlUi Team, and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+#ifndef RMLUI_CORE_DECORATORUTILITIES_H
+#define RMLUI_CORE_DECORATORUTILITIES_H
+
+#include "../../Include/RmlUi/Core/NumericValue.h"
+#include "../../Include/RmlUi/Core/Types.h"
+
+namespace Rml {
+
+using Vector2Numeric = Vector2<NumericValue>;
+
+// Compute a 2d-position property value into a percentage-length vector.
+Vector2Numeric ComputePosition(Array<const Property*, 2> p_position);
+
+} // namespace Rml
+#endif

+ 3 - 0
Source/Core/Factory.cpp

@@ -52,6 +52,7 @@
 #include "DecoratorGradient.h"
 #include "DecoratorNinePatch.h"
 #include "DecoratorShader.h"
+#include "DecoratorText.h"
 #include "DecoratorTiledBox.h"
 #include "DecoratorTiledHorizontal.h"
 #include "DecoratorTiledImage.h"
@@ -109,6 +110,7 @@ struct DefaultInstancers {
 	ElementInstancerGeneric<ElementProgress> progress;
 
 	// Decorators
+	DecoratorTextInstancer decorator_text;
 	DecoratorTiledHorizontalInstancer decorator_tiled_horizontal;
 	DecoratorTiledVerticalInstancer decorator_tiled_vertical;
 	DecoratorTiledBoxInstancer decorator_tiled_box;
@@ -220,6 +222,7 @@ void Factory::Initialise()
 	RegisterElementInstancer("progressbar", &default_instancers.progress);
 
 	// Decorator instancers
+	RegisterDecoratorInstancer("text", &default_instancers.decorator_text);
 	RegisterDecoratorInstancer("tiled-horizontal", &default_instancers.decorator_tiled_horizontal);
 	RegisterDecoratorInstancer("tiled-vertical", &default_instancers.decorator_tiled_vertical);
 	RegisterDecoratorInstancer("tiled-box", &default_instancers.decorator_tiled_box);

+ 87 - 0
Tests/Data/VisualTests/text_decorator.rml

@@ -0,0 +1,87 @@
+<rml>
+<head>
+	<title>Text decorator</title>
+	<link type="text/rcss" href="../style.rcss"/>
+	<meta name="Description" content="A variety of text decorators. Hover over the elements to change the decorator."/>
+	<style>
+		body {
+			background: #ddd;
+			color: #333;
+			width: 900dp;
+		}
+		div {
+			margin: 5dp;
+			width: 160dp;
+			height: 60dp;
+			box-sizing: border-box;
+			border: 1dp #bbb;
+			padding: 10px;
+			float: left;
+		}
+		group {
+			margin-left: 1em;
+			display: flow-root;
+			margin-bottom: 1em;
+		}
+
+		group > :nth-child(n):hover { decorator: text("Hello ♥ world!" red); }
+
+		.basic > :nth-child(1) { decorator: text("Hello &#x1F30E; world!"); }
+		.basic > :nth-child(2) { decorator: text("Hello 🌎 world!" #333); }
+		.basic > :nth-child(3) { decorator: text("Hello 🌎 world!" center center); }
+		.basic > :nth-child(4) { decorator: text("Hello 🌎 world!" 50% 50%); }
+
+		.align_top_left > :nth-child(1) { decorator: text("Hello 🌎 world!" top left); }
+		.align_top_left > :nth-child(2) { decorator: text("Hello 🌎 world!" left top); }
+		.align_top_left > :nth-child(3) { decorator: text("Hello 🌎 world!" 0 0); }
+		.align_top_left > :nth-child(4) { decorator: text("Hello 🌎 world!" 0dp 0dp); }
+		.align_top_left > :nth-child(5) { decorator: text("Hello 🌎 world!" 0% 0%); }
+
+		.color > :nth-child(1) { decorator: text("Hello 🌎 world!" blue); }
+		.color > :nth-child(2) { decorator: text("Hello 🌎 world!" #00f); }
+		.color > :nth-child(3) { decorator: text("Hello 🌎 world!"); color: blue; }
+
+		.misc > :nth-child(1) { decorator: text("Hello 🌎 world!" black bottom right); }
+		.misc > :nth-child(2) { decorator: text("Hello 🌎 world!" black bottom right) content-box; }
+		.misc > :nth-child(3) { decorator: text("Helloooo    🌎    woooorld!" black) content-box; }
+		.misc > :nth-child(4) { decorator: text("Hello 🌎 world!" fuchsia 20px 20%); }
+		.misc > :nth-child(5) { decorator: text("Hello 🌎 world!" fuchsia 20px 20%); opacity: 0.5; }
+
+	</style>
+</head>
+
+<body>
+Default properties [equivalent]
+<group class="basic">
+	<div/>
+	<div/>
+	<div/>
+	<div/>
+</group>
+
+Top-left alignment [equivalent]
+<group class="align_top_left">
+	<div/>
+	<div/>
+	<div/>
+	<div/>
+	<div/>
+</group>
+
+Blue text [equivalent]
+<group class="color">
+	<div/>
+	<div/>
+	<div/>
+</group>
+
+Miscellaneous
+<group class="misc">
+	<div/>
+	<div/>
+	<div/>
+	<div/>
+	<div/>
+</group>
+</body>
+</rml>

+ 10 - 0
changelog.md

@@ -44,6 +44,16 @@ The `<handle>` element has received several major improvements.
   - When the target's containing block has a border.
   - When the target is set to relative positioning and offset from the top-left corner.
 
+### New decorator: `text`
+
+Added a new decorator to render text as a background on elements. This can be particularly helpful when using icon fonts, and even allows using such fonts for generated elements. #348 #679
+
+```
+decorator: text("Hello 🌎 world!" blue bottom right);
+```
+
+The font face will be inherited from the element it is being applied to. However, it can be colored independently. Further, the text can be freely aligned within the element using lengths, percentages, or keywords. Unicode numerical references are supported with the HTML syntax, e.g. `&#x1F30E;`.
+
 ### Flexbox layout improvements
 
 - Apply automatic minimum size of flex items in column mode with auto size. #658