Шрифты и текст

Для вывода текста используются функции text, textf, textAlign и textSize. Смотрите их описание ниже. Цвет выводимого теста определяется функцией stroke.

Вы можете загружать и использовать собственные шрифты из файлов (TrueType или OpenType) при помощи функций createFont и textFont.

Прежде чем выводить текст на экран формируется его разметка — определяются координаты и размеры каждого символа. Это делается автоматически и не требует никаких дополнительных действий. Однако для больших текстов эта операция может занять некоторое время. И если вы хотите увеличить производительность своей программы, то можете выполнить разметку текста заранее вызвав функцию createTextLayout (или createTextLayoutf) и, затем, выводить её на экран функцией textLayoutDraw.

Функции:

void text(double x, double y, const char *text);

Вывести текст в заданной точке. Расположение текста относительно указанной точки задаётся функцией textAlign. Шрифт и размер задаются функциями textFont и textSize. Цвет текста задаётся функцией stroke. См. также textf, createTextLayout.

Параметры:

text — текст для вывода;
x, y — координаты начальной точки.

void textf(double x, double y, const char *format, ...);

Форматированный вывод текста в заданной точке. Форматирование текста устроено так же как и в стандартной функции printf. Расположение текста относительно указанной точки задаётся функцией textAlign. Шрифт и размер задаются функциями textFont и textSize. Цвет текста задаётся функцией stroke. См. также text, createTextLayoutf.

Параметры:

text — текст для вывода;
x, y — координаты начальной точки.

void textAlign(HAlign hor, VAlign vert);

Установить расположение текста относительно начальной точки (см. функцию text)

Параметры:

hor — горизонтальное расположение начальной точки текста, может принимать значения:
    HALIGN_LEFT — начальная точка находится по левому краю текста;
    HALIGN_CENTER — начальная точка находится в середине текста;
    HALIGN_RIGHT — начальная точка находится по правому краю текста.
vert — вертикальное расположение начальной точки текста, может принимать значения:
    VALIGN_TOP — начальная точка находится по верхнему краю текста;
    VALIGN_CENTER — начальная точка находится в середине текста;
    VALIGN_BOTTOM — начальная точка находится по нижнему краю текста.

void textSize(double size);

Установить размер текста (см. функцию text).

Параметры:

size — размер текста в пикселях.

Font createFont(const char *path);

Загрузить шрифт из файла. Функция возвращает значение типа Font, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus.

Данная функция только загружает шрифт в память, для того чтобы писать текст этим шрифтом на экране вам нужно вызвать ещё и функцию textFont. Вы может иметь множество загруженных шрифтов в программе и переключать их функцией textFont.

См. также fontDestroy. и createFontFromMemory.

Параметры:

path — путь к файлу шрифта.

Font createFontFromMemory(const void *data, int size);

Создать шрифт из байтов файла шрифта уже загруженных в оперативную память. Функция возвращает значение типа Font, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus. См. также fontDestroy и createFont.

Параметры:

data — указатель на первый байт данных шрифта;
size — количество байтов.

void fontClone(Font font);

Создать новый шрифт из ранее загруженного — сделать копию.

void fontDestroy(Font font);

Выгрузить шрифт из памяти.

Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на шрифт. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на шрифт. Вы можете занести в эту переменную другой шрифт, но использовать старое значение переменной больше нельзя это приведёт у ошибкам и непредсказуемому поведению программы.

void textFont(Font font);

Выбрать ранее загруженный из файла шрифт для вывода текста (см. функции createFont и text). Вернуть стандартный шрифт можно командой textFontDefault.

Параметры:

font — шрифт загруженный функцией createFont.

void textFontDefault();

Вернуть стандартный шрифт для вывода текста. Отменяет действие функции textFont.

TextLayout createTextLayout(const char *text);

Создать разметку для заданного текста. Разметка определяет координаты и размер каждого символа текста. Разметка запоминает действующий на момент её создания шрифт (textFont) и выравнивание (textAlign), и, рисование данной разметки будет производиться только этим шрифтом. Однако, вы можете менять размер шрифта (textSize) и его цвет (stroke) непосредственно перед выводом данной разметки на экран. Вы можете узнать ширину (textLayoutGetWidth) и высоту (textLayoutGetHeight) текстового блока, а также выводить на экран весь текст (textLayoutDraw) или отдельные его части (textLayoutDrawSubstr) с применением разных способов заливки.

