<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="index.html">Helianthus</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="sprites.html">Спрайты</a></p>
<p><a href="groups.html">Группы спрайтов</a></p>
<p><a href="camera.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>Для подключения и использования библиотеки Helianthus нужно:<br />
- подключить файл <i><helianthus.h></i><br />
- создать и зарегистрировать функции для начальной загрузки и для перерисовки кадра (см. <a href="common.html#worldSetInit">worldSetInit</a> и <a href="common.html#worldSetDraw">worldSetDraw</a>)<br />
- также вы можете зарегистрировать функцию для выполнения каких-либо действий при завершении программы (<a href="common.html#worldSetDeinit">worldSetDeinit</a>);<br />
- вызвать функцию <a href="common.html#worldRun">worldRun</a> для запуска вашей программы</p>
<p>Вот что должно получиться:</p>
<pre>
#include <helianthus.h>
void init() {
// Здесь будут команды для начальной загрузки.
// Они выполнятся только один раз в самом начале.
}
void draw() {
// Здесь будут команды для движения и рисования.
// Во время работы программы они будут запускаться
// несколько раз в секунду.
}
void deinit() {
// Команды внутри этой функции запустятся
// только один раз в самом конце при завершении
// работы программы.
}
int main() {
worldSetInit(&init);
worldSetDraw(&draw);
worldSetDeinit(&deinit);
worldRun();
return 0;
}
</pre>
<p>После завершения работы Helianthus (при окончании выполнения функции <a href="common.html#worldRun">worldRun</a>) все созданные вами объекты библиотеки будут удалены автоматически. Если вы хотите удалить что-то вручную, смотрите функции удаления для соответствующих объектов (<a href="sprites.html#spriteDestroy">spriteDestroy</a>, <a href="groups.html#groupDestroy">groupDestroy</a>, <a href="sound.html#soundDestroy">soundDestroy</a>, <a href="drawing.html#fontDestroy">fontDestroy</a>, <a href="common.html#closeDirectory">closeDirectory</a>).</p>
<p>Вы можете задать размер окна программы функциями <a href="common.html#worldSetWidth">worldSetWidth</a>, <a href="common.html#worldSetHeight">worldSetHeight</a> и задать заголовок окна функцией <a href="common.html#worldSetTitle">worldSetTitle</a>.</p>
<p>Изначально окно имеет фиксированный размер, который вы можете менять только из программы, командами указанными выше. Однако вы можете это изменить и разрешить пользователю изменять размер окна, смотрите функцию <a href="common.html#worldSetResizable">worldSetResizable</a>.</p>
<p>Окно программы непрерывно перерисовывается с частотой 24 кадра в секунду. Частоту перерисовки вы можете поменять при помощи функции <a href="common.html#worldSetFrameRate">worldSetFrameRate</a>.</p>
<p>Программа ведёт отсчёт времени и кадров с момента запуска вы можете получить значение этих счётчиков пи помощи функций <a href="common.html#worldGetSeconds">worldGetSeconds</a> и <a href="common.html#worldGetFrameCount">worldGetFrameCount</a>. Длительность одного кадра можно узнать вызвав функцию <a href="common.html#worldGetTimeStep">worldGetTimeStep</a>.</p>
<p>Также Helianthus предоставляет некоторые общие функции которые не представлены в стандартном я зыке C:<br />
- помощники в генерации случайных чисел (<a href="common.html#randomNumber">randomNumber</a>, <a href="common.html#randomFloat">randomFloat</a>);<br />
- функции для чтения папок (см. <a href="common.html#openDirectory">openDirectory</a>);<br />
- функции проверки существования файлов и папок — <a href="common.html#fileExists">fileExists</a>, <a href="common.html#directoryExists">directoryExists</a>.<br />
- функции для создания всплывающие окна с текстовыми сообщениями (<a href="common.html#messageBox">messageBox</a>) и окон для ввода текста (<a href="common.html#askText">askText</a>, <a href="common.html#askTextEx">askTextEx</a>).</p>
<h2>Функции:</h2>
<h3 id="worldSetInit">void worldSetInit(Callback init);</h3>
<p>Задать функцию для начальной инициализации (загрузки). Эта функция будет запущена только один раз в самом начале работы программы, как только будет вызвана функция <a href="common.html#worldRun">worldRun</a>.</p>
<h4>Параметры:</h4>
<p><i>init</i> — указатель на функцию начальной инициализации (загрузки). Функция быть работать без параметров и не должна возвращать значение.</p>
<h3 id="worldSetDraw">void worldSetDraw(Callback draw);</h3>
<p>Задать основную функцию вашей программы — функцию для перерисовки кадра. Во время работы программы заданная функция будет запускаться несколько раз в секунду перед перерисовкой каждого кадра. Поместите в неё команды для движения и рисования.</p>
<h4>Параметры:</h4>
<p><i>draw</i> — указатель на функцию перерисовки кадра. Функция быть работать без параметров и не должна возвращать значение.</p>
<h3 id="worldSetDeinit">void worldSetDeinit(Callback deinit);</h3>
<p>Задать функцию для выполнения каких-либо действий при завершении программы. Эта функция будет запущена только один раз при окончании работы программы, непосредственно перед завершением выполнения функции <a href="common.html#worldRun">worldRun</a>.</p>
<h4>Параметры:</h4>
<p><i>deinit</i> — указатель на функцию которая будет выполнена перед завершением программы.</p>
<h3 id="worldRun">void worldRun();</h3>
<p>Запустить вашу программу на Helianthus. Перед вызовом этой функции нужно зарегистрировать функции начальной загрузки и перерисовки кадра (см. выше)</p>
<h3 id="worldStop">void worldStop();</h3>
<p>Остановить и закрыть программу. Программа всегда закрывается если пользователь нажмёт на крестик в верхнем правом углу окна, но вы можете добавить и свои способы выхода из программы. Например, в функцию перерисовки вы можете вставить возможность выхода по нажатию клавиши Esc (см. также раздел <a href="input.html" />«Клавиатура и мышь»</a>):</p>
<pre>
void draw() {
…
if (keyWentPressed("escape")) {
worldStop()
}
…
}
</pre>
<h3 id="worldGetWidth">int worldGetWidth();</h3>
<p>Возвращает ширину окна в пикселях. См. также <a href="common.html#worldSetWidth">worldSetWidth</a>.</p>
<h3 id="worldSetWidth">void worldSetWidth(int width);</h3>
<p>Установить ширину окна. См. также <a href="common.html#worldGetWidth">worldGetWidth</a>.</p>
<h4>Параметры:</h4>
<p><i>width</i> — новая ширина окна.</p>
<h3 id="worldGetHeight">int worldGetHeight();</h3>
<p>Возвращает высоту окна в пикселях. См. также <a href="common.html#worldSetHeight">worldSetHeight</a>.</p>
<h3 id="worldSetHeight">void worldSetHeight(int height);</h3>
<p>Установить высоту окна. См. также <a href="common.html#worldGetHeight">worldGetHeight</a>.</p>
<h4>Параметры:</h4>
<p><i>height</i> — новая ширина окна.</p>
<h3 id="worldGetResizable">int worldGetResizable();</h3>
<p>Возвращает <i>TRUE</i> если пользователь имеет возможность изменять размер окна, в противном случае возвращает <i>FALSE</i>.</p>
<h3 id="worldSetResizable">void worldSetResizable(int resizable);</h3>
<p>Включает или выключает возможность измерения размеров окна пользователем. Когда включено пользователь может менять размер окна растягивая его, хватаясь за границы, и, появляется кнопка для разворачивания окна на весь экран.</p>
<h4>Параметры:</h4>
<p><i>resizable</i> — если <i>TRUE</i>, то разрешает пользователю изменять размер окна.</p>
<h3 id="worldGetTitle">const char* worldGetTitle();</h3>
<p>Возвращает установленный ранее заголовок окна (строка текста).</p>
<h3 id="worldSetTitle">void worldSetTitle(const char *title);</h3>
<p>Установить заголовок окна.</p>
<h4>Параметры:</h4>
<p><i>title</i> — новый заголовок окна.</p>
<h3 id="worldGetFrameRate">double worldGetFrameRate();</h3>
<p>Возвращает частоту перерисовки окна, количество кадров в секунду. См. также <a href="common.html#worldSetFrameRate">worldSetFrameRate</a>.</p>
<h3 id="worldSetFrameRate">void worldSetFrameRate(double frameRate);</h3>
<p>Установить частоту перерисовки окна. См. также <a href="common.html#worldGetFrameRate">worldGetFrameRate</a>.</p>
<h4>Параметры:</h4>
<p><i>frameRate</i> — количество кадров в секунду, от 1 до 100.</p>
<h3 id="worldGetTimeStep">double worldGetTimeStep();</h3>
<p>Возвращает длительность одного кадра в секундах. См. также <a href="common.html#worldGetFrameRate">worldGetFrameRate</a>.</p>
<h3 id="worldGetFrameCount">int worldGetFrameCount();</h3>
<p>Возвращает количество кадров прошедшее с момента запуска программы (с момента вызова функции <a href="common.html#worldRun">worldRun</a>. См. также <a href="common.html#worldGetSeconds">worldGetSeconds</a>.</p>
<h3 id="worldGetSeconds">double worldGetSeconds();</h3>
<p>Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции <a href="common.html#worldRun">worldRun</a>. См. также <a href="common.html#worldGetFrameCount">worldGetFrameCount</a>.</p>
<h3 id="randomNumber">int randomNumber(int min, int max);</h3>
<p>Возвращает случайное целое число от <i>min</i> до <i>max</i> включительно.</p>
<h4>Параметры:</h4>
<p><i>min</i> — минимальное значение для случайного числа;<br />
<i>max</i> — максимальное значение для случайного числа.</p>
<h3 id="randomFloat">double randomFloat();</h3>
<p>Возвращает случайное дробное число в диапазоне от 0 до 1.</p>
<h3 id="openDirectory">Directory openDirectory(const char *path);</h3>
<p>Если папка существует, то функция читает список файлов в папке и сохраняет этот список в памяти. Возвращает значение типа <i>Directory</i>, которое является адресом в памяти — указателем на описание списка внутри библиотеки Helianthus.</p>
<p>Если папка не существует или её по какой-то причине невозможно открыть, то функция возвращает нулевой указатель (<i>NULL</i>).</p>
<p>Имена файлов можно получить при помощи функций <a href="common.html#directoryGetCount">directoryGetCount</a> и <a href="common.html#directoryGet">directoryGet</a>. После использования список нужно удалить функцией <a href="common.html#closeDirectory">closeDirectory</a>.</p>
<p>Пример:</p>
<pre>
Directory dir = openDirectory("my/directory");
if (dir) {
for(int i = 0; i < directoryGetCount(dir); ++i) {
printf("file: %s", directoryGet(dir, i));
}
closeDirectory(dir);
}
</pre>
<h4>Параметры:</h4>
<p><i>path</i> — путь к папке.</p>
<h3 id="closeDirectory">void closeDirectory(Directory directory);</h3>
<p>Удаляет ранее загруженный список файлов из памяти. См. также <a href="common.html#openDirectory">openDirectory</a>.</p>
<p><b>Важно:</b> Скорее всего у вас в программе останется переменная в которой хранился указатель на список. Этот указатель станет недействителен — будет указывать на неопределённую область памяти — не на список файлов. Вы можете занести в эту переменную другую список файлов, но использовать старое значение переменной больше нельзя это приведёт к ошибкам и непредсказуемому поведению программы.</p>
<h3 id="directoryGetCount">int directoryGetCount(Directory directory);</h3>
<p>Возвращает количество файлов в списке. См. также <a href="common.html#openDirectory">openDirectory</a> и <a href="common.html#directoryGet">directoryGet</a>.</p>
<h3 id="directoryGet">const char* directoryGet(Directory directory, int i);</h3>
<p>Возвращает имя файла с указанным номером из ранее открытого списка. См. также <a href="common.html#openDirectory">openDirectory</a> и <a href="common.html#directoryGet">directoryGet</a>.</p>
<h4>Параметры:</h4>
<p><i>i</i> — номер файла в списке.</p>
<h3 id="fileExists">int fileExists(const char *path);</h3>
<p>Возвращает <i>TRUE</i> (число 1) если файл по заданному пути существует, иначе возвращает <i>FALSE</i> (число 0).</p>
<h4>Параметры:</h4>
<p><i>path</i> — путь к проверяемому файлу.</p>
<h3 id="directoryExists">int directoryExists(const char *path);</h3>
<p>Возвращает <i>TRUE</i> (число 1) если папке по заданному пути существует, иначе возвращает <i>FALSE</i> (число 0).</p>
<h4>Параметры:</h4>
<p><i>path</i> — путь к проверяемой папке.</p>
<h3 id="messageBox">void messageBox(const char *message);</h3>
<p>Показать окно с текстовым сообщением. Работа программы будет приостановлена, до тех пор пока пользователь не закроет окно (нажав на кнопку OK, например).</p>
<h4>Параметры:</h4>
<p><i>message</i> — текстовое сообщение.</p>
<h3 id="askText">void askText(const char *question, char *answer, int maxAnswerSize);</h3>
<p>Создаёт окно для ввода текста. Пользователю будет предоставлена для редактирования строка текста из параметра <i>answer</i>. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. См. также <a href="common.html#askTextEx">askTextEx</a>.</p>
<h4>Параметры:</h4>
<p><i>question</i> — сообщение для пользователя;<br />
<i>answer</i> — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;<br />
<i>maxAnswerSize</i> — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт.</p>
<h3 id="askTextEx">void askTextEx(const char *question, char *answer, int maxAnswerSize, int multiline, int password);</h3>
<p>Создаёт окно для ввода текста. Пользователю будет предоставлен для редактирования текст из параметра <i>answer</i>. Позволяет работать с многострочным текстом и прятать вводимые символы (для ввода пароля). Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. См. также <a href="common.html#askText">askText</a>.</p>
<h4>Параметры:</h4>
<p><i>question</i> — сообщение для пользователя;<br />
<i>answer</i> — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;<br />
<i>maxAnswerSize</i> — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт;<br />
<i>multiline</i> — если <i>TRUE</i>, то будет отображаться поле для ввода многострочного текста;<br />
<i>password</i> — если <i>TRUE</i>, то вводимые символы будут спрятаны (можно использовать для ввода паролей).</p>
</div>
</body>
</html>