From 78503bd9356e66fa604c863880eece9795a61a72 Mon Sep 17 00:00:00 2001 From: laiskasiili Date: Wed, 11 Sep 2024 18:41:47 +0200 Subject: [PATCH 1/2] Restructure html label section and add word-spacing Harmonize css properties Remove trailing dot in list Fix typo Include review feedback Qt docs reference to supported subset of html and css Streamline structure of html and css section and add little more examples of HTML tags. --- .../style_library/label_settings.rst | 99 ++++++++++++------- 1 file changed, 61 insertions(+), 38 deletions(-) diff --git a/docs/user_manual/style_library/label_settings.rst b/docs/user_manual/style_library/label_settings.rst index 84d9134a56b..1f4764962bf 100644 --- a/docs/user_manual/style_library/label_settings.rst +++ b/docs/user_manual/style_library/label_settings.rst @@ -130,59 +130,82 @@ In the |text| :guilabel:`Text` tab, you can set: * the :guilabel:`Size` in any :ref:`supported unit ` * the :guilabel:`Color` * the :guilabel:`Opacity` -* and :guilabel:`Allow HTML Formatting`: - The HTML formatting option enables the proper rendering of some HTML tags to customize the label. - The supported HTML tags are: +* and :guilabel:`Allow HTML Formatting` enables the use of a subset of HTML tags and CSS rules to customize the label. + +At the bottom of the tab, a widget shows a filterable list of compatible items +stored in your :ref:`style manager database `. +This allows you to easily configure the current text format or label setting +based on an existing one, and also save a new item to the style database: +Press the :guilabel:`Save format...` or :guilabel:`Save settings...` button +and provide a name and tag(s). + +.. note:: When configuring a :guilabel:`Label Settings` item, text format items + are also available in this widget. Select one to quickly overwrite the current + :ref:`textual properties ` of the label. + Likewise, you can create/overwrite a text format from there. - * Color, applicable to text, underline, strikethrough, and overline - * Font properties (font family, font size, bold and italic) - * Superscript and subscript components in text, - where the text will be vertically :sup:`super` or :sub:`sub` aligned - and automatically sized to 2/3 of the parent font size. - You can also set a fixed font size for the superscript/subscript - by including css rules, e.g.: - .. code:: html +.. _labels_text_html: - my superscript text - The CSS formatting rules ``vertical-align: super`` or ``vertical-align: sub`` - are also available in any other HTML element (annotation, layout label or HTML items, ...). +Allow HTML Formatting +..................... - In order to use the HTML formatting, you need to provide the HTML code in the :guilabel:`Value` field. - The expression is parsed and any supported HTML tag overrides its corresponding setting in the labels properties. - They also combine well with other background, shadow, buffer... properties of labels. +With :guilabel:`Allow HTML Formatting` enabled, you need to provide the HTML code in the :guilabel:`Value` field. +Use whitespaces instead of tabs for any kind of indentation. +The expression is parsed and any supported HTML tag overrides its corresponding setting in the labels properties. +An exhaustive list of the supported subset of HTML tags and CSS properties can be found `here `_. - Below an example of a HTML-based expression and rendering - (applies different colors and underline to the same label): +Examples of supported HTML tags: + +* Text formatting, such as italic or bold, e.g.: .. code:: html - format( - '%1 ( %2 ft )', - title( lower( "Name" ) ), - round($length) - ) + QGIS rocks! - .. _figure_label_html_formatting: +* Superscript and subscript, where the text will be vertically :sup:`super` or + :sub:`sub` aligned and automatically sized to 2/3 of the parent font size. + You can also set a fixed font size for the superscript/subscript + by including css rules, e.g.: - .. figure:: img/label_HTML_formatting.png - :align: center + .. code:: html - Labeling with HTML formatting enabled + my superscript text +Examples of supported CSS properties: -At the bottom of the tab, a widget shows a filterable list of compatible items -stored in your :ref:`style manager database `. -This allows you to easily configure the current text format or label setting -based on an existing one, and also save a new item to the style database: -Press the :guilabel:`Save format...` or :guilabel:`Save settings...` button -and provide a name and tag(s). +* Font properties (``color``, ``font-family``, ``font-size``, ``font-weight``, ``font-style``, ``word-spacing``). + Note that ``word-spacing`` will always use unit points. +* Text decorations such as underline, overline and line-through (``text-decoration``) +* Text alignment (``vertical-align``) -.. note:: When configuring a :guilabel:`Label Settings` item, text format items - are also available in this widget. Select one to quickly overwrite the current - :ref:`textual properties ` of the label. - Likewise, you can create/overwrite a text format from there. +CSS properties can be set on HTML tags with the style attribute. +The HTML tag span does not apply any formatting to text by itself and is ideal if you just want to apply CSS styling. +A CSS property name and its value are separated by a colon (``:``). +Multiple CSS properties are separated by semicolon (``;``), e.g.: + +.. code:: html + + I will be displayed as blue underlined text with increased space between words + +Below an example of a HTML-based expression and rendering +(applies different colors and underline to the same label): + +.. code:: html + + format( + '%1 ( %2 ft )', + title( lower( "Name" ) ), + round($length) + ) + +.. _figure_label_html_formatting: + +.. figure:: img/label_HTML_formatting.png + :align: center + + Labeling with HTML formatting enabled .. _labels_formatting: From 2b7b3e53386767d1af78f7c5566a7211ae6100f0 Mon Sep 17 00:00:00 2001 From: DelazJ Date: Tue, 3 Dec 2024 16:06:02 +0100 Subject: [PATCH 2/2] Clarify that we do not support every tags supported by Qt. Yet. And add text and code-block formatting --- .../style_library/label_settings.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/user_manual/style_library/label_settings.rst b/docs/user_manual/style_library/label_settings.rst index 1f4764962bf..2ace9edd61d 100644 --- a/docs/user_manual/style_library/label_settings.rst +++ b/docs/user_manual/style_library/label_settings.rst @@ -154,13 +154,15 @@ Allow HTML Formatting With :guilabel:`Allow HTML Formatting` enabled, you need to provide the HTML code in the :guilabel:`Value` field. Use whitespaces instead of tabs for any kind of indentation. The expression is parsed and any supported HTML tag overrides its corresponding setting in the labels properties. -An exhaustive list of the supported subset of HTML tags and CSS properties can be found `here `_. +Because it is impossible to list and detail every HTML tag and CSS property that QGIS currently supports, +we invite you to explore and test in your labels +`the ones supported `_ by the underlying Qt library. Examples of supported HTML tags: * Text formatting, such as italic or bold, e.g.: - .. code:: html + .. code-block:: html QGIS rocks! @@ -169,7 +171,7 @@ Examples of supported HTML tags: You can also set a fixed font size for the superscript/subscript by including css rules, e.g.: - .. code:: html + .. code-block:: html my superscript text @@ -180,19 +182,20 @@ Examples of supported CSS properties: * Text decorations such as underline, overline and line-through (``text-decoration``) * Text alignment (``vertical-align``) -CSS properties can be set on HTML tags with the style attribute. -The HTML tag span does not apply any formatting to text by itself and is ideal if you just want to apply CSS styling. +CSS properties can be set on HTML tags with the ``style`` attribute. +The HTML tag ``span`` does not apply any formatting to text by itself +and is ideal if you just want to apply CSS styling. A CSS property name and its value are separated by a colon (``:``). Multiple CSS properties are separated by semicolon (``;``), e.g.: -.. code:: html +.. code-block:: html I will be displayed as blue underlined text with increased space between words Below an example of a HTML-based expression and rendering (applies different colors and underline to the same label): -.. code:: html +.. code-block:: html format( '%1 ( %2 ft )',