Czcionki

Czcionki w Lopaka są zależne od platformy. Każda docelowa biblioteka ma własny format czcionki i własny zestaw wbudowanych czcionek — nie możesz swobodnie łączyć czcionek między platformami. Ta strona wyjaśnia, jakich formatów czcionek używa każda platforma, jak wybierać i importować czcionki w edytorze oraz co dzieje się z wybraną czcionką po wygenerowaniu kodu.

Formaty czcionek

Lopaka wewnętrznie pracuje z trzema formatami czcionek:

Format	Opis	Używany przez
BDF	Bitmap Distribution Format — standard czcionek bitmapowych w postaci zwykłego tekstu	U8g2, CircuitPython
GFX	Adafruit GFX — nagłówek C (.h) zawierający tablicę bitmap i tabelę glifów	TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2
TTF / OTF / WOFF	Czcionki wektorowe TrueType i OpenType	LVGL, ESPHome

Niektóre platformy (Flipper Zero, MicroPython) nie używają żadnego z tych formatów — ich czcionki są stałe i skompilowane w samej bibliotece. Omówiono je w sekcjach platform poniżej.

Gdy przesyłasz własną czcionkę, Lopaka konwertuje ją do formatu, którego potrzebuje aktywna platforma — nigdy nie musisz zajmować się konwersją ręcznie (z kilkoma wyjątkami opisanymi poniżej).

Importowanie własnej czcionki

Aby zaimportować czcionkę, wybierz warstwę tekstową, otwórz listę rozwijaną czcionek w Inspektorze i kliknij Importuj czcionkę…. Wybierz plik z systemu plików. To, co wydarzy się dalej, zależy od formatu pliku i aktywnej platformy.

Nagłówek GFX (.h)

Obsługiwane na: TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

Plik jest używany bez zmian, bez konwersji. Po przesłaniu czcionka jest dostępna na liście czcionek, a jej dane bitmap są osadzane w wygenerowanym kodzie.

Czcionka BDF

Obsługiwane na: U8g2, TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

• Na U8g2 — plik jest przesyłany bezpośrednio. Nieobsługiwane znaki w tytule czcionki są zastępowane, gdy Lopaka generuje symbol C i nazwę pliku .h.
• Na platformach opartych na GFX — plik BDF jest automatycznie konwertowany do formatu GFX przed przesłaniem. Konwersja obejmuje drukowalny zakres ASCII (0x20–0x7E). Wynik jest traktowany identycznie jak natywna czcionka GFX.

TTF / OTF / WOFF

Obsługiwane na: U8g2, TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

Przesłanie czcionki wektorowej otwiera Kreator czcionek:

1. Wysokość czcionki — ustaw docelową wysokość w pikselach. Steruje to rasteryzacją glifów. Mniejsze wartości dają kompaktowe bitmapy; większe wartości dają ostrzejsze glify kosztem większej ilości pamięci flash.
2. Powiększenie podglądu — skaluj podgląd (1×–5×), aby sprawdzić wynik. Nie wpływa to na dane wyjściowe.
3. Kliknij Importuj — czcionka jest rasteryzowana i zapisywana w projekcie.

Kreator obejmuje tylko drukowalne ASCII (od spacji do tyldy, 95 znaków). Znaki rozszerzone, litery z akcentami i glify CJK nie są uwzględniane w danych wyjściowych.

Rozmiar i skalowanie czcionki

Platforma	Kontrola rozmiaru	Jak to działa
U8g2	Brak — wybierz inną czcionkę	Każda czcionka BDF ma jeden stały rozmiar
TFT_eSPI / AdafruitGFX / ArduinoGFX / GxEPD2	Skala całkowita (1×, 2×, …)	Podwaja piksele bitmapy
LVGL	Brak — stała Montserrat	Wczesny etap; brak kontrolek rozmiaru i czcionki
ESPHome	Dowolna liczba (px)	Ustawia pole size: w YAML
Flipper Zero	Brak	Stałe czcionki systemowe
MicroPython / CircuitPython	Brak	Jedna wbudowana czcionka

Co trafia do wygenerowanego kodu

Platformy oparte na GFX

Dla każdej czcionki GFX, która nie jest wbudowaną czcionką Adafruit 5×7, generator wstawia:

#include <Fonts/FontName.h>
const GFXfont *font_FontName = &FontName;

