refactor: reorganize the others folder (#9164)

Co-authored-by: André Costa <andre_miguel_costa@hotmail.com>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

docs/src/details/auxiliary-modules/index.rst

@@ -8,16 +8,6 @@ Auxiliary Modules
     :maxdepth: 2
 
     file_explorer
-    font_manager
     fragment
-    gridnav
-    ime_pinyin
-    imgfont
-    monkey
-    obj_id
     obj_property
-    observer/index
-    snapshot
-    sysmon
-    test
     translation

docs/src/details/debugging/index.rst

@@ -9,5 +9,9 @@ Debugging
 
     gdb_plugin
     log
+    monkey
+    obj_id
     profiler
+    sysmon
+    test
     vg_lite_tvg

docs/src/details/libs/font_support/freetype.rst

@@ -122,8 +122,7 @@ please refer to the example code below.
 
 .. admonition::  Further Reading
 
-    - `FreeType tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__
+    `FreeType tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__
-    - LVGL's :ref:`add_font`
 
 Rendering vector fonts is supported with VGLite or ThorVG,
 when using vector fonts with ThorVG, it is possible to set a letter outline of a different color.
@@ -148,7 +147,7 @@ See the :cpp:func:`lv_example_freetype_2_vector_font` function for a usage examp
 Examples
 ********
 
-.. include:: ../../examples/libs/freetype/index.rst
+.. include:: ../../../examples/libs/freetype/index.rst
 
 
 

docs/src/details/libs/font_support/index.rst

@@ -0,0 +1,13 @@
+.. _libs_font_support:
+
+============
+Font Support
+============
+
+
+.. toctree::
+    :maxdepth: 2
+
+    freetype
+    tiny_ttf
+

docs/src/details/libs/font_support/tiny_ttf.rst

@@ -47,7 +47,7 @@ allow kerning, if supported, or disable.
 Example
 *******
 
-.. include:: ../../examples/libs/tiny_ttf/index.rst
+.. include:: ../../../examples/libs/tiny_ttf/index.rst
 
 
 

docs/src/details/libs/fs_support/index.rst

@@ -0,0 +1,16 @@
+.. _libs_fs_support:
+
+===================
+File System Support
+===================
+
+
+.. toctree::
+    :maxdepth: 2
+
+    fs
+    arduino_esp_littlefs
+    arduino_sd
+    frogfs
+    lfs
+

docs/src/details/libs/image_support/bmp.rst

@@ -49,7 +49,7 @@ Limitations
 Example
 *******
 
-.. include:: ../../examples/libs/bmp/index.rst
+.. include:: ../../../examples/libs/bmp/index.rst
 
 
 

docs/src/details/libs/image_support/gif.rst

@@ -90,7 +90,7 @@ ARGB8888 has a pixel size of 4.
 Example
 *******
 
-.. include:: ../../examples/libs/gif/index.rst
+.. include:: ../../../examples/libs/gif/index.rst
 
 
 

docs/src/details/libs/image_support/index.rst

@@ -0,0 +1,19 @@
+.. _libs_image_support:
+
+=============
+Image Support
+=============
+
+
+.. toctree::
+    :maxdepth: 2
+
+    bmp
+    gif
+    libjpeg_turbo
+    libpng
+    lodepng
+    rle
+    rlottie
+    svg
+    tjpgd

docs/src/details/libs/image_support/libjpeg_turbo.rst

@@ -66,7 +66,7 @@ feature to ensure that the memory usage is within a reasonable range.
 Example
 *******
 
-.. include:: ../../examples/libs/libjpeg_turbo/index.rst
+.. include:: ../../../examples/libs/libjpeg_turbo/index.rst
 
 
 

docs/src/details/libs/image_support/libpng.rst

@@ -59,7 +59,7 @@ stored in RGBA pixel format.
 Example
 *******
 
-.. include:: ../../examples/libs/libpng/index.rst
+.. include:: ../../../examples/libs/libpng/index.rst
 
 
 

docs/src/details/libs/image_support/lodepng.rst

@@ -52,7 +52,7 @@ for example Compress PNG: https://compresspng.com/
 Example
 *******
 
-.. include:: ../../examples/libs/lodepng/index.rst
+.. include:: ../../../examples/libs/lodepng/index.rst
 
 
 

docs/src/details/libs/image_support/rle.rst

@@ -22,7 +22,7 @@ compressed to save more than 70% space.  The below statistics are from a watch
 project.  It shows the file count of every compress level. For rare conditions, RLE
 compress may increase the file size if there's no large repetition in data.
 
-.. image:: rle-compress-statistics.png
+.. image:: /_static/images/rle-compress-statistics.png
    :alt: RLE compress statistics from a watch project
    :align: center
 

docs/src/details/libs/image_support/rlottie.rst

@@ -298,7 +298,7 @@ IDF) with the appropriate :cpp:expr:`MALLOC_CAP` call --- for SPIRAM usage this
 Example
 *******
 
-.. include:: ../../examples/libs/rlottie/index.rst
+.. include:: ../../../examples/libs/rlottie/index.rst
 
 
 

docs/src/details/libs/image_support/svg.rst

@@ -1,7 +1,7 @@
 .. _svg:
 
 ===========
-SVG Support
+SVG Decoder
 ===========
 
 The lv_svg extension provides makes it possible to use SVG images in your LVGL UI using the
@@ -22,11 +22,20 @@ If you need support for SVG animation attribute parsing,
 you can set :c:macro:`LV_USE_SVG_ANIMATION` in ``lv_conf.h`` to ``1``.
 
 
