<html>
<head>
<meta charset="UTF-8" />
<link rel="stylesheet" type="text/css" href="style.css" />
<title>Шрифты и текст - Helianthus</title>
</head>
<body>
<div class="navigation">
<p><a href="https://coolbug.org/users/bw/helianthus/ru.html">Helianthus</a></p>
<hr />
<p><a href="index.html">Helianthus: Документация</a></p>
<p><a href="install.html">Установка</a></p>
<p><a href="common.html">Запуск и общие функции</a></p>
<p><a href="input.html">Клавиатура и мышь</a></p>
<p><a href="drawing.html">Рисование</a></p>
<p><a href="font.html">Шрифты и текст</a></p>
<p><a href="animation.html">Текстуры и анимация</a></p>
<p><a href="framebuffer.html">Буфер кадра</a></p>
<p><a href="sprites.html">Спрайты</a></p>
<p><a href="groups.html">Группы спрайтов</a></p>
<p><a href="sound.html">Звук</a></p>
<hr />
<p><a href="functions.html">Все функции</a></p>
</div>
<div class="content">
<h1>Шрифты и текст</h1>
<p>Для вывода текста используются функции <a href="font.html#text">text</a>, <a href="font.html#textf">textf</a>, <a href="font.html#textAlign">textAlign</a> и <a href="font.html#textSize">textSize</a>. Смотрите их описание ниже. Цвет выводимого теста определяется функцией <a href="drawing.html#stroke">stroke</a>.</p>
<p>Вы можете загружать и использовать собственные шрифты из файлов (TrueType или OpenType) при помощи функций <a href="font.html#createFont">createFont</a> и <a href="font.html#textFont">textFont</a>.</p>
<p>Прежде чем выводить текст на экран формируется его разметка — определяются координаты и размеры каждого символа. Это делается автоматически и не требует никаких дополнительных действий. Однако для больших текстов эта операция может занять некоторое время. И если вы хотите увеличить производительность своей программы, то можете выполнить разметку текста заранее вызвав функцию <a href="font.html#createTextLayout">createTextLayout</a> (или <a href="font.html#createTextLayoutf">createTextLayoutf</a>) и, затем, выводить её на экран функцией <a href="font.html#textLayoutDraw">textLayoutDraw</a>.</p>
<h2>Функции:</h2>
<h3 id="text">void text(double x, double y, const char *text);</h3>
<p>Вывести текст в заданной точке. Расположение текста относительно указанной точки задаётся функцией <a href="font.html#textAlign">textAlign</a>. Шрифт и размер задаются функциями <a href="font.html#textFont">textFont</a> и <a href="font.html#textSize">textSize</a>. Цвет текста задаётся функцией <a href="drawing.html#stroke">stroke</a>. См. также <a href="font.html#textf">textf</a>, <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<h4>Параметры:</h4>
<p><i>tex</i><i>t</i> — текст для вывода;<br />
<i>x</i>, <i>y</i> — координаты начальной точки.</p>
<h3 id="textf">void textf(double x, double y, const char *format, ...);</h3>
<p>Форматированный вывод текста в заданной точке. Форматирование текста устроено так же как и в стандартной функции <i>printf</i>. Расположение текста относительно указанной точки задаётся функцией <a href="font.html#textAlign">textAlign</a>. Шрифт и размер задаются функциями <a href="font.html#textFont">textFont</a> и <a href="font.html#textSize">textSize</a>. Цвет текста задаётся функцией <a href="drawing.html#stroke">stroke</a>. См. также <a href="font.html#text">text</a>, <a href="font.html#createTextLayoutf">createTextLayoutf</a>.</p>
<h4>Параметры:</h4>
<p><i>tex</i><i>t</i> — текст для вывода;<br />
<i>x</i>, <i>y</i> — координаты начальной точки.</p>
<h3 id="textAlign">void textAlign(HAlign hor, VAlign vert);</h3>
<p>Установить расположение текста относительно начальной точки (см. функцию <a href="font.html#text">text</a>)</p>
<h4>Параметры:</h4>
<p><i>hor</i> — горизонтальное расположение начальной точки текста, может принимать значения:<br />
<i>HALIGN_LEFT</i> — начальная точка находится по левому краю текста;<br />
<i>HALIGN_CENTER</i> — начальная точка находится в середине текста;<br />
<i>HALIGN_RIGHT</i> — начальная точка находится по правому краю текста.<br />
<i>vert</i> — вертикальное расположение начальной точки текста, может принимать значения:<br />
<i>VALIGN_TOP</i> — начальная точка находится по верхнему краю текста;<br />
<i>VALIGN_CENTER</i> — начальная точка находится в середине текста;<br />
<i>VALIGN_BOTTOM</i> — начальная точка находится по нижнему краю текста.</p>
<h3 id="textSize">void textSize(double size);</h3>
<p>Установить размер текста (см. функцию <a href="font.html#text">text</a>).</p>
<h4>Параметры:</h4>
<p><i>size</i> — размер текста в пикселях.</p>
<h3 id="createFont">Font createFont(const char *path);</h3>
<p>Загрузить шрифт из файла. Функция возвращает значение типа <i>Font</i>, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus.</p>
<p>Данная функция только загружает шрифт в память, для того чтобы писать текст этим шрифтом на экране вам нужно вызвать ещё и функцию <a href="font.html#textFont">textFont</a>. Вы может иметь множество загруженных шрифтов в программе и переключать их функцией <a href="font.html#textFont">textFont</a>.</p>
<p>См. также <a href="font.html#fontDestroy">fontDestroy</a>. и <a href="font.html#createFontFromMemory">createFontFromMemory</a>.</p>
<h4>Параметры:</h4>
<p><i>path</i> — путь к файлу шрифта.</p>
<h3 id="createFontFromMemory">Font createFontFromMemory(const void *data, int size);</h3>
<p>Создать шрифт из байтов файла шрифта уже загруженных в оперативную память. Функция возвращает значение типа <i>Font</i>, которое является адресом в памяти — указателем на описание шрифта внутри библиотеки Helianthus. См. также <a href="font.html#fontDestroy">fontDestroy</a> и <a href="font.html#createFont">createFont</a>.</p>
<h4>Параметры:</h4>
<p><i>data</i> — указатель на первый байт данных шрифта;<br />
<i>size</i> — количество байтов.</p>
<h3 id="fontClone">void fontClone(Font font);</h3>
<p>Создать новый шрифт из ранее загруженного — сделать копию.</p>
<h3 id="fontDestroy">void fontDestroy(Font font);</h3>
<p>Выгрузить шрифт из памяти.</p>
<p><b>Важно:</b> Скорее всего у вас в программе останется переменная в которой хранился указатель на шрифт. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на шрифт. Вы можете занести в эту переменную другой шрифт, но использовать старое значение переменной больше нельзя это приведёт у ошибкам и непредсказуемому поведению программы.</p>
<h3 id="textFont">void textFont(Font font);</h3>
<p>Выбрать ранее загруженный из файла шрифт для вывода текста (см. функции <a href="font.html#createFont">createFont</a> и <a href="font.html#text">text</a>). Вернуть стандартный шрифт можно командой <a href="font.html#textFontDefault">textFontDefault</a>.</p>
<h4>Параметры:</h4>
<p><i>font</i> — шрифт загруженный функцией <a href="font.html#createFont">createFont</a>.</p>
<h3 id="textFontDefault">void textFontDefault();</h3>
<p>Вернуть стандартный шрифт для вывода текста. Отменяет действие функции <a href="font.html#textFont">textFont</a>.</p>
<h3 id="createTextLayout">TextLayout createTextLayout(const char *text);</h3>
<p>Создать разметку для заданного текста. Разметка определяет координаты и размер каждого символа текста. Разметка запоминает действующий на момент её создания шрифт (<a href="font.html#textFont">textFont</a>) и выравнивание (<a href="font.html#textAlign">textAlign</a>), и, рисование данной разметки будет производиться только этим шрифтом. Однако, вы можете менять размер шрифта (<a href="font.html#textSize">textSize</a>) и его цвет (<a href="drawing.html#stroke">stroke</a>) непосредственно перед выводом данной разметки на экран. Вы можете узнать ширину (<a href="font.html#textLayoutGetWidth">textLayoutGetWidth</a>) и высоту (<a href="font.html#textLayoutGetHeight">textLayoutGetHeight</a>) текстового блока, а также выводить на экран весь текст (<a href="font.html#textLayoutDraw">textLayoutDraw</a>) или отдельные его части (<a href="font.html#textLayoutDrawSubstr">textLayoutDrawSubstr</a>) с применением разных способов заливки.</p>
<p>См. также <a href="font.html#createTextLayoutf">createTextLayoutf</a>, <a href="font.html#textLayoutDestroy">textLayoutDestroy</a>.</p>
<h3 id="createTextLayoutf">TextLayout createTextLayoutf(const char *format, ...);</h3>
<p>Сформировать текст по заданному формату и создать разметку для этого текста. Форматирование текста устроено так же как и в стандартной функции <i>printf</i>. Подробнее о разметке текста смотрите в описании функции <a href="font.html#createTextLayout">createTextLayout</a>. См. также <a href="font.html#textLayoutDestroy">textLayoutDestroy</a>.</p>
<h3 id="textLayoutDestroy">void textLayoutDestroy(TextLayout layout);</h3>
<p>Удалить разметку из памяти. См. также <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<p><b>Важно:</b> Скорее всего у вас в программе останется переменная в которой хранился указатель на разметку. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на разметку. Вы можете занести в эту переменную другую разметку, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.</p>
<h3 id="textLayoutDraw">void textLayoutDraw(TextLayout layout, double x, double y);</h3>
<p>Вывести ранее созданную текстовую разметку на экран в заданных координатах. См. также <a href="font.html#createTextLayout">createTextLayout</a> и <a href="font.html#textLayoutDrawSubstr">textLayoutDrawSubstr</a>.</p>
<h3 id="textLayoutDrawFrom">void textLayoutDrawFrom(TextLayout layout, double x, double y, int start);</h3>
<p>Вывести в заданных координатах часть текста разметки начиная от заданного символа (параметр <i>start</i>) до конца текста. См. <a href="font.html#textLayoutDraw">textLayoutDraw</a>, <a href="font.html#textLayoutDrawSubstr">textLayoutDrawSubstr</a>, <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<h3 id="textLayoutDrawSubstr">void textLayoutDrawSubstr(TextLayout layout, double x, double y, int start, int length);</h3>
<p>Вывести в заданных координатах часть текста разметки длиной <i>length</i> начиная от <i>start</i>. См. <a href="font.html#textLayoutDraw">textLayoutDraw</a>, <a href="font.html#textLayoutDrawFrom">textLayoutDrawFrom</a>, <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<h3 id="textLayoutGetLeft">double textLayoutGetLeft(TextLayout layout);</h3>
<h3 id="textLayoutGetTop">double textLayoutGetTop(TextLayout layout);</h3>
<p>Данные функции возвращают смещение верхнего левого угла границы текстового блока (см. рисунок) относительно базовой точки с учётом действующего в данный момент размера шрифта (<a href="font.html#textSize">textSize</a>). См. также <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<img src="image/figure5.png" />
<h3 id="textLayoutGetWidth">double textLayoutGetWidth(TextLayout layout);</h3>
<p>Возвращает ширину текстового блока с учётом действующего в данный момент размера шрифта (<a href="font.html#textSize">textSize</a>). См. также <a href="font.html#createTextLayout">createTextLayout</a>, <a href="font.html#textLayoutGetTop">textLayoutGetTop</a>.</p>
<h3 id="textLayoutGetHeight">double textLayoutGetHeight(TextLayout layout);</h3>
<p>Возвращает ширину текстового блока с учётом действующего в данный момент размера шрифта (<a href="font.html#textSize">textSize</a>). См. также <a href="font.html#createTextLayout">createTextLayout</a>, <a href="font.html#textLayoutGetTop">textLayoutGetTop</a>.</p>
<h3 id="textLayoutGetTopAscenderLine">double textLayoutGetTopAscenderLine(TextLayout layout);</h3>
<p>Возвращает координату верхней линии выносных элементов строчных букв (ascender-line) первой строки текстового блока с учётом действующего в данный момент размера шрифта (<a href="font.html#textSize">textSize</a>). См. также <a href="font.html#createTextLayout">createTextLayout</a>, <a href="font.html#textLayoutGetTop">textLayoutGetTop</a>.</p>
<h3 id="textLayoutGetTopXLine">double textLayoutGetTopXLine(TextLayout layout);</h3>
<p>Возвращает координату средней линии (верхняя граница строчных букв, x-line) первой строки текстового блока с учётом действующего в данный момент размера шрифта (<a href="font.html#textSize">textSize</a>). См. также <a href="font.html#createTextLayout">createTextLayout</a>, <a href="font.html#textLayoutGetTop">textLayoutGetTop</a>.</p>
<h3 id="textLayoutGetBottomBaseline">double textLayoutGetBottomBaseline(TextLayout layout);</h3>
<p>Возвращает координату базовой линии последней строки текстового блока с учётом действующего в данный момент размера шрифта (<a href="font.html#textSize">textSize</a>). См. также <a href="font.html#createTextLayout">createTextLayout</a>, <a href="font.html#textLayoutGetTop">textLayoutGetTop</a>.</p>
<h3 id="textLayoutCursorUp">int textLayoutCursorUp(TextLayout layout, int cursor);</h3>
<p>Возвращает порядковый номер символа находящегося в тексте непосредственно над заданным символом. См. также <a href="font.html#textLayoutCursorDown">textLayoutCursorDown</a> и <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<h3 id="textLayoutCursorDown">int textLayoutCursorDown(TextLayout layout, int cursor);</h3>
<p>Возвращает порядковый номер символа находящегося в тексте непосредственно под заданным символом. См. также <a href="font.html#textLayoutCursorUp">textLayoutCursorUp</a> и <a href="font.html#createTextLayout">createTextLayout</a>.</p>
<h3 id="textLayoutCursorGetX">double textLayoutCursorGetX(TextLayout layout, int cursor);</h3>
<p>Возвращает координату X левого нижнего края заданного символа. См. также <a href="font.html#textLayoutCursorGetY">textLayoutCursorGetY</a> и <a href="font.html#createTextLayout">createTextLayout</a><i>.</i></p>
<h3 id="textLayoutCursorGetY">double textLayoutCursorGetY(TextLayout layout, int cursor);</h3>
<p>Возвращает координату Y левого нижнего края заданного символа. См. также <a href="font.html#textLayoutCursorGetX">textLayoutCursorGetX</a> и <a href="font.html#createTextLayout">createTextLayout</a><i>.</i></p>
<h3 id="textLayoutCursorGetHeight">double textLayoutCursorGetHeight(TextLayout layout, int cursor);</h3>
<p>Возвращает высоту заданного символа. См. также <a href="font.html#textLayoutCursorGetX">textLayoutCursorGetX</a>, <a href="font.html#textLayoutCursorGetY">textLayoutCursorGetY</a><i> </i>и <a href="font.html#createTextLayout">createTextLayout</a>.</p>
</div>
</body>
</html>