kolibrios-gitea/programs/develop/libraries/console/console.txt
Evgeny Grechnikov (Diamond) 0dc8dae83d console library version 7; console examples updated
git-svn-id: svn://kolibrios.org@1145 a494cfbc-eb01-0410-851d-a64ba20cac60
2009-08-27 16:05:05 +00:00

166 lines
7.2 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

console.obj экспортирует следующие функции:
typedef unsigned long dword; /* 32-битное беззнаковое целое */
typedef unsigned short word; /* 16-битное беззнаковое целое */
void __stdcall con_init(dword wnd_width, dword wnd_height,
dword scr_width, dword scr_height, const char* title);
Инициализация консоли. Вызывается один раз в начале программы.
wnd_width, wnd_height - высота и ширина (в символах) видимой в окне консоли
области;
scr_width, scr_height - высота и ширина (в символах) всей консоли;
любые из первых 4 параметров могут быть установлены в -1 (=0xFFFFFFFF)
- использовать значения по умолчанию;
title - заголовок окна консоли.
void __stdcall con_exit(bool bCloseWindow);
Вызывается при завершении программы. Если (байтовый) параметр bCloseWindow
нулевой, то окно консоли остаётся на экране до того момента, как пользователь
пожелает закрыть его, при этом к заголовку добавляется строка " [Finished]".
void __stdcall con_set_title(const char* title);
Устанавливает новый заголовок окна консоли.
void __stdcall con_write_asciiz(const char* string);
Выводит ASCIIZ-строку в консоль в текущую позицию, продвигает текущую позицию.
void __stdcall con_write_string(const char* string, dword length);
Аналогично con_write_asciiz, но выводит ровно length символов.
int __cdecl con_printf(const char* format, ...)
Стандартная printf из ANSI C.
dword __stdcall con_get_flags(void);
Получает значение флагов вывода.
dword __stdcall con_set_flags(dword new_flags);
Устанавливает значение флагов вывода. Возвращает старое значение.
Флаги (битовая маска):
/* цвет текста */
#define CON_COLOR_BLUE 1
#define CON_COLOR_GREEN 2
#define CON_COLOR_RED 4
#define CON_COLOR_BRIGHT 8
/* цвет фона */
#define CON_BGR_BLUE 0x10
#define CON_BGR_GREEN 0x20
#define CON_BGR_RED 0x40
#define CON_BGR_BRIGHT 0x80
/* управление выводом */
#define CON_IGNORE_SPECIALS 0x100
/* Если флаг сброшен, функция интерпретирует специальные символы:
10 ('\n') - перевод в начало следующей строки
13 ('\r') - перевод в начало текущей строки
8 ('\b') - забой (на символ назад)
9 ('\t') - табуляция
27 ('\033'='\x1B') - начало Esc-последовательности;
иначе выводит их как обычные символы. */
/* Поддерживаемые Esc-последовательности:
Esc[<number1>;<number2>;<number3>m - выбор атрибутов символов:
можно указывать один, два или три кода в любом порядке;
0 = нормальное изображение (белые символы на чёрном фоне)
1 = выделение яркостью
5 = яркий фон
7 = реверсное изображение (чёрные символы на белом фоне)
30 = чёрные символы
31 = красные символы
32 = зелёные символы
33 = коричневые символы
34 = синие символы
35 = фиолетовые символы
36 = бирюзовые символы
37 = белые символы
40 = чёрный фон
41 = красный фон
42 = зелёный фон
43 = коричневый фон
44 = синий фон
45 = фиолетовый фон
46 = бирюзовый фон
47 = белый фон
Следующие последовательности появились в версии 5 библиотеки:
Esc[2J - очистить экран, переместить курсор в левый верхний угол
Esc[<number1>;<number2>H = Esc[<number1>;<number2>f -
установить курсор в позицию с координатами <number1>,<number2>
Esc[<number>A - переместить курсор на <number> строк вверх
Esc[<number>B - переместить курсор на <number> строк вниз
Esc[<number>C - переместить курсор на <number> позиций вправо
Esc[<number>D - переместить курсор на <number> позиций влево
*/
/* сигнал о закрытии окна консоли; появился в версии 6 библиотеки;
флаг игнорируется функцией con_set_flags */
#define CON_WINDOW_CLOSED 0x200
Значение по умолчанию для флагов = 7.
int __stdcall con_get_font_height(void);
Возвращает значение высоты шрифта.
int __stdcall con_get_cursor_height(void);
Получает значение высоты курсора.
int __stdcall con_set_cursor_height(int new_height);
Устанавливает значение высоты курсора. Возвращает старое значение.
Попытка установить значение вне корректного интервала (от 0 до font_height-1)
игнорируется.
Курсор высоты 0 не отображается на экране.
Значение высоты по умолчанию - 15% от высоты шрифта.
int __stdcall con_getch(void);
Считывает один символ с клавиатуры.
Для обычных символов возвращается ASCII-код. Для расширенных символов
(например, Fx и стрелочек) первый вызов функции возвращает 0,
а повторный вызов возвращает расширенный код (подобно DOS-функциям ввода).
Начиная с версии 7 библиотеки, после закрытия окна консоли возвращается
значение 0.
word __stdcall con_getch2(void);
Считывает один символ с клавиатуры. Младший байт содержит ASCII-код клавиши
(0 для расширенных символов), старший - расширенный код
(подобно BIOS-функциям ввода).
Начиная с версии 7 библиотеки, после закрытия окна консоли возвращается
значение 0.
int __stdcall con_kbhit(void);
Возвращает 1, если какая-то клавиша была нажата, 0 иначе. Для считывания
нажатой клавиши предназначены функции con_getch и con_getch2.
Начиная с версии 6 библиотеки, после закрытия окна консоли всегда возвращает 1.
char* __stdcall con_gets(char* str, int n);
Считывает строку с клавиатуры. Ввод прерывается при поступлении символа
новой строки, а также по прочтении n-1 символа (в зависимости от того, что
произойдёт раньше). В первом случае символ новой строки также записывается в
str. Считанная строка дополняется нулевым символом.
Начиная с версии 6 библиотеки, функция возвращает указатель на введённую
строку при успешном чтении и NULL, если окно консоли было закрыто. До версии
6 возвращаемое значение было неопределено.
typedef int (__stdcall * con_gets2_callback)(int keycode, char** pstr, int* pn, int* ppos);
char* __stdcall con_gets2(con_gets2_callback callback, char* str, int n);
Функция появилась в версии 4 библиотеки.
Полностью аналогична con_gets за исключением того, что когда пользователь
нажимает нераспознанную клавишу, вызывается указанная callback-процедура
(которая может, например, обрабатывать up/down для истории ввода и tab для
автодополнения). Процедуре передаётся код клавиши и три указателя - на строку,
на лимит и на текущую позицию в строке. Процедура может менять содержимое
строки и может менять саму строку (например, перераспределить память для
увеличения лимита), лимит, позицию в строке - для этого и передаются указатели.
Возвращаемое значение: 0=строка не менялась; 1=строка изменилась, необходимо
удалить старую и вывести новую; 2=строка изменилась, необходимо её вывести;
3=немедленно выйти из функции.
Начиная с версии 6 библиотеки, функция возвращает указатель на введённую
строку при успешном чтении и NULL, если окно консоли было закрыто. До версии
6 возвращаемое значение было неопределено.
void __stdcall con_cls();
Функция появилась в версии 5 библиотеки.
Очищает экран и переводит курсор в левый верхний угол.
void __stdcall con_get_cursor_pos(int* px, int* py);
Функция появилась в версии 5 библиотеки.
Записывает в *px текущую координату курсора по оси x, в *py - по оси y.
void __stdcall con_set_cursor_pos(int x, int y);
Функция появилась в версии 5 библиотеки.
Устанавливает курсор в позицию с указанными координатами. Если какой-то из
параметров выходит за пределы соответствующего диапазона (от 0 до scr_width-1
для x, от 0 до scr_height-1 для y, scr_width и scr_height были заданы при
вызове con_init), то соответствующая координата курсора не меняется.