From 0c1658259b8be37239e535202cc69f43f7eafd46 Mon Sep 17 00:00:00 2001 From: Landon Rohatensky Date: Tue, 12 Mar 2024 16:07:44 -0700 Subject: [PATCH] add docs for load font from url (#3261) --- components/display/fonts.rst | 37 +++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/components/display/fonts.rst b/components/display/fonts.rst index 0a1ed8574..47ab89461 100644 --- a/components/display/fonts.rst +++ b/components/display/fonts.rst @@ -7,11 +7,14 @@ Font Renderer Component :description: Instructions for setting up fonts in ESPHome. :image: format-font.svg -ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts. +ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts. These fonts can be used in ESPHome's :ref:`own rendering engine `. -To use fonts you first have to define a font object in your ESPHome configuration file. Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file. +To use fonts you can either + - Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file. + - Use the ``gfonts://`` short form to use Google Fonts directly. + - Load a font from a URL directly on build. Next, create a ``font:`` section in your configuration: @@ -68,6 +71,15 @@ Next, create a ``font:`` section in your configuration: "\U000F05D4", # mdi-airplane-landing ] + - file: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf" + id: web_font + size: 20 + - file: + url: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf" + type: web + id: web_font2 + size: 24 + display: # ... @@ -77,7 +89,7 @@ Configuration variables: - **file** (**Required**, string): The path (relative to where the .yaml file is) of the font file. You can also use the ``gfonts://`` short form to use Google Fonts, or use the below structure: - - **type** (**Required**, string): Can be ``local`` or ``gfonts``. + - **type** (**Required**, string): Can be ``local``, ``gfonts`` or ``web``. **Local Fonts**: @@ -101,6 +113,10 @@ Configuration variables: - **extra-bold**: 800 - **black**: 900 + **Web Fonts**: + + - **url** (**Required**, string): The URL of the TrueType or bitmap font file. + - **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the font later in your display code. - **size** (*Optional*, int): The size of the font in pt (not pixel!). @@ -117,14 +133,14 @@ Configuration variables: .. note:: - OpenType/TrueType font files offer icons at codepoints far from what's reachable on a standard keyboard, for these it's needed - to specify the unicode codepoint of the glyph as a hex address escaped with ``\u`` or ``\U``. - - - Code points up to ``0xFFFF`` are encoded like ``\uE6E8``. Lowercase ``\u`` and exactly 4 hexadecimal digits. + OpenType/TrueType font files offer icons at codepoints far from what's reachable on a standard keyboard, for these it's needed + to specify the unicode codepoint of the glyph as a hex address escaped with ``\u`` or ``\U``. + + - Code points up to ``0xFFFF`` are encoded like ``\uE6E8``. Lowercase ``\u`` and exactly 4 hexadecimal digits. - Code points above ``0xFFFF`` are encoded like ``\U0001F5E9``. Capital ``\U`` and exactly 8 hexadecimal digits. - - The ``extras`` section only supports OpenType/TrueType files, ``size`` and ``bpp`` will be the same as the above level. This will allow printing icons alongside the characters in the same string, like ``I \uF004 You \uF001``. - + + The ``extras`` section only supports OpenType/TrueType files, ``size`` and ``bpp`` will be the same as the above level. This will allow printing icons alongside the characters in the same string, like ``I \uF004 You \uF001``. + Many font sizes with multiple glyphs at high bit depths will increase the binary size considerably. Make your choices carefully. @@ -142,4 +158,3 @@ See Also - `MDI cheatsheet `_ - `MDI font repository `_ - :ghedit:`Edit` -