From 1badb6933e7d408da82c79bcef30e081a827a199 Mon Sep 17 00:00:00 2001 From: Ivan Mahonin Date: Mar 23 2020 13:01:05 +0000 Subject: update documentation --- diff --git a/doc/build/.gitignore b/doc/build/.gitignore new file mode 100644 index 0000000..2d19fc7 --- /dev/null +++ b/doc/build/.gitignore @@ -0,0 +1 @@ +*.html diff --git a/doc/build/style.css b/doc/build/style.css new file mode 100644 index 0000000..a8b83a9 --- /dev/null +++ b/doc/build/style.css @@ -0,0 +1,100 @@ + +body { + margin: auto; + padding: 0; + border: 0; + max-width: 1100px; + height: 100%; + background-color: rgb(100, 100, 100); + font-family: serif; + font-size: 12pt; + line-height: 1.5; +} + +.navigation { + margin: 0; + border: 0; + position: fixed; + max-width: 280px; + padding: 20px; +} + +.navigation a { + font-family: sans-serif; + font-weight: bold; + text-decoration: none; + color: rgb(220, 220, 220); + color: white; +} +.navigation a:visited { color: rgb(200, 200, 200); } +.navigation a:hover { color: white !important; } +.navigation a:active { color: rgb(180, 180, 180); } + +.navigation hr { + border: 0; + border-top: 1px solid gray; + margin-left: 20px; + width: 100px; +} + + +.content { + margin: 0 0 0 340px; + padding: 20px; + border: 0; + max-width: 800px; + min-height: 100%; + background-color: white; +} + +.content a { + font-family: sans-serif; + font-weight: bold; + text-decoration: none; +} + +p { + margin-top: 10px; + margin-bottom: 20px; +} + +h1, h2, h3, h4, h5 { + font-family: sans-serif; + font-weight: bold; +} + +h1 { + font-size: 18pt; +} + +h2 { + font-size: 14pt; +} + +h3 { + font-size: 12pt; + margin-top: 30px; + margin-bottom: 5px; +} + +h3+h3 { + margin-top: 0; +} + +h4 { + font-size: 10pt; + margin-top: 0; + margin-bottom: 0; +} + +table, th, td { + border: 1px solid gray; + border-collapse: collapse; + padding: 5px; +} + +pre { + border: 1px solid gray; + background-color: rgb(230, 230, 230); + padding: 10px; +} \ No newline at end of file diff --git a/doc/helianthus-doc-ru.odt b/doc/helianthus-doc-ru.odt index 92cb302..7d0a38d 100644 Binary files a/doc/helianthus-doc-ru.odt and b/doc/helianthus-doc-ru.odt differ diff --git a/doc/ru/common.html b/doc/ru/common.html index c235887..986c42d 100644 --- a/doc/ru/common.html +++ b/doc/ru/common.html @@ -24,6 +24,7 @@

Для подключения и использования библиотеки Helianthus нужно:
- подключить файл <helianthus.h>
- создать и зарегистрировать функции для начальной загрузки и для перерисовки кадра (см. worldSetInit и worldSetDraw)
+- также вы можете зарегистрировать функцию для выполнения каких-либо действий при завершении программы (worldSetDeinit);
- вызвать функцию worldRun для запуска вашей программы

Вот что должно получиться:

