Subversion Repositories Kolibri OS

Compare Revisions

Regard whitespace Rev 2598 → Rev 2599

/programs/develop/libraries/console/console.txt
File deleted
/programs/develop/libraries/console/console_en.txt
0,0 → 1,162
console.obj exports the following functions
 
typedef unsigned long dword; /* 32-bit unsigned integer */
typedef unsigned short word; /* 16-bit unsigned integer */
 
void __stdcall con_init(dword wnd_width, dword wnd_height,
dword scr_width, dword scr_height, const char* title);
Console initialization. Must be called only once.
wnd_width, wnd_height - width and height (in units of characters) of the visible region;
scr_width, scr_height - width and height (in units of characters) of console;
Any of these four parameters can be set to -1 (=0xFFFFFFFF)
to use the library's default values;
title - console window's caption.
 
void __stdcall con_exit(bool bCloseWindow);
You should call this funstion at the end of the program.
If bCloseWindow is zero, the string "[Finished]" will be added to the caption of the window
and the console window will remain on the screen until the user
closes it.
 
void __stdcall con_set_title(const char* title);
Set new window caption.
 
void __stdcall con_write_asciiz(const char* string);
Display ASCIIZ-string to the console at the current position, shifting
the current position.
 
void __stdcall con_write_string(const char* string, dword length);
Similar to con_write_asciiz, but length of the string must be given as a separate parameter
 
int __cdecl con_printf(const char* format, ...)
Standard "printf" function from ANSI C.
 
dword __stdcall con_get_flags(void);
Get output flags.
dword __stdcall con_set_flags(dword new_flags);
Set output flags. This function returns previous values.
Flags (bitmask):
/* text color */
#define CON_COLOR_BLUE 0x01
#define CON_COLOR_GREEN 0x02
#define CON_COLOR_RED 0x04
#define CON_COLOR_BRIGHT 0x08
/* background color */
#define CON_BGR_BLUE 0x10
#define CON_BGR_GREEN 0x20
#define CON_BGR_RED 0x40
#define CON_BGR_BRIGHT 0x80
/* output controls */
#define CON_IGNORE_SPECIALS 0x100
/* if this flag is cleared, function interprets special characters:
10 ('\n') - next line
13 ('\r') - carriage return
8 ('\b') - backspace
9 ('\t') - tab
27 ('\033' = '\x1B') - the beginning of Esc-sequences;
otherwise, these characters will be displayed like ordinary characters. */
/* Supported Esc-sequences:
Esc[<number1>;<number2>;<number3>m - choice of character attributes:
You can specify one, two or three codes in any order;
0 = normal mode (white on black)
1 = bright selection
5 = bright background
7 = inverse mode (black on white)
30 = black characters
31 = red characters
32 = green characters
33 = brown characters
34 = blue characters
35 = purple characters
36 = turqoise characters
37 = white characters
40 = black background
41 = red background
42 = green background
43 = brown background
44 = blue background
45 = purple background
46 = turqoise background
47 = white background
The following sequences appeared in version 5 of library:
Esc[2J - clear screen, move cursor to upper left corner
Esc[<number1>;<number2>H = Esc[<number1>;<number2>f -
move cursor to <number1>,<number2>
Esc[<number>A - move cursor to <number> lines up
Esc[<number>B - move cursor to <number> lines down
Esc[<number>C - move cursor to <number> positions right
Esc[<number>D - move cursor to <number> positions left
*/
/* signal "console closed"; appeared in version 6;
ignored by con_set_flags */
#define CON_WINDOW_CLOSED 0x200
The default value for flags = 7. (grey text on black background)
 
int __stdcall con_get_font_height(void);
Get the height of the font.
 
int __stdcall con_get_cursor_height(void);
Get the height of the cursor.
int __stdcall con_set_cursor_height(int new_height);
Set the height of the cursor. This function returns previous value.
An attempt to set the value out of the correct interval (from 0 to
font_height-1) is ignored.
Cursor with zero height isn't displayed.
Default value: - 15% from font height.
 
int __stdcall con_getch(void);
Get one character from the keyboard.
 
For normal characters function returns ASCII-code. For extended
characters (eg, Fx, and arrows), first function call returns 0
and second call returns the extended code (similar to the DOS-function
input). Starting from version 7, after closing the console window,
this function returns 0.
 
word __stdcall con_getch2(void);
Reads a character from the keyboard. Low byte contains the ASCII-code
(0 for extended characters), high byte - advanced code (like in BIOS
input functions). Starting from version 7, after closing the console
window, this function returns 0.
 
int __stdcall con_kbhit(void);
Returns 1 if a key was pressed, 0 otherwise. To read pressed keys use
con_getch and con_getch2. Starting from version 6, after closing
the console window, this function returns 1.
 
char* __stdcall con_gets(char* str, int n);
Reads a string from the keyboard. Reading is interrupted when got
"new line" character, or after reading the (n-1) characters (depending on
what comes first). In the first case the newline is also recorded in the
str. The acquired line is complemented by a null character.
Starting from version 6, the function returns a pointer to the entered
line if reading was successful, and NULL if the console window was closed.
 
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);
Con_gets completely analogous, except that when the user
press unrecognized key, it calls the specified callback-procedure
(which may, for example, handle up / down for history and tab to enter
autocompletion). You should pass to the procedure: key code and three pointers
- to the string, to the maximum length and to the current position.
function may change the contents of string and may change the string
itself (for example, to reallocate memory for increase the limit),
maximum length, and position of the line - pointers are passed for it.
Return value: 0 = line wasn't changed 1 = line changed, you should
remove old string and display new, 2 = line changed, it is necessary
to display it; 3 = immediately exit the function.
Starting from version 6, the function returns a pointer to the entered
line with the successful reading, and NULL if the console window was closed.
 
void __stdcall con_cls();
Clear screen and set cursor at upper left corner.
 
 
void __stdcall con_get_cursor_pos(int* px, int* py);
Wrote current (x) coordinate of cursor to *px, and (y) to *py.
 
void __stdcall con_set_cursor_pos(int x, int y);
Set the cursor position to the specified coordinates. If any of the
parameters beyond the relevant range (from 0 to 1 scr_width-
for x, from 0 to 1 for scr_height-y, scr_width scr_height and were asked if
call con_init), then the corresponding coordinate of the cursor does not change.
/programs/develop/libraries/console/console_ru.txt
0,0 → 1,165
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), òî ñîîòâåòñòâóþùàÿ êîîðäèíàòà êóðñîðà íå ìåíÿåòñÿ.