Jeśli ta sama czcionka jest używana przez więcej niż jedną warstwę, deklaracja jest deduplikowana — pojawia się raz.

U8g2

W linii pojawia się tylko identyfikator czcionki:

u8g2.setFont(u8g2_font_helvB08_tr);

Bez nagłówka i bez zmiennej.

Flipper Zero

Stała czcionki jest osadzana bezpośrednio:

canvas_set_font(canvas, FontPrimary);

ESPHome

Blok font: jest dodawany w katalogu głównym dokumentu YAML. Wiele warstw tekstowych używających różnych rozmiarów tej samej czcionki tworzy osobne wpisy.

LVGL

Wbudowana czcionka Montserrat jest przywoływana bezpośrednio. Nie jest generowana żadna zmienna czcionki ani dołączenie.

Praktyczne wskazówki

• Minimalny czytelny rozmiar na monochromatycznych OLED-ach. Czcionki BDF 4–6 px są technicznie poprawne, ale na prawdziwym sprzęcie stają się trudne do odczytania. 8 px (np. helvB08) to praktyczne minimum dla większości wyświetlaczy.
• Budżet RAM dla czcionek GFX. Każda dołączona czcionka GFX zajmuje pamięć flash mikrokontrolera. FreeMono12pt7b to około 1,7 KB; FreeMonoBold24pt7b to około 4,5 KB. Sprawdź ograniczenia pamięci flash urządzenia przed dodaniem dużych czcionek.
• Pokrycie znaków własnych czcionek. Konwertery Lopaka BDF→GFX oraz importu czcionek wektorowych kodują tylko drukowalny zakres ASCII (spacja 0x20 do tylda 0x7E, 95 znaków). Aby uzyskać rozszerzone pokrycie U8g2, zaimportuj BDF zawierający te glify. Dla platform GFX użyj gotowego pliku .h, który już je zawiera.
• Własne czcionki muszą pasować do platformy projektu. Przesłane czcionki są przechowywane jako zasoby projektu — czcionka GFX .h nie zadziała na U8g2, a czcionka BDF nie zadziała na TFT_eSPI.

Czcionki według platformy

U8g2

U8g2 zawiera dużą kolekcję czcionek wywodzących się z BDF, skompilowanych bezpośrednio w bibliotece. Lopaka udostępnia tę pełną kolekcję w selektorze czcionek. Nazwy czcionek w wygenerowanym kodzie podążają za schematem nazewnictwa samej biblioteki:

u8g2.setFont(u8g2_font_haxrcorp4089_tr);

Żadne dane czcionki nie są generowane do szkicu — sama nazwa wystarczy, ponieważ czcionka już znajduje się w bibliotece U8g2. Wbudowane czcionki U8g2 są też pomijane w Ustawienia kodu → Czcionki, ponieważ nie ma dodatkowego pliku do pobrania.

Rozmiar czcionki jest stały. Każda czcionka BDF ma jedną wbudowaną wysokość w pikselach. Aby wyświetlić większy tekst, musisz wybrać inną czcionkę, a nie skalować bieżącą.

Przesyłanie własnych czcionek: U8g2 akceptuje pliki .bdf, .ttf, .otf i .woff. Pliki BDF są importowane bezpośrednio. Czcionki wektorowe otwierają Kreator czcionek, w którym wybierasz stałą wysokość w pikselach, zanim Lopaka przekonwertuje je do BDF. Lopaka przechowuje wynikowy BDF bez zmian na potrzeby podglądów i edycji. Własne czcionki pojawiają się w Ustawienia kodu → Czcionki, gdzie możesz pobrać każdą jako plik .h U8g2.

Domyślnie pobrany nagłówek zawiera każdy glif z BDF. Włącz Renderuj tylko użyte glify, aby uwzględnić tylko znaki Unicode używane przez warstwy tekstu i pola tekstowego odwołujące się do tej czcionki. Jeśli dowolna taka warstwa używa tekstu zmiennej w czasie wykonania, Lopaka eksportuje pełną czcionkę, aby nieznane znaki czasu wykonania nie zostały pominięte.

Przy włączonym Uwzględnij czcionki wygenerowane źródło ekranu zawiera każdy pobrany nagłówek czcionki.

TFT_eSPI, AdafruitGFX, ArduinoGFX, GxEPD2