+As Image Source
+***************
 
-.. _svg_example:
+`lv_image` directly supports SVG images.  For example:
 
-Example
+.. code-block:: c
-*******
+
+    lv_image_set_src(widget, "S:path/to/example.svg");
+
+
+Direct Rendering
+****************
+
+It is also possible to draw SVG vector graphics in draw events:
 
 .. code:: c
 
@@ -44,12 +53,12 @@ Example
     /* Release the DOM tree */
     lv_svg_node_delete(svg_doc);
 
-`lv_image` also supports SVG images.  For example:
+.. _svg_example:
 
-.. code-block:: c
+Example
-
+*******
-    lv_image_set_src(widget, "S:path/to/example.svg");
 
+.. include:: ../../../examples/libs/svg/index.rst
 
 
 .. _svg_api:

docs/src/details/libs/image_support/tjpgd.rst

@@ -1,8 +1,8 @@
 .. _tjpgd:
 
-================================
+=================
-Tiny JPEG Decompressor (TJpgDec)
+Tiny JPEG Decoder
-================================
+=================
 
 **Tiny JPEG Decompressor** is an LVGL interface to the TJpgDec library --- a generic
 JPEG image decompressor module that highly optimized for small embedded systems.  It
@@ -65,7 +65,7 @@ Converting JPEG to C array
 Example
 *******
 
-.. include:: ../../examples/libs/tjpgd/index.rst
+.. include:: ../../../examples/libs/tjpgd/index.rst
 
 
 

docs/src/details/libs/index.rst

@@ -8,24 +8,11 @@
 .. toctree::
     :maxdepth: 2
 
-    arduino_esp_littlefs
+    font_support/index
-    arduino_sd
+    fs_support/index
+    image_support/index
+    video_support/index
     barcode
-    bmp
-    ffmpeg
-    freetype
-    frogfs
-    fs
-    gif
-    gstreamer
     gltf
-    lfs
-    libjpeg_turbo
-    libpng
-    lodepng
     qrcode
-    rle
+
-    rlottie
-    svg
-    tiny_ttf
-    tjpgd

docs/src/details/libs/video_support/ffmpeg.rst

@@ -90,7 +90,7 @@ Learn more about :ref:`events`.
 Examples
 ********
 
-.. include:: ../../examples/libs/ffmpeg/index.rst
+.. include:: ../../../examples/libs/ffmpeg/index.rst
 
 
 

docs/src/details/libs/video_support/gstreamer.rst

@@ -66,7 +66,7 @@ Requirements
 The GStreamer extension requires **GStreamer 1.0** or later with the following components:
 
 :gstreamer-1.0:        Core GStreamer framework
-:gstreamer-video-1.0:  Video handling and processing utilities  
+:gstreamer-video-1.0:  Video handling and processing utilities
 :gstreamer-app-1.0:    Application integration utilities
 
 Dependencies
@@ -92,18 +92,18 @@ Setup
 .. code-block:: cmake
 
     find_package(PkgConfig REQUIRED)
-    
+
     # Find GStreamer packages
     pkg_check_modules(GSTREAMER REQUIRED gstreamer-1.0)
     pkg_check_modules(GSTREAMER_VIDEO REQUIRED gstreamer-video-1.0)
     pkg_check_modules(GSTREAMER_APP REQUIRED gstreamer-app-1.0)
-    
+
     # Link with LVGL
