From 8643ae7a766b0f1c24d11d2dc64af6f23c307ad0 Mon Sep 17 00:00:00 2001 From: Matthias Rauter Date: Tue, 29 Apr 2025 10:20:51 +0200 Subject: [PATCH] Add Qt styling, ids, and classes to string overview graphics While many graphics in core use a light blue color, it does not fit to Qt and to the general styling of the documentation. This patch changes the color to the Qt green. In the long run, I would like to have styling switching between light and dark mode. This patch applies ids and styling so that it could be switched from outside, if the html document this is embedded into sets the correct tags. This will probably require some features in qdoc. Task-number: QTBUG-133882 Change-Id: Iadce79a5f5a99014abe97c19d9e76efac3d49dad Reviewed-by: Mate Barany --- src/corelib/doc/images/string_class_api.svg | 158 +++++++++----- .../doc/images/string_class_calling.svg | 196 +++++++++++------- 2 files changed, 224 insertions(+), 130 deletions(-) diff --git a/src/corelib/doc/images/string_class_api.svg b/src/corelib/doc/images/string_class_api.svg index b3bfc3082da..291057a4241 100644 --- a/src/corelib/doc/images/string_class_api.svg +++ b/src/corelib/doc/images/string_class_api.svg @@ -2,15 +2,36 @@ viewBox="-410 -30 540 470" version="1.1" xmlns="http://www.w3.org/2000/svg"> + + + - + + transform="translate(0, -6)" + class="text-style"> Choosing a string class for creating an API @@ -63,9 +85,10 @@ + transform="translate(0, -6)" + class="text-style"> For a parameter or the return value? @@ -74,9 +97,10 @@ + transform="translate(0, -6)" + class="text-style"> Will you make a persistent copy? @@ -85,21 +109,23 @@ - Reference to - permanent or - temporary? + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="middle" + transform="translate(0, -12)" + class="text-style"> + Reference to + permanent or + temporary? + transform="translate(0, -6)" + class="text-style"> Reference to full or part? @@ -108,8 +134,9 @@ + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="middle" + class="text-style"> const QString&¹ @@ -117,9 +144,10 @@ + transform="translate(0, -8)" + class="text-style"> Q*StringView Parameters: preferably QAnyStringView Generally: any of L1, UTF-8, or UTF-16 @@ -130,115 +158,133 @@ + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="middle" + class="text-style"> QString + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> parameter + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> return value + font-size="12" font-family="Arial" fill="#333333" + text-anchor="left" dominant-baseline="middle" + class="text-style-arrows"> yes + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> no + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> reference + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> full + font-size="12" font-family="Arial" fill="#333333" + text-anchor="left" dominant-baseline="auto" + class="text-style-arrows"> part + font-size="12" font-family="Arial" fill="#333333" + text-anchor="left" dominant-baseline="auto" + class="text-style-arrows"> temporary - 1: If you return a QString in full, you can choose to return a value instead of a reference, allowing you to return a - temporary in the future without - breaking source code compatibility. This is + temporary in the + future without breaking source code compatibility. This is also done for all Qt APIs. diff --git a/src/corelib/doc/images/string_class_calling.svg b/src/corelib/doc/images/string_class_calling.svg index 4253d35705b..9c5a1eecb09 100644 --- a/src/corelib/doc/images/string_class_calling.svg +++ b/src/corelib/doc/images/string_class_calling.svg @@ -2,40 +2,61 @@ viewBox="-410 -30 540 540" version="1.1" xmlns="http://www.w3.org/2000/svg"> + + + + h 120 + a 20,20 0 0 1 20,20 + v 0 + a 20,20 0 0 1 -20,20 + h -120 + a 20,20 0 0 1 -20,-20 + v 0 + a 20,20 0 0 1 20,-20 + Z"/> + h 80 + a 20,20 0 0 1 20,20 + v 0 + a 20,20 0 0 1 -20,20 + h -80 + a 20,20 0 0 1 -20,-20 + v 0 + a 20,20 0 0 1 20,-20 + Z"/> - + + transform="translate(0, -6)" + class="text-style"> Choosing a string class for calling Qt functions @@ -63,9 +85,10 @@ + transform="translate(0, -12)" + class="text-style"> Is your string known at compile time (a literal)? @@ -75,9 +98,10 @@ + transform="translate(0, -6)" + class="text-style"> Is the parameter a QString or a Q*View? @@ -87,9 +111,10 @@ + transform="translate(0, -6)" + class="text-style"> Has the parameter a preferred² encoding? @@ -99,9 +124,10 @@ + transform="translate(0, -6)" + class="text-style"> Is your string ASCII? @@ -110,9 +136,10 @@ + transform="translate(0, -4)" + class="text-style"> QString¹ or any other owning string @@ -121,9 +148,10 @@ + transform="translate(0, -4)" + class="text-style"> QStringLiteral same as u"foo"_s @@ -132,9 +160,10 @@ + transform="translate(0, -4)" + class="text-style"> QLatin1StringView create with "foo"_L1 @@ -143,9 +172,10 @@ + transform="translate(0, -4)" + class="text-style"> QStringView create with u"foo" f @@ -155,9 +185,10 @@ + transform="translate(0, -8)" + class="text-style"> Q*StringView of the preferred encoding, create with u"foo", u8"foo" or "foo"_L1 @@ -166,28 +197,33 @@ + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> yes + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> no @@ -195,11 +231,13 @@ + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> QString @@ -207,33 +245,39 @@ + font-size="12" font-family="Arial" fill="#333333" + text-anchor="left" dominant-baseline="middle" + class="text-style-arrows"> Q*View + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> no + font-size="12" font-family="Arial" fill="#333333" + text-anchor="left" dominant-baseline="middle" + class="text-style-arrows"> yes @@ -241,35 +285,39 @@ + font-size="12" font-family="Arial" fill="#333333" + text-anchor="middle" dominant-baseline="auto" + class="text-style-arrows"> yes + font-size="12" font-family="Arial" fill="#333333" + text-anchor="left" dominant-baseline="middle" + class="text-style-arrows"> no - 1: An owning string is required to assemble or store a string at runtime, if it is not known at compile time. This can be - QString or any other - owning string, such as std::string. The correct + QString or any + other owning string, such as std::string. The correct choice depends on the required encoding. 2: Some functions are more effective when using the