forked from KolibriOS/kolibrios
ec273ce904
New function 'con_get_input' useful to get escape codes from special keys. Implemented alternative screen buffer. See included documentation for more details. git-svn-id: svn://kolibrios.org@9105 a494cfbc-eb01-0410-851d-a64ba20cac60
187 lines
8.1 KiB
Plaintext
187 lines
8.1 KiB
Plaintext
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 = yellow characters
|
|
34 = blue characters
|
|
35 = magenta characters
|
|
36 = cyan characters
|
|
37 = white characters
|
|
40 = black background
|
|
41 = red background
|
|
42 = green background
|
|
43 = yellow background
|
|
44 = blue background
|
|
45 = magenta background
|
|
46 = cyan background
|
|
47 = white background
|
|
The following sequences appeared in version 5 of library:
|
|
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
|
|
Esc[<number1>;<number2>H = Esc[<number1>;<number2>f -
|
|
move cursor to <number1>,<number2>
|
|
Esc[2J - clear screen, move cursor to upper left corner
|
|
The following sequences appeared in version 9 of library:
|
|
Esc[J or Esc[0J - Erase everything below cursor
|
|
Esc[1J - Erase everything above cursor
|
|
Esc[K - Erase in line
|
|
Esc[<number>L - Insert <number> lines at the cursor position
|
|
Esc[<number>M - Delete <number> lines at the cursor position
|
|
Esc[<number>P - Delete <number chars at the cursor position
|
|
Esc[<number>X - Erase <number chars at the cursor position
|
|
Esc[<number>d - Set cursor to absolute line position
|
|
Esc[<number1>;<number2>f - Cursor position
|
|
Esc[<mode>h - Set mode (see below)
|
|
Esc[<mode>l - Reset mode (see below)
|
|
The following modes are currently supported:
|
|
?1 - Application cursor keys
|
|
?25 - Show/Hide cursor
|
|
?1049 - Alternative screen buffer. The alternative buffer has no scrollback.
|
|
Esc[<number1>;<number2>r - Set scroll region from row <number1> to row <number2>
|
|
(Use in combination with insert/delete lines)
|
|
Esc]0<string>ST/BEL - Set window caption. The string is terminated with ASCII char 0x07 or 0x9C.
|
|
Esc]2<string>ST/BEL - Implemented identical as Esc]0.
|
|
*/
|
|
/* 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.
|
|
|
|
int __stdcall con_get_input(char* buf, int buflen);
|
|
Read as many input events as are available and fit in the receive buffer.
|
|
Input event can be regular ASCII code from keyboard, but also escape codes for special keys.
|
|
The support for mouse events via escape codes is not yet implemented. |