Wszystkie te platformy używają formatu czcionki Adafruit GFX — pliku nagłówka C, który bezpośrednio osadza dane bitmap. Wbudowany zestaw obejmuje czcionkę Adafruit 5×7 oraz dziesiątki czcionek z rodziny Free w wielu rozmiarach (FreeMono, FreeSans, FreeSerif w wariantach regular, bold, italic, bold-italic w rozmiarach 9, 12, 18 i 24 pt oraz więcej).

Czcionka 5×7 jest własnym domyślnym ustawieniem biblioteki. Nie wymaga deklaracji nagłówka. Dla pozostałych czcionek to, co generator umieszcza na początku, zależy od tego, skąd pochodzą dane czcionki:

Platforma	Czcionki dostarczane z biblioteką	Inne czcionki (przesłane lub nieobecne w bibliotece)
TFT_eSPI	FreeMono/FreeSans/FreeSerif w rozmiarach 9, 12, 18 i 24 pt: bez #include, TFT_eSPI kompiluje je przy użyciu LOAD_GFXFF; niewyświetlane do pobrania	#include "FontName.h"
AdafruitGFX, GxEPD2, Inkplate	Rodzina Free, Org_01, Picopixel, Tiny3x3a2pt7b i TomThumb: #include <Fonts/FontName.h> z biblioteki Adafruit GFX	#include "FontName.h"
ArduinoGFX	—	#include "FontName.h" dla każdej czcionki

Wywołanie tekstu odwołuje się następnie bezpośrednio do symbolu czcionki:

#include <Fonts/FreeMono12pt7b.h>
// ...
display.setFont(&FreeMono12pt7b);

Dla każdego #include "FontName.h" pobierz nagłówek z Ustawienia kodu → Czcionki i umieść go obok szkicu.

Rozmiar czcionki jest skalowalny. Czcionki GFX obsługują całkowity mnożnik skali. Mnożnik 1 renderuje w natywnym rozmiarze pikseli; 2 podwaja oba wymiary.

Korekta pozycji Y. Czcionki GFX używają opadającej linii bazowej — współrzędna Y odnosi się do linii bazowej, a nie do góry glifu. Lopaka automatycznie to kompensuje, gdy przeciągasz tekst na obszarze rysowania, i generuje poprawioną współrzędną w wygenerowanym kodzie.

Przesyłanie własnych czcionek. Akceptuje pliki .h (gotowy nagłówek GFX), .bdf, .ttf, .otf i .woff.

• .h — używany bez zmian, bez konwersji.
• .bdf — automatycznie konwertowany do formatu GFX przed przesłaniem.
• .ttf / .otf / .woff — otwiera kreator czcionek (zobacz powyżej).

LVGL

Obsługa LVGL w Lopaka jest na wczesnym etapie. Obecnie dostępna jest tylko jedna czcionka — wbudowana Montserrat — w stałym rozmiarze. Kontrolki wyboru i rozmiaru czcionki nie są udostępnione. Zostanie to rozszerzone w przyszłej wersji.

ESPHome

ESPHome rozwiązuje czcionki z Google Fonts w czasie budowania. Wygenerowany YAML zawiera blok font:, który pobiera czcionkę po nazwie podczas wgrywania na urządzenie:

font:
    - file: gfonts://Roboto
      id: font_roboto
      size: 16

Rozmiar czcionki jest konfigurowalny. Dostępne czcionki to czcionki TTF zawarte we wbudowanym zestawie Lopaka (Roboto, Montserrat, Ubuntu i inne). Przesyłanie własnych czcionek nie jest obsługiwane dla ESPHome.

Flipper Zero i Flipper One

Flipper udostępnia dokładnie cztery czcionki systemowe:

Nazwa w Lopaka	Stała Flippera	Typowe użycie
Primary	FontPrimary	Zwykły tekst interfejsu
Secondary	FontSecondary	Małe etykiety drugorzędne
Keyboard	FontKeyboard	Klawiatura ekranowa
Big Numbers	FontBigNumbers	Wyświetlanie dużych cyfr

Nie ma kontrolek rozmiaru ani przesyłania własnych czcionek.

MicroPython

MicroPython używa jednej stałej wbudowanej czcionki (Petme 8×8). Wszystkie warstwy tekstowe używają jej automatycznie.

CircuitPython

CircuitPython używa czcionki BDF Terminus. Przesyłanie własnych czcionek nie jest obsługiwane.