91 lines
2.8 KiB
ReStructuredText
91 lines
2.8 KiB
ReStructuredText
.. _xml_fonts:
|
|
|
|
=====
|
|
Fonts
|
|
=====
|
|
|
|
Overview
|
|
********
|
|
|
|
A ``<fonts>`` section can be added in ``globals.xml`` files.
|
|
Later, it might be supported in components and widgets to define local fonts and keep the global space cleaner.
|
|
|
|
Usage
|
|
*****
|
|
|
|
The following section creates a mapping between font names and their paths with various attributes:
|
|
|
|
.. code-block:: xml
|
|
|
|
<fonts>
|
|
<bin as_file="false" name="medium" src="path/to/file.ttf" range="0x20-0x7f" symbols="°" size="24"/>
|
|
<tiny_ttf as_file="true" name="big" src_path="path/to/file.ttf" range="0x20-0x7f" symbols="auto" size="48"/>
|
|
<freetype name="chinese" src_path="file.ttf" size="48" custom_freetype_attribute="abc"/>
|
|
</fonts>
|
|
|
|
In ``<styles>`` and ``<view>``, fonts can be referenced by their name, e.g.,
|
|
|
|
.. code-block:: xml
|
|
|
|
<style name="style1" text_font="medium"/>
|
|
|
|
The tag name determines how the font is loaded. Currently, only ``tinyttf as_file="true"`` is supported.
|
|
|
|
- ``bin``:
|
|
- If ``as_file="true"``: Converts the font file to ``bin`` (see `lv_font_conv`)
|
|
which will be loaded by ``lv_binfont_create()``.
|
|
- If ``as_file="false"`` (default): On export, the font file will be converted to a C array LVGL font
|
|
that can be used directly by LVGL.
|
|
- ``tinyttf``:
|
|
- If ``as_file="true"``: Can be loaded directly by ``lv_tiny_ttf_create_file()``.
|
|
- If ``as_file="false"`` (default): The font file will be converted to a raw C array on export
|
|
that will be loaded by ``lv_tiny_ttf_create_data()``.
|
|
- ``freetype``: The file can be loaded directly by ``lv_freetype_font_create()``.
|
|
|
|
For simplicity, if ``as_file="false"``, fonts will be loaded as files in the preview.
|
|
Setting ``as_file="false"`` affects only the C export.
|
|
|
|
If the UI is created from XML at runtime and a ``globals.xml`` is parsed, the ``as_file="false"`` tags are skipped
|
|
because it is assumed that the user manually creates the mapping. This is because the XML parser cannot
|
|
automatically map an LVGL font definition like:
|
|
|
|
.. code-block:: c
|
|
|
|
lv_font_t my_font_24;
|
|
|
|
to
|
|
|
|
.. code-block:: xml
|
|
|
|
<bin name="my_font_24"/>
|
|
|
|
Exported Code
|
|
-------------
|
|
|
|
When C code is exported, global ``const lv_font_t * <font_name>`` variables are created, and in the
|
|
initialization function of the component library (e.g., ``my_lib_init_gen()``), the actual font is assigned.
|
|
|
|
In :cpp:expr:`lv_style_set_text_font(&style1, <font_name>)`, the created font is referenced.
|
|
|
|
Constants
|
|
---------
|
|
|
|
Constants can also be used with fonts.
|
|
|
|
.. code-block:: xml
|
|
|
|
<consts>
|
|
<int name="font_size" value="32">
|
|
<variant name="size" case="small" value="24"/>
|
|
</int>
|
|
</consts>
|
|
|
|
<fonts>
|
|
<bin name="medium" src_path="file.ttf" range="0x20-0x7f" symbols="°" size="#font_size"/>
|
|
</fonts>
|
|
|
|
Default Font
|
|
------------
|
|
|
|
``"lv_font_default"`` can be used to access ``LV_FONT_DEFAULT``. Other built-in fonts are not exposed by default.
|