-    target_include_directories(lvgl PUBLIC 
+    target_include_directories(lvgl PUBLIC
         ${GSTREAMER_INCLUDE_DIRS}
-        ${GSTREAMER_VIDEO_INCLUDE_DIRS} 
+        ${GSTREAMER_VIDEO_INCLUDE_DIRS}
         ${GSTREAMER_APP_INCLUDE_DIRS})
-    target_link_libraries(lvgl PUBLIC 
+    target_link_libraries(lvgl PUBLIC
         ${GSTREAMER_LIBRARIES}
         ${GSTREAMER_VIDEO_LIBRARIES}
         ${GSTREAMER_APP_LIBRARIES})
@@ -126,18 +126,18 @@ Setup
     {
         /* Initialize LVGL */
         lv_init();
-        
+
         /* Setup display driver */
         lv_display_t *display = lv_display_create(800, 480);
         /* ... configure display driver ... */
-        
+
         /* Create and run your GStreamer application */
         lv_example_gstreamer_1();
-        
+
         while (1) {
             lv_timer_handler();
         }
-        
+
         return 0;
     }
 
@@ -153,18 +153,18 @@ Here's how to create a basic GStreamer player and load media:
 
     /* Create a GStreamer object */
     lv_obj_t * streamer = lv_gstreamer_create(lv_screen_active());
-    
+
     /* Set the media source using URI factory */
-    lv_result_t result = lv_gstreamer_set_src(streamer, 
+    lv_result_t result = lv_gstreamer_set_src(streamer,
         LV_GSTREAMER_FACTORY_URI_DECODE,
         LV_GSTREAMER_PROPERTY_URI_DECODE,
         "https://example.com/video.webm");
-    
+
     if (result != LV_RESULT_OK) {
         LV_LOG_ERROR("Failed to set GStreamer source");
         return;
     }
-    
+
     /* Start playback */
     lv_gstreamer_play(streamer);
 
@@ -178,15 +178,15 @@ The GStreamer widget supports various media sources through different factories:
 .. code-block:: c
 
     /* Load from web URL */
-    lv_gstreamer_set_src(streamer, LV_GSTREAMER_FACTORY_URI_DECODE, 
+    lv_gstreamer_set_src(streamer, LV_GSTREAMER_FACTORY_URI_DECODE,
                          LV_GSTREAMER_PROPERTY_URI_DECODE,
                          "https://example.com/stream.webm");
-    
+
     /* Load from local file */
     lv_gstreamer_set_src(streamer, LV_GSTREAMER_FACTORY_URI_DECODE,
-                         LV_GSTREAMER_PROPERTY_URI_DECODE, 
+                         LV_GSTREAMER_PROPERTY_URI_DECODE,
                          "file:///path/to/video.mp4");
-    
+
     /* RTSP stream */
     lv_gstreamer_set_src(streamer, LV_GSTREAMER_FACTORY_URI_DECODE,
                          LV_GSTREAMER_PROPERTY_URI_DECODE,
@@ -213,17 +213,17 @@ Control media playback with these functions:
     lv_gstreamer_play(streamer);
     lv_gstreamer_pause(streamer);
     lv_gstreamer_stop(streamer);
-    
+
     /* Get current state */
     lv_gstreamer_state_t state = lv_gstreamer_get_state(streamer);
-    
+
     /* Seek to position (in milliseconds) */
     lv_gstreamer_set_position(streamer, 30000);  /* Seek to 30 seconds */
-    
+
     /* Get current position and duration */
     uint32_t position = lv_gstreamer_get_position(streamer);
     uint32_t duration = lv_gstreamer_get_duration(streamer);
-    
+
     /* Set playback rate - values relative to 256 (1x speed) */
     lv_gstreamer_set_rate(streamer, 128);   /* 0.5x speed */
     lv_gstreamer_set_rate(streamer, 256);   /* 1.0x speed (normal) */
@@ -238,7 +238,7 @@ Manage audio volume with built-in controls:
 
     /* Set volume (0-100%) */
     lv_gstreamer_set_volume(streamer, 75);
-    
+
     /* Get current volume */
     uint8_t volume = lv_gstreamer_get_volume(streamer);
 
@@ -253,16 +253,16 @@ Handle GStreamer events using LVGL's event system:
     {
         lv_event_code_t code = lv_event_get_code(e);
         lv_obj_t * streamer = lv_event_get_target_obj(e);
-        
+
         if(code == LV_EVENT_READY) {
-                LV_LOG_USER("Stream ready - Duration: %" LV_PRIu32 " ms", 
+                LV_LOG_USER("Stream ready - Duration: %" LV_PRIu32 " ms",
                            lv_gstreamer_get_duration(streamer));
                 LV_LOG_USER("Resolution: %" LV_PRId32 "x%" LV_PRId32,
                            lv_image_get_src_width(streamer),
                            lv_image_get_src_height(streamer));
         }
     }
-    
+
     /* Add event callback */
     lv_obj_add_event_cb(streamer, gstreamer_event_cb, LV_EVENT_ALL, NULL);
 
@@ -291,7 +291,7 @@ Media Information Access
 Once media is loaded (LV_EVENT_READY), you can access:
 
 - Video resolution via ``lv_image_get_src_width()`` and ``lv_image_get_src_height()``
-- Media duration via ``lv_gstreamer_get_duration()``  
+- Media duration via ``lv_gstreamer_get_duration()``
 - Current playback position via ``lv_gstreamer_get_position()``
 - Current volume level via ``lv_gstreamer_get_volume()``
 - Current playback state via ``lv_gstreamer_get_state()``
@@ -301,7 +301,7 @@ Once media is loaded (LV_EVENT_READY), you can access:
 Examples
 ********
 
-.. include:: ../../examples/libs/gstreamer/index.rst
+.. include:: ../../../examples/libs/gstreamer/index.rst
 
 .. _gstreamer_api:
 

docs/src/details/libs/video_support/index.rst

@@ -0,0 +1,11 @@
+.. _libs_video_support:
+
+=============
+Video Support
+=============
+
+.. toctree::
+    :maxdepth: 2
+
+    ffmpeg
+    gstreamer

docs/src/details/main-modules/draw/index.rst

@@ -11,3 +11,4 @@ Drawing
     draw_api
     draw_layers
     draw_descriptors
+    snapshot

docs/src/details/main-modules/draw/snapshot.rst

@@ -84,7 +84,7 @@ is large enough, and if it fails, destroy the existing draw buffer and call
 Example
 *******
 
-.. include:: ../../examples/others/snapshot/index.rst
+.. include:: ../../../examples/others/snapshot/index.rst
 
 
 

docs/src/details/main-modules/fonts/bdf_fonts.rst

@@ -0,0 +1,88 @@
+
+.. _bdf_font:
+
+========
+BDF Font
+========
+
+Overview
+********
+
+Small displays with low resolution don't look pretty with automatically rendered fonts. A bitmap font provides
+the solution, but it's necessary to convert the bitmap font (BDF) to a TTF.
+
+Convert BDF to TTF
+******************
+
+BDF are bitmap fonts where fonts are not described in outlines but in pixels. BDF files can be used but
+they must be converted into the TTF format using ``mkttf``, which can be found
+in this GitHub repository:  https://github.com/Tblue/mkttf .  This tool uses potrace to generate outlines from
+the bitmap information. The bitmap itself will be embedded into the TTF as well. `lv_font_conv <https://github.com/lvgl/lv_font_conv/>`__ uses
+the embedded bitmap but it also needs the outlines. One might think you can use a fake MS Bitmap
+only sfnt (ttf) (TTF without outlines) created by fontforge, but this will not work.
+
+Install imagemagick, python3, python3-fontforge and potrace
+
+On Ubuntu Systems, just type
+
+.. code:: bash
+
+    sudo apt install imagemagick python3-fontforge potrace
+
+Clone mkttf
+
+.. code:: bash
+
+    git clone https://github.com/Tblue/mkttf
+
+Read the mkttf docs.
+
+Former versions of imagemagick needs the imagemagick call in front of convert, identify and so on.
+But newer versions don't. So you might want to change 2 lines in ``potrace-wrapper.sh`` ---
+open ``potrace-wrapper.sh`` and remove imagemagick from line 55 and line 64:
+
+line 55
+
+.. code:: bash
+
+    wh=($(identify -format '%[width]pt %[height]pt' "${input?}"))
+
+line 64
+
+.. code:: bash
+
+    convert "${input?}" -sample '1000%' - \
+
+It might be necessary to change the mkttf.py script.
+
+line 1
+
+.. code:: bash
+
+    #!/usr/bin/env python3
+
+Example
+*******
+
+.. code-block:: console
+
+    cd mkttf
+    ./mkttf.py ./TerminusMedium-12-12.bdf
+    Importing bitmaps from 0 additional fonts...
+    Importing font `./TerminusMedium-12-12.bdf' into glyph background...
+    Processing glyphs...
+    Saving TTF file...
+    Saving SFD file...
+    Done!
+
+The TTF ``TerminusMedium-001.000.ttf`` will be created from ``./TerminusMedium-12-12.bdf``.
+
+To create a font for LVGL:
+
+.. code:: bash
+
+    lv_font_conv --bpp 1 --size 12 --no-compress --font TerminusMedium-001.000.ttf --range 0x20-0x7e,0xa1-0xff --format lvgl -o terminus_1bpp_12px.c
+
+:note: use 1-bpp because we don't use anti-aliasing. It doesn't look sharp on displays with a low resolution.
+
+

docs/src/details/main-modules/fonts/binfont_loader.rst

@@ -0,0 +1,65 @@
+
+.. _binfont_loader:
+
+==============
+BinFont Loader
+==============
+
+Overview
+********
+
+:cpp:func:`lv_binfont_create` can be used to load a font from a file. The font needs
+to have a special binary format. (Not TTF or WOFF). Use
+`lv_font_conv <https://github.com/lvgl/lv_font_conv/>`__ with the
+``--format bin`` option to generate an LVGL compatible font file.
+
+Loading from File
+*****************
+
+:note: To load a font :ref:`LVGL's filesystem <file_system>`
+       needs to be enabled and a driver must be added.
+
+Example
+
+.. code-block:: c
+
+   lv_font_t *my_font = lv_binfont_create("X:/path/to/my_font.bin");
+   if(my_font == NULL) return;
+
+   /* Use the font */
+
+   /* Free the font if not required anymore */
+   lv_binfont_destroy(my_font);
+
+
+
+Loading from Memory
+*******************
+
+:cpp:func:`lv_binfont_create_from_buffer` can be used to load a font from a memory buffer.
+This function may be useful to load a font from an external file system, which is not
+supported by LVGL. The font needs to be in the same format as if it were loaded from a file.
+
+:note: To load a font from a buffer :ref:`LVGL's filesystem <file_system>`
+       needs to be enabled and the MEMFS driver must be added.
+
+Example
+
+.. code-block:: c
+
+   lv_font_t *my_font;
+   uint8_t *buf;
+   uint32_t bufsize;
+
+   /* Read font file into the buffer from the external file system */
+   ...
+
+   /* Load font from the buffer */
+   my_font = lv_binfont_create_from_buffer((void *)buf, buf));
+   if(my_font == NULL) return;
+   /* Use the font */
+
+   /* Free the font if not required anymore */
+   lv_binfont_destroy(my_font);
+
+

docs/src/details/main-modules/fonts/built_in_fonts.rst

@@ -0,0 +1,114 @@
+.. _built_in_fonts:
+
+==============
+Built-In Fonts
+==============
+
+Overview
+********
+
+There are several built-in fonts in different sizes, which can be
+enabled in ``lv_conf.h`` with *LV_FONT_...* defines.
+
+
+The built-in fonts are **global variables** with names like
+:cpp:var:`lv_font_montserrat_16` for a 16 px height font. To use them in a
+style, just add a pointer to a font variable like this:
+
+.. code-block:: c
+
+    lv_style_set_text_font(&my_style, &lv_font_montserrat_28);
+
+
+The built-in fonts with ``bpp = 4`` contain the ASCII characters and use
+the `Montserrat <https://fonts.google.com/specimen/Montserrat>`__ font.
+
+In addition to the ASCII range all the :ref:`predefined symbols <font_symbols>` are
+added to the built-in fonts from the
+`FontAwesome <https://fontawesome.com/>`__ font.
+
+
+Normal Fonts
+************
+
+The following fonts contain all ASCII characters, the degree symbol (U+00B0), the
+bullet symbol (U+2022) and the built-in symbols (see below).
+
+- :c:macro:`LV_FONT_MONTSERRAT_12`: 12 px font
+- :c:macro:`LV_FONT_MONTSERRAT_14`: 14 px font
+- :c:macro:`LV_FONT_MONTSERRAT_16`: 16 px font
+- :c:macro:`LV_FONT_MONTSERRAT_18`: 18 px font
+- :c:macro:`LV_FONT_MONTSERRAT_20`: 20 px font
+- :c:macro:`LV_FONT_MONTSERRAT_22`: 22 px font
+- :c:macro:`LV_FONT_MONTSERRAT_24`: 24 px font
+- :c:macro:`LV_FONT_MONTSERRAT_26`: 26 px font
+- :c:macro:`LV_FONT_MONTSERRAT_28`: 28 px font
+- :c:macro:`LV_FONT_MONTSERRAT_30`: 30 px font
+- :c:macro:`LV_FONT_MONTSERRAT_32`: 32 px font
+- :c:macro:`LV_FONT_MONTSERRAT_34`: 34 px font
+- :c:macro:`LV_FONT_MONTSERRAT_36`: 36 px font
+- :c:macro:`LV_FONT_MONTSERRAT_38`: 38 px font
+- :c:macro:`LV_FONT_MONTSERRAT_40`: 40 px font
+- :c:macro:`LV_FONT_MONTSERRAT_42`: 42 px font
+- :c:macro:`LV_FONT_MONTSERRAT_44`: 44 px font
+- :c:macro:`LV_FONT_MONTSERRAT_46`: 46 px font
+- :c:macro:`LV_FONT_MONTSERRAT_48`: 48 px font
+
+Special Fonts
+*************
+
+-  :c:macro:`LV_FONT_MONTSERRAT_28_COMPRESSED`: Same as normal 28 px font but stored as a :ref:`fonts_compressed` with 3 bpp
+-  :c:macro:`LV_FONT_DEJAVU_16_PERSIAN_HEBREW`: 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms
+-  :c:macro:`LV_FONT_SOURCE_HAN_SANS_SC_16_CJK`: 16 px font with normal range plus 1000 of the most common CJK radicals
+-  :c:macro:`LV_FONT_UNSCII_8`: 8 px pixel perfect font with only ASCII characters
+-  :c:macro:`LV_FONT_UNSCII_16`: 16 px pixel perfect font with only ASCII characters
+
+
+.. _add_new_builtin_font:
+
+Adding a New Font
+*****************
+
+There are several ways to add a new font to your project:
+
+1. The simplest method is to use the `Online font converter <https://lvgl.io/tools/fontconverter>`__.
+   Just set the parameters, click the *Convert* button, copy the font to your project
+   and use it. **Be sure to carefully read the steps provided on that site
+   or you will get an error while converting.**
+2. Use the `Offline font converter <https://github.com/lvgl/lv_font_conv>`__.
+   (Requires Node.js to be installed)
+3. If you want to create something like the built-in
+   fonts (Montserrat font and symbols) but in a different size and/or
+   ranges, you can use the ``built_in_font_gen.py`` script in
+   ``lvgl/scripts/built_in_font`` folder. (This requires Python and
+   https://github.com/lvgl/lv_font_conv/ to be installed.)
+
+To declare a font in a file, use :cpp:expr:`LV_FONT_DECLARE(my_font_name)`.
+
+To make fonts globally available (like the built-in fonts), add them to
+:c:macro:`LV_FONT_CUSTOM_DECLARE` in ``lv_conf.h``.
+
+
+.. _fonts_compressed:
+
+Compressed Fonts
+****************
+
+The built-in font engine supports compressed bitmaps.
+Compressed fonts can be generated by
+
+- ticking the ``Compressed`` check box in the online converter
+- not passing the ``--no-compress`` flag to the offline converter (compression is applied by default)
+
+Compression is more effective with larger fonts and higher bpp. However,
+it's about 30% slower to render compressed fonts. Therefore, it is
+recommended to compress only the largest fonts of a user interface,
+because
+
+- they need the most memory
+- they can be compressed better
+- and on the likelihood that they are used less frequently than the medium-sized
+  fonts, the performance cost will be smaller.
+
+Compressed fonts also support ``bpp=3``.
+

docs/src/details/main-modules/fonts/font_manager.rst

@@ -127,7 +127,7 @@ being referenced, the font manager will fail to be destroyed and the function wi
 Example
 *******
 
-.. include:: ../../examples/others/font_manager/index.rst
+.. include:: ../../../examples/others/font_manager/index.rst
 
 
 

docs/src/details/main-modules/fonts/imgfont.rst

@@ -43,7 +43,7 @@ To destroy the *imgfont* that is no longer used, use :cpp:expr:`lv_imgfont_destr
 Example
 *******
 
-.. include:: ../../examples/others/imgfont/index.rst
+.. include:: ../../../examples/others/imgfont/index.rst
 
 
 

docs/src/details/main-modules/fonts/index.rst

@@ -0,0 +1,20 @@
+.. _fonts:
+
+===============
+Fonts (lv_font)
+===============
+
+.. toctree::
+    :maxdepth: 2
+
+    overview
+    built_in_fonts
+    binfont_loader
+    ../../libs/font_support/tiny_ttf
+    ../../libs/font_support/freetype
+    imgfont
+    bdf_fonts
+    rtl
+    new_font_engine
+    font_manager
+

docs/src/details/main-modules/fonts/new_font_engine.rst

@@ -0,0 +1,88 @@
+
+.. _new_font_engine:
+
+========================
+Adding a New Font Engine
+========================
+
+Overview
+********
+
+Fonts have a **format** property. It describes how the glyph data is stored.
+At the time of writing, there are several possible values that this field can take, and those
+values fall into 2 categories:
+
+1. **Bitmap based**: 1, 2, 4 or 8-bpp and image format, and
+2. **Vector based** vector, SVG; for the latter, the user provides the rendering logic.
+
+For simple formats:
+
+- the font is stored as an array of bitmaps, one bitmap per glyph;
+- the value stored for each pixel determines the pixel's opacity, enabling edges
+  to be smoother --- higher bpp values result in smoother edges.
+
+For advanced formats, the font information is stored in its respective format.
+
+The **format** property also affects the amount of memory needed to store a
+font. For example, ``format = LV_FONT_GLYPH_FORMAT_A4`` makes a font nearly four
+times larger compared to ``format = LV_FONT_GLYPH_FORMAT_A1``.
+
+Example
+*******
+
+LVGL's font interface is designed to be very flexible but, even so, you
+can add your own font engine in place of LVGL's internal one. For
+example, you can use `FreeType <https://www.freetype.org/>`__ to
+real-time render glyphs from TTF fonts or use an external flash to store
+the font's bitmap and read them when the library needs them. FreeType can be used in LVGL as described in :ref:`Freetype <freetype>`.
+
+To add a new font engine, a custom :cpp:type:`lv_font_t` variable needs to be created:
+
+.. code-block:: c
+
+   /* Describe the properties of a font */
+   lv_font_t my_font;
+   my_font.get_glyph_dsc = my_get_glyph_dsc_cb;        /* Set a callback to get info about glyphs */
+   my_font.get_glyph_bitmap = my_get_glyph_bitmap_cb;  /* Set a callback to get bitmap of a glyph */
+   my_font.line_height = height;                       /* The real line height where any text fits */
+   my_font.base_line = base_line;                      /* Base line measured from the top of line_height */
+   my_font.dsc = something_required;                   /* Store any implementation specific data here */
+   my_font.user_data = user_data;                      /* Optionally some extra user data */
+
+   ...
+
+   /* Get info about glyph of `unicode_letter` in `font` font.
+    * Store the result in `dsc_out`.
+    * The next letter (`unicode_letter_next`) might be used to calculate the width required by this glyph (kerning)
+    */
+   bool my_get_glyph_dsc_cb(const lv_font_t * font, lv_font_glyph_dsc_t * dsc_out, uint32_t unicode_letter, uint32_t unicode_letter_next)
+   {
+       /* Your code here */
+
+       /* Store the result.
+        * For example ...
+        */
+       dsc_out->adv_w = 12;        /* Horizontal space required by the glyph in [px] */
+       dsc_out->box_h = 8;         /* Height of the bitmap in [px] */
+       dsc_out->box_w = 6;         /* Width of the bitmap in [px] */
+       dsc_out->ofs_x = 0;         /* X offset of the bitmap in [px] */
+       dsc_out->ofs_y = 3;         /* Y offset of the bitmap measured from the as line */
+       dsc_out->format= LV_FONT_GLYPH_FORMAT_A2;
+
+       return true;                /* true: glyph found; false: glyph was not found */
+   }
+
+
+   /* Get the bitmap of `unicode_letter` from `font`. */
+   const uint8_t * my_get_glyph_bitmap_cb(const lv_font_t * font, uint32_t unicode_letter)
+   {
+       /* Your code here */
+
+       /* The bitmap should be a continuous bitstream where
+        * each pixel is represented by `bpp` bits */
+
+       return bitmap;    /* Or NULL if not found */
+   }
+
+
+

docs/src/details/main-modules/fonts/overview.rst

@@ -0,0 +1,188 @@
+.. |check|  unicode:: U+02713 .. CHECK MARK
+.. |Aacute| unicode:: U+000C1 .. LATIN CAPITAL LETTER A WITH ACUTE
+.. |eacute| unicode:: U+000E9 .. LATIN SMALL LETTER E WITH ACUTE
+.. |otilde| unicode:: U+000F5 .. LATIN SMALL LETTER O WITH TILDE
+.. |Utilde| unicode:: U+00168 .. LATIN CAPITAL LETTER U WITH TILDE
+.. |uuml|   unicode:: U+000FC .. LATIN SMALL LETTER U WITH DIAERESIS
+.. |uml|    unicode:: U+000A8 .. DIAERESIS
+
+.. _font:
+
+========
+Overview
+========
+
+What is a Font?
+***************
+
+In LVGL fonts are collections of bitmaps and other information required
+to render the images of the individual letters (glyphs). A font is stored in a
+:cpp:type:`lv_font_t` variable and can be set in a style's *text_font* field.
+For example:
+
+.. code-block:: c
+
+    lv_style_set_text_font(&my_style, &lv_font_montserrat_28);  /* Set a larger font */
+
+Font Engines
+************
+
+A font engine is some C code that allows LVGL to extract various information
+from the fonts, such as character (glyph) information or bitmap.
+
+LVGL's built-in font engine is suitable for most typical cases.
+It can handle various bit-per-pixel settings (1, 2, 3, 4, 8) in bitmaps,
+kerning, having only selected character ranges from multiple fonts,
+compressing bitmaps, and several others.
+
+The built-in font engine is also the easiest to use:
+
+1. Go to https://lvgl.io/tools/fontconverter
+2. Upload font(s) and set the ranges and/or specify a list of characters to include and other parameters
+3. Click the "Submit" button and copy the generated file to your project
+4. In a C file add :cpp:expr:`LV_FONT_DECLARE(font_name)` to declare the font
+5. Use the font like ``lv_style_set_text_font(&my_style, &font_name);``
+   or ``lv_obj_set_style_text_font(label1, &font_name, 0);``
+
+LVGL also supports several other font engines:
+
+- ``fmt_txt``: This is the built-in font engine that stores the fonts as a C array
+- ``binfont``: Similar to the built-in format, but the font is stored as a file, so it can be loaded at runtime too
+- ``tiny_ttf``: Small vector graphics engine to load TTF files at runtime at any size
+- ``freetype``: Well known font rendering library load and render TTF fonts at runtime. Also supports letter strokes.
+
+Unicode Support
+***************
+
+LVGL supports **UTF-8** encoded Unicode characters. Your editor needs to
+be configured to save your code/text as UTF-8 (usually this is the default)
+and be sure that :c:macro:`LV_TXT_ENC` is set to :c:macro:`LV_TXT_ENC_UTF8` in
+``lv_conf.h``. (This is the default value.)
+
+To test it try
+
+.. code-block:: c
+
+   lv_obj_t * label1 = lv_label_create(lv_screen_active(), NULL);
+   lv_label_set_text(label1, LV_SYMBOL_OK);
+
+If all works well, a '\ |check|\ ' character should be displayed.
+
+
+Typesetting
+***********
+
+Although LVGL can decode and display any Unicode characters
+(assuming the font supports them), LVGL cannot correctly render
+all complex languages.
+
+The standard Latin-based languages (e.g., English, Spanish, German)
+and East Asian languages such as Chinese, Japanese, and Korean (CJK)
+are relatively straightforward, as their characters are simply
+written from left to right.
+
+Languages like Arabic, Persian, and Hebrew, which use Right-to-Left
+(RTL) or mixed writing directions, are also supported in LVGL.
+Learn more :ref:`here <bidi>`.
+
+For characters such as '|eacute|', '|uuml|', '|otilde|', '|Aacute|', and '|Utilde|',
+it is recommended to use the single Unicode format (NFC) rather than decomposing them
+into a base letter and diacritics (e.g. ``u`` + |uml|).
+
+Complex languages where subsequent characters combine into a single glyph
+and where the resulting glyph has no individual Unicode representation
+(e.g., Devanagari), have limited support in LVGL.
+
+
+Kerning
+*******
+
+Fonts usually provide kerning information to adjust the spacing between specific
+characters.
+
+- The `Online converter <https://lvgl.io/tools/fontconverter>`__ generates kerning tables.
+- The `Offline converter <https://github.com/lvgl/lv_font_conv/>`__ generates kerning tables unless ``--no-kerning`` is
+  specified.
+- FreeType integration does not currently support kerning.
+- The Tiny TTF font engine supports GPOS (Glyph Positioning) and Kern tables.
+
+To configure kerning at runtime, use :cpp:func:`lv_font_set_kerning`.
+
+
+Using Font Fallback
+*******************
+
+If the font in use does not have a glyph needed in a text-rendering task, you can
+specify a ``fallback`` font to be used in :cpp:type:`lv_font_t`.
+
+``fallback`` can be chained, so it will try to solve until there is no ``fallback`` set.
+
+.. code-block:: c
+
+   /* Roboto font doesn't have support for CJK glyphs */
+   lv_font_t *roboto = my_font_load_function();
+   /* Droid Sans Fallback has more glyphs but its typeface doesn't look good as Roboto */
+   lv_font_t *droid_sans_fallback = my_font_load_function();
+   /* So now we can display Roboto for supported characters while having wider characters set support */
+   roboto->fallback = droid_sans_fallback;
+
+
+.. _font_symbols:
+
+Symbols
+*******
+
+LVGL supports some predefined "symbols". A symbol is a specific Unicode character
+in a font with an icon-like image. The symbols have names like ``LV_SYMBOL_OK``,
+``LV_SYMBOL_HOME``, etc. See the full list of predefined symbols below:
+
+.. image:: /_static/images/symbols.png
+
+The symbols in the :ref:`built-in fonts <built_in_fonts>` are created from
+the `FontAwesome <https://fontawesome.com/>`__ font.
+
+Using these symbols is very simple:
+
+
+.. code-block:: c
+
+    lv_label_set_text(label, LV_SYMBOL_OK); /*Just a symbol*/
+    lv_label_set_text(label, LV_SYMBOL_OK "Apply"); /*Concatenate with a string*/
+
+
+To add a new symbol in a custom font:
+
+1. Search for a symbol on https://fontawesome.com. For example the
+   `USB symbol <https://fontawesome.com/icons/usb?style=brands>`__. Copy its
+   Unicode ID which is ``0xf287``.
+2. Open the `Online font converter <https://lvgl.io/tools/fontconverter>`__.
+   Add `FontAwesome.woff <https://lvgl.io/assets/others/FontAwesome5-Solid+Brands+Regular.woff>`__.
+3. Set the parameters such as Name, Size, BPP. You'll use this name to
+   declare and use the font in your code.
+4. Add the Unicode ID of the symbol to the range field. E.g. ``0xf287``
+   for the USB symbol. More symbols can be enumerated with ``,``.
+5. Convert the font and copy the generated source code to your project.
+   Make sure to compile the ``.c`` file of your font.
+6. Declare the font using :cpp:expr:`LV_FONT_DECLARE(my_font_name)`.
+
+**Using the symbol**
+
+1. Convert the Unicode value to UTF8, for example on
+   `this site <http://www.ltg.ed.ac.uk/~richard/utf-8.cgi?input=f287&mode=hex>`__.
+   For ``0xf287`` the *Hex UTF-8 bytes* are ``EF 8A 87``.
+2. Create a ``#define`` string from the UTF8 values: ``#define MY_USB_SYMBOL "\xEF\x8A\x87"``
+3. Create a label and set the text. Eg. :cpp:expr:`lv_label_set_text(label, MY_USB_SYMBOL)`
+
+:note: :cpp:expr:`lv_label_set_text(label, MY_USB_SYMBOL)` searches for this symbol
+       in the font defined in the style's ``text.font`` property. To use the symbol
+       you will need to set the style's text font to use the generated font, e.g.
+       :cpp:expr:`lv_style_set_text_font(&my_style, &my_font_name)` or
+       :cpp:expr:`lv_obj_set_style_text_font(label, &my_font_name, 0)`.
+
+Of course any other fonts can be used, just make sure that they define the
+symbols you need.
+
+.. _fonts_api:
+
+API
+***

docs/src/details/main-modules/fonts/rtl.rst

@@ -0,0 +1,73 @@
+
+
+.. _bidi:
+
+
+=====================
+Bidirectional Support
+=====================
+
+
+Overview
+********
+
+Most languages use a Left-to-Right (LTR for short) writing direction,
+however some languages (such as Hebrew, Persian or Arabic) use
+Right-to-Left (RTL for short) direction.
+
+LVGL not only supports RTL text but supports mixed (a.k.a.
+bidirectional, BiDi) text rendering as well. Some examples:
+
+.. image:: /_static/images/bidi.png
+
+BiDi support is enabled by setting :c:macro:`LV_USE_BIDI` to a non-zero value in ``lv_conf.h``.
+
+All text has a base direction (LTR or RTL) which determines some
+rendering rules and the default alignment of the text (left or right).
+However, in LVGL, the base direction is not only applied to labels. It's
+a general property which can be set for every Widget. If not set then it
+will be inherited from the parent. This means it's enough to set the
+base direction of a screen and its child Widgets will inherit it.
+
+The default base direction for screens can be set by
+:c:macro:`LV_BIDI_BASE_DIR_DEF` in ``lv_conf.h`` and other Widgets inherit the
+base direction from their parent.
+
+To set a Widget's base direction use :cpp:expr:`lv_obj_set_style_base_dir(widget, base_dir, selector)`.
+The possible base directions are:
+
+- :cpp:enumerator:`LV_BASE_DIR_LTR`: Left to Right base direction
+- :cpp:enumerator:`LV_BASE_DIR_RTL`: Right to Left base direction
+- :cpp:enumerator:`LV_BASE_DIR_AUTO`: Auto detect base direction
+
+This list summarizes the effect of RTL base direction on Widgets:
+
+- Create Widgets by default on the right
+- ``lv_tabview``: Displays tabs from right to left
+- ``lv_checkbox``: Shows the box on the right
+- ``lv_buttonmatrix``: Orders buttons from right to left
+- ``lv_list``: Shows icons on the right
+- ``lv_dropdown``: Aligns options to the right
+- The text strings in ``lv_table``, ``lv_buttonmatrix``, ``lv_keyboard``, ``lv_tabview``,
+  ``lv_dropdown``, ``lv_roller`` are "BiDi processed" to be displayed correctly
+
+Arabic and Persian support
+**************************
+
+There are some special rules to display Arabic and Persian characters:
+the *form* of a character depends on its position in the text. A
+different form of the same letter needs to be used when it is isolated,
+at start, middle or end positions. Besides these, some conjunction rules
+should also be taken into account.
+
+LVGL supports these rules if :c:macro:`LV_USE_ARABIC_PERSIAN_CHARS` is enabled
+in ``lv_conf.h``.
+
+However, there are some limitations:
+
+- Only displaying text is supported (e.g. on labels), i.e. text inputs (e.g. Text
+  Area) do not support this feature.
+- Static text (i.e. const) is not processed. E.g. text set by :cpp:func:`lv_label_set_text`
+  will be "Arabic processed" but :cpp:func:`lv_label_set_text_static` will not.
+- Text get functions (e.g. :cpp:func:`lv_label_get_text`) will return the processed text.
+

docs/src/details/main-modules/indev/gridnav.rst

@@ -4,6 +4,10 @@
 Grid navigation
 ===============
 
+
+Overview
+********
+
 Grid navigation (gridnav for short) is a feature that moves focus among a set
 of child Widgets via arrow-key presses.
 
@@ -82,7 +86,7 @@ hidden (:cpp:enumerator:`LV_OBJ_FLAG_HIDDEN`) to receive focus via gridnav.
 Examples
 ********
 
-.. include:: ../../examples/others/gridnav/index.rst
+.. include:: ../../../examples/others/gridnav/index.rst
 
 
 

docs/src/details/main-modules/indev/index.rst

@@ -14,3 +14,4 @@ Input devices (lv_indev)
     button
     groups
     gestures
+    gridnav

docs/src/details/main-modules/index.rst

@@ -9,10 +9,11 @@ Main Modules
 
     display/index
     indev/index
-    color
+    fonts/index
-    font
     image
+    color
     timer
     animation
     fs
+    observer/index
     draw/index

docs/src/details/widgets/image.rst

@@ -35,7 +35,7 @@ To provide maximum flexibility, the source of the image can be:
 
 - a variable in code (a C array containing the pixels).
 - a file stored externally (e.g. on an SD card).
-- a :ref:`Symbol <fonts_symbols>` as text.
+- a :ref:`Symbol <font_symbols>` as text.
 
 To set the source of an image, use :cpp:expr:`lv_image_set_src(img, src)`.