См. также createTextLayoutEx, createTextLayoutf, textLayoutDestroy.

TextLayout createTextLayoutEx(const char *text, int length);

Создать разметку для заданного текста, точно так же как и createTextLayout. Разница лишь в том, что данная функция создаёт разметку не для всего текста, а только для указанного количества его байтов.

См. также createTextLayoutf, textLayoutDestroy.

TextLayout createTextLayoutf(const char *format, ...);

Сформировать текст по заданному формату и создать разметку для этого текста. Форматирование текста устроено так же как и в стандартной функции printf. Подробнее о разметке текста смотрите в описании функции createTextLayout. См. также textLayoutDestroy.

void textLayoutDestroy(TextLayout layout);

Удалить разметку из памяти. См. также createTextLayout.

Важно: Скорее всего у вас в программе останется переменная в которой хранился указатель на разметку. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на разметку. Вы можете занести в эту переменную другую разметку, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.

void textLayoutDraw(TextLayout layout, double x, double y);

Вывести ранее созданную текстовую разметку на экран в заданных координатах. См. также createTextLayout и textLayoutDrawSubstr.

void textLayoutDrawFrom(TextLayout layout, double x, double y, int start);

Вывести в заданных координатах часть текста разметки начиная от заданного символа (параметр start) до конца текста. См. textLayoutDraw, textLayoutDrawSubstr, createTextLayout.

void textLayoutDrawSubstr(TextLayout layout, double x, double y, int start, int length);

Вывести в заданных координатах часть текста разметки длиной length начиная от start. См. textLayoutDraw, textLayoutDrawFrom, createTextLayout.

double textLayoutGetLeft(TextLayout layout);

double textLayoutGetTop(TextLayout layout);

Данные функции возвращают смещение верхнего левого угла границы текстового блока (см. рисунок) относительно базовой точки с учётом действующего в данный момент размера шрифта (textSize). См. также createTextLayout.

double textLayoutGetWidth(TextLayout layout);

Возвращает ширину текстового блока с учётом действующего в данный момент размера шрифта (textSize). См. также createTextLayout, textLayoutGetTop.

double textLayoutGetHeight(TextLayout layout);

double textLayoutGetTopAscenderLine(TextLayout layout);

Возвращает координату верхней линии выносных элементов строчных букв (ascender-line) первой строки текстового блока с учётом действующего в данный момент размера шрифта (textSize). См. также createTextLayout, textLayoutGetTop.

double textLayoutGetTopXLine(TextLayout layout);

Возвращает координату средней линии (верхняя граница строчных букв, x-line) первой строки текстового блока с учётом действующего в данный момент размера шрифта (textSize). См. также createTextLayout, textLayoutGetTop.

double textLayoutGetBottomBaseline(TextLayout layout);

Возвращает координату базовой линии последней строки текстового блока с учётом действующего в данный момент размера шрифта (textSize). См. также createTextLayout, textLayoutGetTop.

int textLayoutCursorUp(TextLayout layout, int cursor);

Возвращает порядковый номер символа находящегося в тексте непосредственно над заданным символом. См. также textLayoutCursorDown и createTextLayout.

int textLayoutCursorDown(TextLayout layout, int cursor);

Возвращает порядковый номер символа находящегося в тексте непосредственно под заданным символом. См. также textLayoutCursorUp и createTextLayout.

double textLayoutCursorGetX(TextLayout layout, int cursor);

Возвращает координату X левого нижнего края заданного символа. См. также textLayoutCursorGetY и createTextLayout.

double textLayoutCursorGetY(TextLayout layout, int cursor);

Возвращает координату Y левого нижнего края заданного символа. См. также textLayoutCursorGetX и createTextLayout.

double textLayoutCursorGetHeight(TextLayout layout, int cursor);

Возвращает высоту заданного символа. См. также textLayoutCursorGetX, textLayoutCursorGetY и createTextLayout.