Introduce example that shows advanced text features

This example demonstrates how to use variable axis support in Qt to make text fit in a pre-defined layout. The example is given a non-specific name so that it can easily be expanded to show additional font features later. Pick-to: 6.8 Change-Id: Ic18b177f02a21fa9e7726bb35e94ed6ecc93bafd Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
author: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io> 2024-07-22 11:55:21 +0200
committer: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io> 2024-08-29 01:35:26 +0200
commit: 0b23a68fabf6bfcb03d04db7119c2985d7b5d84d (patch)
tree: 4993baa12da02a2f25b24ec7335a7f4b50069766 /examples/quick/advancedtext
parent: 091a2eae9f260bf66b49d528e9484840216dd287 (diff)
9 files changed, 255 insertions, 0 deletions
diff --git a/examples/quick/advancedtext/CMakeLists.txt b/examples/quick/advancedtext/CMakeLists.txt
new file mode 100644
index 0000000000..b213bc1d8c
--- /dev/null
+++ b/examples/quick/advancedtext/CMakeLists.txt
@@ -0,0 +1,46 @@
+# Copyright (C) 2024 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.16)
+project(advancedtext LANGUAGES CXX)
+
+find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)
+
+qt_standard_project_setup(REQUIRES 6.8)
+
+qt_add_executable(advancedtextexample
+    WIN32
+    MACOSX_BUNDLE
+    main.cpp
+)
+
+target_link_libraries(advancedtextexample PRIVATE
+    Qt6::Core
+    Qt6::Gui
+    Qt6::Qml
+    Qt6::Quick
+)
+
+qt_add_qml_module(advancedtextexample
+    URI advancedtext
+    QML_FILES
+        "Main.qml"
+        "TextSample.qml"
+    RESOURCES
+        "fonts/Georama-VariableFont_wdth,wght.ttf"
+)
+
+install(TARGETS advancedtextexample
+    BUNDLE  DESTINATION .
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+)
+
+qt_generate_deploy_qml_app_script(
+    TARGET advancedtextexample
+    OUTPUT_SCRIPT deploy_script
+    MACOS_BUNDLE_POST_BUILD
+    NO_UNSUPPORTED_PLATFORM_ERROR
+    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
+)
+install(SCRIPT ${deploy_script})
diff --git a/examples/quick/advancedtext/Main.qml b/examples/quick/advancedtext/Main.qml
new file mode 100644
index 0000000000..6280a92b29
--- /dev/null
+++ b/examples/quick/advancedtext/Main.qml
@@ -0,0 +1,53 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+import QtQuick
+import QtQuick.Controls
+import QtQuick.Layouts
+
+ApplicationWindow {
+    width: 320
+    height: 480
+    visible: true
+    title: qsTr("Advanced Text Example")
+
+    FontLoader {
+        id: georama
+        source: "fonts/Georama-VariableFont_wdth,wght.ttf"
+    }
+
+    Column {
+        id: column
+
+        anchors.top: parent.top
+        anchors.bottom: parent.bottom
+        anchors.horizontalCenter: parent.horizontalCenter
+        width: parent.width * 0.6
+        spacing: 20
+
+        Text {
+            width: parent.width
+            font.pixelSize: 12
+            wrapMode: Text.WrapAtWordBoundaryOrAnywhere
+            text: qsTr("The following text does not fit in its layout. Fine-tune the width and weight to make it fit.")
+        }
+
+        TextSample {
+            anchors.topMargin: 50
+            text: qsTr("Breaking: News!")
+            font.pixelSize: 32
+        }
+
+        TextSample {
+            font.pixelSize: 18
+            text: "Lorem ipsum dolor sit amet,\n" +
+                  "consectetur adipiscing elit.\n" +
+                  "Praesent ornare nunc vel mauris\n" +
+                  "bibendum gravida.\n" +
+                  "Maecenas sed massa maximus,\n" +
+                  "sagittis ex in, tristique ipsum.\n" +
+                  "Vestibulum tincidunt est sapien,\n" +
+                  "ut venenatis sapien tincidunt ut."
+        }
+    }
+}
diff --git a/examples/quick/advancedtext/TextSample.qml b/examples/quick/advancedtext/TextSample.qml
new file mode 100644
index 0000000000..9dfca939f2
--- /dev/null
+++ b/examples/quick/advancedtext/TextSample.qml
@@ -0,0 +1,75 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+import QtQuick
+import QtQuick.Controls
+import QtQuick.Layouts
+
+Item {
+    id: textSample
+    property bool textFits: textLabel.implicitWidth < statusRectangle.width
+                            && statusRectangle.width - textLabel.implicitWidth < 20
+    property alias text: textLabel.text
+    property alias font: textLabel.font
+
+    width: parent.width
+    height: textLabel.height + controlsLayout.height
+    anchors.margins: 10
+
+    Rectangle {
+        id: statusRectangle
+        color: "transparent"
+        border.color: textFits ? "forestgreen" : "firebrick"
+        border.width: 2
+        radius: 10
+        anchors.fill: parent
+
+        anchors.margins: -5
+        antialiasing: true
+    }
+
+    Column {
+        anchors.fill: parent
+        id: column
+        Label {
+            id: textLabel
+            font.family: georama.name
+//! [variableAxes]
+            font.variableAxes: {
+                "wdth": widthSlider.value,
+                "wght": weightSlider.value
+            }
+//! [variableAxes]
+        }
+
+        GridLayout {
+            id: controlsLayout
+            width: parent.width
+            columns: 2
+            Label {
+                Layout.margins: 5
+                text: qsTr("Width")
+            }
+            Slider {
+                id: widthSlider
+                from: 62.5
+                to: 150
+                value: 100
+                Layout.fillWidth: true
+                Layout.margins: 5
+            }
+            Label {
+                text: qsTr("Weight")
+                Layout.margins: 5
+            }
+            Slider {
+                id: weightSlider
+                from: 100
+                to: 900
+                value: 400
+                Layout.fillWidth: true
+                Layout.margins: 5
+            }
+        }
+    }
+}
diff --git a/examples/quick/advancedtext/doc/images/qml-advancedtext-example-wrong.png b/examples/quick/advancedtext/doc/images/qml-advancedtext-example-wrong.png
new file mode 100644
index 0000000000..3bf5928146
--- /dev/null
+++ b/examples/quick/advancedtext/doc/images/qml-advancedtext-example-wrong.png
diff --git a/examples/quick/advancedtext/doc/images/qml-advancedtext-example.png b/examples/quick/advancedtext/doc/images/qml-advancedtext-example.png
new file mode 100644
index 0000000000..f7cb5ed0f1
--- /dev/null
+++ b/examples/quick/advancedtext/doc/images/qml-advancedtext-example.png
diff --git a/examples/quick/advancedtext/doc/src/advancedtext.qdoc b/examples/quick/advancedtext/doc/src/advancedtext.qdoc
new file mode 100644
index 0000000000..64dcf00a4b
--- /dev/null
+++ b/examples/quick/advancedtext/doc/src/advancedtext.qdoc
@@ -0,0 +1,51 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+/*!
+    \title Advanced Text Example
+    \example advancedtext
+    \image qml-advancedtext-example.png
+    \brief A Qt Quick example demonstrating some advanced features of text.
+    \ingroup qtquickexamples
+    \examplecategory {Graphics}
+
+    Traditionally, font families have been distributed in a limited number of variations: a set
+    of hardcoded weights, styles and widths (and combinations of these) that can be selected as
+    standalone fonts.
+
+    Variable fonts expands on this idea. Instead of distributing the variations of the font family
+    as stand-alone font files, a single variable font can produce the variations (and many more)
+    through interpolation.
+
+    This is achieved by defining so-called "variable axes" in the font for properties such as
+    width, slant or weight. The user may select from preset values along these axes or set any
+    custom value in the range the font supports.
+
+    This example includes a variable font called "Georama" (Copyright 2020 The Georama Project
+    Authors, Licensed under OFL 1.1). It has two variable axes: One for weight and one for width.
+    By manipulating either of these, the user can create a wide range of variations over the font
+    design.
+
+    The example illustrates how this may be used in a real world scenario: When starting the
+    example, the text snippets stretch outside the bounding boxes defined in the strict layout.
+
+    \image qml-advancedtext-example-wrong.png
+
+    By tweaking the width and/or weight, the visual designer can get variations of the font which
+    fit the layout exactly without having to change the font size.
+
+    \image qml-advancedtext-example.png
+
+    The example assigns sliders to each of the two variable axes in the font. It then binds the
+    variable axis values to the sliders so that the font updates automatically when the user changes
+    them.
+
+    \snippet advancedtext/TextSample.qml variableAxes
+
+    The variable axes are addressed by their four-character tag. Some tags, such as "wdth" and
+    "wght", are mapped to specific font attributes by convention (in this case: "width" and
+    "weight", respectively.) But the font may support any axis as long as it is denoted by a
+    four-character tag. Information about the axes the font supports will often be included in
+    its file name.
+
+    \include examples-run.qdocinc
+*/
diff --git a/examples/quick/advancedtext/fonts/Georama-VariableFont_wdth,wght.ttf b/examples/quick/advancedtext/fonts/Georama-VariableFont_wdth,wght.ttf
new file mode 100644
index 0000000000..b991822100
--- /dev/null
+++ b/examples/quick/advancedtext/fonts/Georama-VariableFont_wdth,wght.ttf
diff --git a/examples/quick/advancedtext/main.cpp b/examples/quick/advancedtext/main.cpp
new file mode 100644
index 0000000000..2002b9f5ea
--- /dev/null
+++ b/examples/quick/advancedtext/main.cpp
@@ -0,0 +1,16 @@
+// Copyright (C) 2024 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#include <QGuiApplication>
+#include <QQmlApplicationEngine>
+
+int main(int argc, char *argv[])
+{
+    QGuiApplication app(argc, argv);
+    app.setOrganizationName("QtProject");
+
+    QQmlApplicationEngine engine;
+    engine.loadFromModule("advancedtext", "Main");
+
+    return app.exec();
+}
diff --git a/examples/quick/advancedtext/qt_attribution.json b/examples/quick/advancedtext/qt_attribution.json
new file mode 100644
index 0000000000..09c5ee295e
--- /dev/null
+++ b/examples/quick/advancedtext/qt_attribution.json
@@ -0,0 +1,14 @@
+[
+    {
+        "Id": "georama-font",
+        "Name": "Georama",
+        "QDocModule": "qtquick",
+        "QtUsage": "Used in the Advanced Text example",
+        "QtParts": [ "examples" ],
+        "Files": "fonts/Georama-VariableFont_wdth,wght.ttf",
+        "LicenseId": "OFL-1.1",
+        "License": "SIL Open Font License 1.1",
+        "Homepage": "https://github.com/productiontype/Georama",
+        "Copyright": "Copyright 2020 The Georama Project Authors"
+    }
+]
author	Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>	2024-07-22 11:55:21 +0200
committer	Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@qt.io>	2024-08-29 01:35:26 +0200
commit	0b23a68fabf6bfcb03d04db7119c2985d7b5d84d (patch)
tree	4993baa12da02a2f25b24ec7335a7f4b50069766 /examples/quick/advancedtext
parent	091a2eae9f260bf66b49d528e9484840216dd287 (diff)