diff --git a/docs/details/libs/freetype.rst b/docs/details/libs/freetype.rst index 87abcf768..ac7896778 100644 --- a/docs/details/libs/freetype.rst +++ b/docs/details/libs/freetype.rst @@ -4,21 +4,27 @@ FreeType support ================ -Interface to FreeType library to generate font bitmap at run time. +Interface to FreeType library to generate font bitmaps at run time. + +A detailed introduction can be found at: https://freetype.org/ . + -Detailed introduction: https://www.freetype.org Add FreeType to your project ----------------------------- +**************************** First, Download FreeType from `here `__. +If you haven't already done so, now is a good time to get familiar with setting up +and configuring this library. The above website is a good place to start, as is the +``README`` file in the top directory of the freetype project directory. + There are two ways to use FreeType: For UNIX -~~~~~~~~ +-------- -For UNIX systems, it is recommended to use the way of compiling and installing libraries. +For UNIX systems, the following is recommended to compile and install FreeType libraries. - Enter the FreeType source code directory - ``make`` @@ -27,12 +33,16 @@ For UNIX systems, it is recommended to use the way of compiling and installing l - Link library: ``freetype`` (for GCC: ``-L/usr/local/lib -lfreetype``) For Embedded Devices -~~~~~~~~~~~~~~~~~~~~ +-------------------- -For embedded devices, it is more recommended to use the FreeType -configuration file provided by LVGL, which only includes the most -commonly used functions, which is very meaningful for saving limited -FLASH space. +For embedded devices, it is recommended to use the FreeType +configuration files provided by LVGL: + +- lvgl/src/libs/freetype/ftmodule.h +- lvgl/src/libs/freetype/ftoption.h + +which only include the most commonly used modules and options, which is important to +save limited FLASH space. - Copy the FreeType source code to your project directory. - Refer to the following ``Makefile`` for configuration: @@ -60,10 +70,12 @@ FLASH space. FT_CSRCS += freetype/src/truetype/truetype.c CSRCS += $(FT_CSRCS) + + .. _freetype_usage: Usage ------ +***** Enable :c:macro:`LV_USE_FREETYPE` in ``lv_conf.h``. @@ -75,18 +87,20 @@ By default, the FreeType extension doesn't use LVGL's file system. You can simply pass the path to the font as usual on your operating system or platform. -If you want FreeType to use lvgl's memory allocation and file system +If you want FreeType to use LVGL's memory allocation and file system interface, you can enable :c:macro:`LV_FREETYPE_USE_LVGL_PORT` in -``lv_conf.h``, convenient for unified management. +``lv_conf.h``, convenient for unified management. If you do this, you will need +to exclude the configured FreeType library's ``ftsystem.c`` file from being compiled, +since LVGL's ``lv_ftsystem.c`` has custom versions of the functions defined therein. The font style supports *Italic* and **Bold** fonts processed by -software, and can be set with reference to the following values: +software, and can be set by using following values where style values are required: - :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style. - :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style. - :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style. -They can be combined.eg: +These values can be combined, e.g. :cpp:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`. The FreeType extension also supports colored bitmap glyphs such as emojis. Note @@ -97,23 +111,29 @@ Use the :cpp:func:`lv_freetype_font_create` function to create a font. To delete a font, use :cpp:func:`lv_freetype_font_delete`. For more detailed usage, please refer to example code. + + .. _freetype_example: Examples --------- +******** .. include:: ../../examples/libs/freetype/index.rst -Learn more ----------- + + +Learn More +********** - FreeType`tutorial `__ - LVGL's :ref:`add_font` + + .. _freetype_api: API ---- +*** :ref:`ftoption_h` diff --git a/docs/details/other-components/font_manager.rst b/docs/details/other-components/font_manager.rst index 3942bf88b..9d5698c32 100644 --- a/docs/details/other-components/font_manager.rst +++ b/docs/details/other-components/font_manager.rst @@ -4,13 +4,15 @@ Font Manager ============ -Font Manager is a secondary encapsulation based on :ref:`freetype`, which -facilitates upper-level applications to manage and use vector fonts. Currently -supported functions include: +Font Manager is a secondary encapsulation of :ref:`freetype`, which provides +facilities for high-level applications to manage and use vector fonts. Currently +provided font-management functions includes: - Font resource reference counting (reduces repeated creation of font resources). - Font resource concatenation (font fallback). -- Font resource recycling mechanism (buffers recently deleted font resources to reduce the time overhead of repeated creation). +- Font resource recycling mechanism (buffers recently deleted font resources to + reduce the time overhead of repeated creation). + .. _font_manager_usage: @@ -18,22 +20,23 @@ supported functions include: Usage ***** -Enable :c:macro:`LIB_FREETYPE` and `LV_USE_FONT_MANAGER` in ``lv_conf.h``. - -Configure :c:macro:`LV_FONT_MANAGER_NAME_MAX_LEN` to set the maximum length of the font name. +Enable FreeType and Font Manager in ``lv_conf.h`` by setting the +:c:macro:`LV_USE_FREETYPE` and :c:macro:`LV_USE_FONT_MANAGER` macros to non-zero +values, and configure :c:macro:`LV_FONT_MANAGER_NAME_MAX_LEN` to set the maximum +length of the font name. Initialize Font Manager ----------------------- Use :cpp:func:`lv_font_manager_create` to create a font manager, where the :cpp:func:`recycle_cache_size` parameter is used to set the number of font recycling -caches,which can improve font creation efficiency. +caches, which can improve font creation efficiency. Use :cpp:func:`lv_font_manager_add_path_static` to add a mapping between the font file path and the custom font name, so that the application can access the font resources more conveniently. It should be noted that if the file path is not static -(assigned from a local variable), please use :cpp:func:`lv_font_manager_add_path` to -add the path. This API will copy the path content to the internal management. +(assigned from a local variable), use :cpp:func:`lv_font_manager_add_path` to +add the path. This function will make its own copy of the string. Use :cpp:func:`lv_font_manager_remove_path` to remove the font path mapping. @@ -57,7 +60,7 @@ Create Font from Font Manager Use :cpp:func:`lv_font_manager_create_font` to create a font. The parameters are basically the same as :cpp:func:`lv_freetype_font_create`. -The :cpp:func:`font_family` parameter can be filled with the names of multiple fonts +The ``font_family`` parameter can be filled with the names of multiple fonts (separated by ``,``) to achieve font concatenation (when the corresponding glyph is not found in a font file, it will automatically search from the next concatenated font). @@ -81,11 +84,11 @@ font). Delete Font ----------- -Use :cpp:func:`lv_font_manager_delete_font` to delete the font. -The font manager will mark the font resource as a recyclable font so that it can be -quickly created next time. +Use :cpp:func:`lv_font_manager_delete_font` to delete the font when it is no longer needed. +The font manager will mark the font resource as a recyclable font so that it has the +possibility of being more quickly created next time. -Note that you need to delete the widget that references the font first, and then +Note that you need to delete any Widgets that used the font first, and then delete the font to avoid accessing wild pointers. .. code-block:: c @@ -102,7 +105,8 @@ Use :cpp:func:`lv_font_manager_delete` to destroy the entire font manager. It sh be noted that before destruction, it is necessary to ensure that the application has deleted all fonts using :cpp:func:`lv_font_manager_delete_font`. The font manager will check the reference status of all allocated fonts. If there are still fonts -being referenced, the font manager will fail to destroy and return false. +being referenced, the font manager will fail to be destroyed and the function will return false. + .. _font_manager_example: @@ -112,6 +116,8 @@ Example .. include:: ../../examples/others/font_manager/index.rst + + .. _font_manager_api: API