@@ -42,15 +43,38 @@ void draw() {     // несколько раз в секунду. } +void deinit() { +    // Команды внутри этой функции запустятся +    // только один раз в самом конце при завершении +    // работы программы. +} + int main() {     worldSetInit(&init);     worldSetDraw(&draw); +    worldSetDeinit(&deinit);     worldRun();     return 0; } +

После завершения работы Helianthus (при окончании выполнения функции worldRun) все созданные вами объекты библиотеки будут удалены автоматически. Если вы хотите удалить что-то вручную, смотрите функции удаления для соответствующих объектов (spriteDestroy, groupDestroy, soundDestroy, fontDestroy, closeDirectory).

+ +

Вы можете задать размер окна программы функциями worldSetWidth, worldSetHeight и задать заголовок окна функцией worldSetTitle.

+ +

Изначально окно имеет фиксированный размер, который вы можете менять только из программы, командами указанными выше. Однако вы можете это изменить и разрешить пользователю изменять размер окна, смотрите функцию worldSetResizable.

+ +

Окно программы непрерывно перерисовывается с частотой 24 кадра в секунду. Частоту перерисовки вы можете поменять при помощи функции worldSetFrameRate.

+ +

Программа ведёт отсчёт времени и кадров с момента запуска вы можете получить значение этих счётчиков пи помощи функций worldGetSeconds и worldGetFrameCount. Длительность одного кадра можно узнать вызвав функцию worldGetTimeStep.

+ +

Также Helianthus предоставляет некоторые общие функции которые не представлены в стандартном я зыке C:
+- помощники в генерации случайных чисел (randomNumber, randomFloat);
+- функции для чтения папок (см. openDirectory);
+- функции проверки существования файлов и папок — fileExists, directoryExists.
+- функции для создания всплывающие окна с текстовыми сообщениями (messageBox) и окон для ввода текста (askText, askTextEx).

+

Функции:

void worldSetInit(Callback init);

@@ -69,6 +93,14 @@ int main() {

draw — указатель на функцию перерисовки кадра. Функция быть работать без параметров и не должна возвращать значение.

+

void worldSetDeinit(Callback deinit);

+ +

Задать функцию для выполнения каких-либо действий при завершении программы. Эта функция будет запущена только один раз при окончании работы программы, непосредственно перед завершением выполнения функции worldRun.

+ +

Параметры:

+ +

deinit — указатель на функцию которая будет выполнена перед завершением программы.

+

void worldRun();

Запустить вашу программу на Helianthus. Перед вызовом этой функции нужно зарегистрировать функции начальной загрузки и перерисовки кадра (см. выше)

@@ -112,6 +144,30 @@ void draw() {

height — новая ширина окна.

+

int worldGetResizable();

+ +

Возвращает TRUE если пользователь имеет возможность изменять размер окна, в противном случае возвращает FALSE.

+ +

void worldSetResizable(int resizable);

+ +

Включает или выключает возможность измерения размеров окна пользователем. Когда включено пользователь может менять размер окна растягивая его, хватаясь за границы, и, появляется кнопка для разворачивания окна на весь экран.

+ +

Параметры:

+ +

resizable — если TRUE, то разрешает пользователю изменять размер окна.

+ +

const char* worldGetTitle();

+ +

Возвращает установленный ранее заголовок окна (строка текста).

+ +

void worldSetTitle(const char *title);

+ +

Установить заголовок окна.

+ +

Параметры:

+ +

title — новый заголовок окна.

+

double worldGetFrameRate();

Возвращает частоту перерисовки окна, количество кадров в секунду. См. также worldSetFrameRate.

@@ -134,7 +190,7 @@ void draw() {

double worldGetSeconds();

-

Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции worldRun. См. также worldGetFrames.

+

Возвращает количество секунд прошедшее с момента запуска программы (с момента вызова функции worldRun. См. также worldGetFrameCount.

int randomNumber(int min, int max);

@@ -149,6 +205,95 @@ void draw() {

Возвращает случайное дробное число в диапазоне от 0 до 1.

+

Directory openDirectory(const char *path);

+ +

Если папка существует, то функция читает список файлов в папке и сохраняет этот список в памяти. Возвращает значение типа Directory, которое является адресом в памяти — указателем на описание списка внутри библиотеки Helianthus.

+ +

Если папка не существует или её по какой-то причине невозможно открыть, то функция возвращает нулевой указатель (NULL).

+ +

Имена файлов можно получить при помощи функций directoryGetCount и directoryGet. После использования список нужно удалить функцией closeDirectory.

+ +

Пример:

+ +
+Directory dir = openDirectory("my/directory");
+if (dir) {
+    for(int i = 0; i < directoryGetCount(dir); ++i) {
+        printf("file: %s", directoryGet(dir, i));
+    }
+    closeDirectory(dir);
+}
+
+ + +

Параметры:

+ +

path — путь к папке.

+ +

void closeDirectory(Directory directory);

+ +

Удаляет ранее загруженный список файлов из памяти. См. также openDirectory.

+ +

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

+ +

int directoryGetCount(Directory directory);

+ +

Возвращает количество файлов в списке. См. также openDirectory и directoryGet.

+ +

const char* directoryGet(Directory directory, int i);

+ +

Возвращает имя файла с указанным номером из ранее открытого списка. См. также openDirectory и directoryGet.

+ +

Параметры:

+ +

i — номер файла в списке.

+ +

int fileExists(const char *path);

+ +

Возвращает TRUE (число 1) если файл по заданному пути существует, иначе возвращает FALSE (число 0).

+ +

Параметры:

+ +

path — путь к проверяемому файлу.

+ +

int directoryExists(const char *path);

+ +

Возвращает TRUE (число 1) если папке по заданному пути существует, иначе возвращает FALSE (число 0).

+ +

Параметры:

+ +

path — путь к проверяемой папке.

+ +

void messageBox(const char *message);

+ +

Показать окно с текстовым сообщением. Работа программы будет приостановлена, до тех пор пока пользователь не закроет окно (нажав на кнопку OK, например).

+ +

Параметры:

+ +

message — текстовое сообщение.

+ +

void askText(const char *question, char *answer, int maxAnswerSize);

+ +

Создаёт окно для ввода текста. Пользователю будет предоставлена для редактирования строка текста из параметра answer. Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. См. также askTextEx.

+ +

Параметры:

+ +

question — сообщение для пользователя;
+answer — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;
+maxAnswerSize — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт.

+ +

void askTextEx(const char *question, char *answer, int maxAnswerSize, int multiline, int password);

+ +

Создаёт окно для ввода текста. Пользователю будет предоставлен для редактирования текст из параметра answer. Позволяет работать с многострочным текстом и прятать вводимые символы (для ввода пароля). Работа программы будет приостановлена, до тех пор пока пользователь не закончит ввод и не закроет окно. См. также askText.

+ +

Параметры:

+ +

question — сообщение для пользователя;
+answer — указатель на строку куда будет сохранён ответ, также этот параметр используется чтобы задать начальное значение для текстового поля;
+maxAnswerSize — максимальный размер для строки ответа в байтах включая ограничивающий нулевой байт;
+multiline — если TRUE, то будет отображаться поле для ввода многострочного текста;
+password — если TRUE, то вводимые символы будут спрятаны (можно использовать для ввода паролей).

+ diff --git a/doc/ru/drawing.html b/doc/ru/drawing.html index 93f3ece..b165cf9 100644 --- a/doc/ru/drawing.html +++ b/doc/ru/drawing.html @@ -63,7 +63,7 @@ closePath();

Также существуют отдельные функции для рисования прямоугольников, линий, эллипсов и дуг окружности, смотрите описания функций ниже.

-

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

+

Для вывода текста используются функции text, textAlign, textFontFamily и textSize. Смотрите их описание ниже. Вы можете загружать собственные шрифты из файлов (TrueType или OpenType) при помощи функций createFont и textFont.

Функции:

@@ -109,7 +109,7 @@ closePath();

weight — толщина линии.

-

char* rgb(double r, double g, double b);

+

const char* rgb(double r, double g, double b);

Функция возвращает текстовое наименование цвета для заданных числовых значений яркости красной, зелёной и синей составляющих.

@@ -119,7 +119,7 @@ closePath(); g — яркость зелёной составляющей цвета, дробное число от 0 до 1;
b — яркость синей составляющей цвета, дробное число от 0 до 1.

-

char* rgba(double r, double g, double b, double a);

+

const char* rgba(double r, double g, double b, double a);

Функция возвращает текстовое наименование цвета для заданных числовых значений яркости красной, зелёной и синей составляющих, а также прозрачности.

@@ -251,21 +251,51 @@ closePath();     VALIGN_CENTER — начальная точка находится в середине текста;
    VALIGN_BOTTOM — начальная точка находится по нижнему краю текста.

-

void textFont(const char *font);

+

void textSize(double size);

-

Установить шрифт для текста (см. функцию text). Указанный шрифт должен быть установлен в системе. Можете посмотреть списки шрифтов в любом установленном на вашем компьютере текстовом редакторе.

+

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

Параметры:

-

font — текстовое наименование шрифта.

+

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

-

void textSize(double size);

+

void textFontFamily(const char *family);

-

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

+

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

Параметры:

-

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

+

family — текстовое наименование шрифта.

+ +

void textFontDefault();

+ +

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

+ +

Font createFont(const char *path);

+ +

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

+ +

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

+ +

См. также fontDestroy.

+ +

Параметры:

+ +

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

+ +

void fontDestroy(Font font);

+ +

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

+ +

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

+ +

void textFont(Font font);

+ +

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

+ +

Параметры:

+ +

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

diff --git a/doc/ru/functions.html b/doc/ru/functions.html index 9f9b788..da17081 100644 --- a/doc/ru/functions.html +++ b/doc/ru/functions.html @@ -22,12 +22,17 @@

Запуск и общие функции

worldSetInit
worldSetDraw
+worldSetDeinit
worldRun
worldStop
worldGetWidth
worldSetWidth
worldGetHeight
worldSetHeight
+worldGetResizable
+worldSetResizable
+worldGetTitle
+worldSetTitle
worldGetFrameRate
worldSetFrameRate
worldGetTimeStep
@@ -35,6 +40,15 @@ worldGetSeconds
randomNumber
randomFloat
+openDirectory
+closeDirectory
+directoryGetCount
+directoryGet
+fileExists
+directoryExists
+messageBox
+askText
+askTextEx

Клавиатура и мышь

keyDown
keyWentDown
@@ -45,6 +59,8 @@ mouseDidMove
mouseX
mouseY
+keyEventGetCount
+keyEventGet

Рисование

background
fill
@@ -68,8 +84,12 @@ regularPolygon
text
textAlign
-textFont
textSize
+textFontFamily
+textFontDefault
+createFont
+fontDestroy
+textFont

Спрайты

createSprite
createSpriteEx
diff --git a/doc/ru/input.html b/doc/ru/input.html index 4c6ebf2..5cecded 100644 --- a/doc/ru/input.html +++ b/doc/ru/input.html @@ -35,6 +35,23 @@

Кроме этого существуют функции для определения момента нажатия и отпускания клавиш и кнопок. На тот случай когда некоторые действия нужно выполнить только один раз в момент нажатия (или отпускания) клавиши. Смотрите функции keyWentDown, keyWentUp, mouseWentDown, mouseWentUp.

+

Также вы можете получить полный список нажатых, отпущенных или удерживаемых клавиш и кнопок при помощи функций keyEventGetCount и keyEventGet.

+ +

Например, если вы не знаете наименования какой-либо клавиши, вы можете выводить имена нажимаемых клавиш в терминал при помощи такой программы:

+ +
+void draw() {
+    …
+    int count = keyEventCount(KEYEVENT_KEY_WENTDOWN);
+    for(int i = 0; i < count; ++i) {
+        printf( "pressed key: %s",
+            keyEventGet(KEYEVENT_KEY_WENTDOWN, i) );
+    }
+    …
+}
+
+ +

Функции:

int keyDown(const char *code);

@@ -99,6 +116,55 @@

Возвращает координату Y указателя мыши.

+

int keyEventGetCount(KeyEvent mode);

+ +

Возвращает количество зарегистрированных на данном кадре клавиш (или кнопок мыши), соответствующих одному из перечисленных ниже типу событий:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ТипОписание
KEYEVENT_KEY_DOWNудерживаемые в данный момент клавиши, см. keyDown
KEYEVENT_KEY_WENTDOWNклавиши, которые только что стали нажатыми, см. keyWentDown
KEYEVENT_KEY_WENTUPклавиши, которые были только что отпущены, см. keyWentUp
KEYEVENT_MOUSE_DOWNкнопки мыши, которые в данный момент нажаты, см. mouseDown
KEYEVENT_MOUSE_WENTDOWNкнопки мыши, которые только что стали нажатыми, см. mouseWentDown
KEYEVENT_MOUSE_WENTUPкнопки мыши, которые были только что отпущены, см. mouseWentUp
+ + +

Параметры:

+ +

mode — тип событий, см. выше.

+ +

const char* keyEventGet(KeyEvent mode, int i);

+ +

Возвращает наименования клавиши или кнопки мыши из списка событий указанного типа, по указанному номеру. Элементы в списке событий отсортированы по времени возникновения события. То есть клавиши идут в том порядке в котором они были нажаты (или отпущены). См. также keyEventGetCount.

+ +

Параметры:

+ +

mode — тип событий, список типов смотрите в описании функции keyEventGetCount;
+i — порядковой номер клавиши или кнопки в списке для указанного типа, элементы

+ diff --git a/doc/ru/sprites.html b/doc/ru/sprites.html index 67fa452..25aa54d 100644 --- a/doc/ru/sprites.html +++ b/doc/ru/sprites.html @@ -106,7 +106,7 @@ int main() { spritePush Да. Нет. - Первый сайт движется так будто и не было столкновения, второй же отталкивается от первого и меняет свою скорость и направление движения. + Первый спрайт движется так будто и не было столкновения, второй же отталкивается от первого и меняет свою скорость и направление движения. spriteCollideEx