OpenEuphoria

8.3 Console

8.3.1 Information

8.3.1.1 has_console

include std/console.e
namespace console
public function has_console()

Determing if the process has a console window or not

Returns:

1 if there is more than one process attached to the current console, 0 if a console does not exist or only one process (EUPHORIA) is attached to the current console.

Notes:

Method always returns 1 on *nix systems. On Windows client systems earlier than Windows XP the method always returns 0. On Windows server systems earlier than Windows Server 2003 the method always returns 0.

Examples:

include std/console.e

if has_console() then
    printf(1, "Hello Console!")
end if

8.3.1.2 key_codes

include std/console.e
namespace console
public function key_codes(object codes = 0)

Gets and sets the keyboard codes used internally by Euphoria.

Parameters:

1. codes : Either a sequence of exactly 256 integers or an atom (the default).

Returns:

A sequence of the current 256 keyboard codes, prior to any changes that this function might make.

Comments:

When codes is a atom then no change to the existing codes is made, otherwise the set of 256 integers in codes completely replaces the existing codes.

Examples:

include std/console.e
sequence kc
kc = key_codes() -- Get existing set.
kc[KC_LEFT] = 263 -- Change the code for the left-arrow press.
key_codes(kc) -- Set the new codes.

8.3.2 Key Code names.

These are the names of the index values for each of the 256 key code values.

See Also:

key_codes

8.3.2.1 KC_LBUTTON

include std/console.e
namespace console
public constant KC_LBUTTON

8.3.2.2 set_keycodes

include std/console.e
namespace console
public function set_keycodes(object kcfile)

Change the default codes returned by the keyboard.

Parameters:

1. kcfile : Either the name of a text file or the handle of an opened (for reading) text file.

Comments:

The text file is expected to contain bindings for one or more keyboard codes. The format of the files is a set of lines, one line per key binding, in the form KEYNAME = NEWVALUE. The keyname is the same as the constants but without the "KC_" prefix. The key bindings can be in any order.

Returns:

When this function completes without error, zero (0) is returned, otherwise an error code is returned.

• -1 means that the supplied file could not me loaded in to a map.
• -2 means that a new key value was not an integer
• -3 means that an unknown key name was found in the file.

Example 1:

-- doskeys.txt file containing some key bindings
F1 = 260
F2 = 261
INSERT = 456

set_keycodes( "doskeys.txt" )

See Also:

key_codes

8.3.3 Cursor Style Constants

In the cursor constants below, the second and fourth hex digits (from the left) determine the top and bottom row of pixels in the cursor. The first digit controls whether the cursor will be visible or not. For example, #0407 turns on the 4th through 7th rows.

See Also:

cursor

8.3.3.1 NO_CURSOR

include std/console.e
namespace console
public constant NO_CURSOR

8.3.3.2 UNDERLINE_CURSOR

include std/console.e
namespace console
public constant UNDERLINE_CURSOR

8.3.3.3 THICK_UNDERLINE_CURSOR

include std/console.e
namespace console
public constant THICK_UNDERLINE_CURSOR

8.3.3.4 HALF_BLOCK_CURSOR

include std/console.e
namespace console
public constant HALF_BLOCK_CURSOR

8.3.3.5 BLOCK_CURSOR

include std/console.e
namespace console
public constant BLOCK_CURSOR

8.3.4 Keyboard related routines

8.3.4.1 get_key

<built-in> function get_key()

Return the key that was pressed by the user, without waiting. Special codes are returned for the function keys, arrow keys etc.

Returns:

An integer, either -1 if no key waiting, or the code of the next key waiting in keyboard buffer.

Comments:

The operating system can hold a small number of key-hits in its keyboard buffer. get_key() will return the next one from the buffer, or -1 if the buffer is empty.

Run the key.bat program to see what key code is generated for each key on your keyboard.

Example 1:

integer n = get_key()
if n=-1 then
    puts(1, "No key waiting.\n")
end if

See Also:

wait_key

8.3.4.2 allow_break

include std/console.e
namespace console
public procedure allow_break(types :boolean b)

Set behavior of CTRL+C/CTRL+Break

Parameters:

1. b : a boolean, TRUE ( != 0 ) to enable the trapping of Ctrl-C/Ctrl-Break, FALSE ( 0 ) to disable it.

Comments:

When b is 1 (true), CTRL+C and CTRL+Break can terminate your program when it tries to read input from the keyboard. When i is 0 (false) your program will not be terminated by CTRL+C or CTRL+Break.

Initially your program can be terminated at any point where it tries to read from the keyboard.

You can find out if the user has pressed Control-C or Control-Break by calling check_break().

Example 1:

allow_break(0)  -- don't let the user kill the program!

See Also:

check_break

8.3.4.3 check_break

include std/console.e
namespace console
public function check_break()

Returns the number of Control-C/Control-BREAK key presses.

Returns:

An integer, the number of times that CTRL+C or CTRL+Break have been pressed since the last call to check_break(), or since the beginning of the program if this is the first call.

Comments:

This is useful after you have called allow_break(0) which prevents CTRL+C or CTRL+Break from terminating your program. You can use check_break() to find out if the user has pressed one of these keys. You might then perform some action such as a graceful shutdown of your program.

Neither CTRL+C or CTRL+Break will be returned as input characters when you read the keyboard. You can only detect them by calling check_break().

Example 1:

k = get_key()
if check_break() then  -- ^C or ^Break was hit once or more
    temp = graphics_mode(-1)
    puts(STDOUT, "Shutting down...")
    save_all_user_data()
    abort(1)
end if

See Also:

allow_break

8.3.4.4 wait_key

include std/console.e
namespace console
public function wait_key()

Waits for user to press a key, unless any is pending, and returns key code.

Returns:

An integer, which is a key code. If one is waiting in keyboard buffer, then return it. Otherwise, wait for one to come up.

See Also:

get_key, getc

8.3.4.5 any_key

include std/console.e
namespace console
public procedure any_key(sequence prompt = "Press Any Key to continue...", integer con = 1)

Display a prompt to the user and wait for any key.

Parameters:

1. prompt : Prompt to display, defaults to "Press Any Key to continue..."
2. con : Either 1 (stdout), or 2 (stderr). Defaults to 1.

Comments:

This wraps wait_key by giving a clue that the user should press a key, and perhaps do some other things as well.

Example 1:

any_key() -- "Press Any Key to continue..."

Example 2:

any_key("Press Any Key to quit")

See Also:

wait_key

8.3.4.6 maybe_any_key

include std/console.e
namespace console
public procedure maybe_any_key(sequence prompt = "Press Any Key to continue...",
        integer con = 1)

Display a prompt to the user and wait for any key only if the user is running under a GUI environment.

Parameters:

1. prompt : Prompt to display, defaults to "Press Any Key to continue..."
2. con : Either 1 (stdout), or 2 (stderr). Defaults to 1.

Comments:

This wraps wait_key by giving a clue that the user should press a key, and perhaps do some other things as well. Requires Windows XP or later or Windows 2003 or later to work. Earlier versions of Windows or O/S will always pause even when not needed. On the other hand, on Unix like Operating Systems this wont pause even when needed.

Example 1:

any_key() -- "Press Any Key to continue..."

Example 2:

any_key("Press Any Key to quit")

See Also:

wait_key

8.3.4.7 prompt_number

include std/console.e
namespace console
public function prompt_number(sequence prompt, sequence range)

Prompts the user to enter a number, and returns only validated input.

Parameters:

1. st : is a string of text that will be displayed on the screen.
2. s : is a sequence of two values {lower, upper} which determine the range of values that the user may enter. s can be empty, {}, if there are no restrictions.

Returns:

An atom, in the assigned range which the user typed in.

Errors:

If puts() cannot display st on standard output, or if the first or second element of s is a sequence, a runtime error will be raised.

If user tries cancelling the prompt by hitting Ctrl-Z, the program will abort as well, issuing a type check error.

Comments:

As long as the user enters a number that is less than lower or greater than upper, the user will be prompted again.

If this routine is too simple for your needs, feel free to copy it and make your own more specialized version.

Example 1:

age = prompt_number("What is your age? ", {0, 150})

Example 2:

t = prompt_number("Enter a temperature in Celcius:\n", {})

See Also:

puts, prompt_string

8.3.4.8 prompt_string

include std/console.e
namespace console
public function prompt_string(sequence prompt)

Prompt the user to enter a string of text.

Parameters:

1. st : is a string that will be displayed on the screen.

Returns:

A sequence, the string that the user typed in, stripped of any new-line character.

Comments:

If the user happens to type control-Z (indicates end-of-file), "" will be returned.

Example 1:

name = prompt_string("What is your name? ")

See Also:

prompt_number

8.3.5 Cross Platform Text Graphics

8.3.5.1 positive_int

include std/console.e
namespace console
public type positive_int(object x)

8.3.5.2 clear_screen

<built-in> procedure clear_screen()

Clear the screen using the current background color (may be set by bk_color() ).

See Also:

bk_color

8.3.5.3 get_screen_char

include std/console.e
namespace console
public function get_screen_char(positive_atom line, positive_atom column, integer fgbg = 0)

Get the value and attribute of the character at a given screen location.

Parameters:

1. line : the 1-base line number of the location
2. column : the 1-base column number of the location
3. fgbg : an integer, if 0 (the default) you get an attribute_code returned otherwise you get a foreground and background color number returned.

Returns:

• If fgbg is zero then a sequence of two elements, {character, attribute_code} for the specified location.
• If fgbg is not zero then a sequence of three elements, {characterfg_color, bg_color}

Comments:

• This function inspects a single character on the active page.
• The attribute_code is an atom that contains the foreground and background color of the character, and possibly other operating-system dependant information describing the appearance of the character on the screen.
• The fg_color and bg_color are integers in the range 0 to 15, which correspond to...

color number	name
0	black
1	dark blue
2	green
3	cyan
4	crimson
5	purple
6	brown
7	light gray
8	dark gray
9	blue
10	bright green
11	light blue
12	red
13	magenta
14	yellow
15	white

• With get_screen_char() and put_screen_char() you can save and restore a character on the screen along with its attribute_code.

Example 1:

-- read character and attributes at top left corner
s = get_screen_char(1,1)
-- s could be {'A', 92}
-- store character and attributes at line 25, column 10
put_screen_char(25, 10, s)

Example 2:

-- read character and colors at line 25, column 10.
s = get_screen_char(25,10, 1)
-- s could be {'A', 12, 5}

See Also:

put_screen_char, save_text_image

8.3.5.4 put_screen_char

include std/console.e
namespace console
public procedure put_screen_char(positive_atom line, positive_atom column, sequence char_attr)

Stores/displays a sequence of characters with attributes at a given location.

Parameters:

1. line : the 1-based line at which to start writing
2. column : the 1-based column at which to start writing
3. char_attr : a sequence of alternated characters and attribute codes.

Comments:

char_attr must be in the form {character, attribute code, character, attribute code, ...}.

Errors:

The length of char_attr must be a multiple of 2.

Comments:

The attributes atom contains the foreground color, background color, and possibly other platform-dependent information controlling how the character is displayed on the screen. If char_attr has 0 length, nothing will be written to the screen. The characters are written to the active page. It's faster to write several characters to the screen with a single call to put_screen_char() than it is to write one character at a time.

Example 1:

-- write AZ to the top left of the screen
-- (attributes are platform-dependent)
put_screen_char(1, 1, {'A', 152, 'Z', 131})

See Also:

get_screen_char, display_text_image

8.3.5.5 attr_to_colors

include std/console.e
namespace console
public function attr_to_colors(integer attr_code)

Converts an attribute code to its foreground and background color components.

Parameters:

1. attr_code : integer, an attribute code.

Returns:

A sequence of two elements - {fgcolor, bgcolor}

Example 1:

? attr_to_colors(92) --> {12, 5}

See Also:

get_screen_char, colors_to_attr

8.3.5.6 colors_to_attr

include std/console.e
namespace console
public function colors_to_attr(object fgbg, integer bg = 0)

Converts a foreground and background color set to its attribute code format.

Parameters:

1. fgbg : Either a sequence of {fgcolor, bgcolor} or just an integer fgcolor.
2. bg : An integer bgcolor. Only used when fgbg is an integer.

Returns:

An integer attribute code.

Example 1:

? colors_to_attr({12, 5}) --> 92
? colors_to_attr(12, 5) --> 92

See Also:

get_screen_char, put_screen_char, attr_to_colors

8.3.5.7 display_text_image

include std/console.e
namespace console
public procedure display_text_image(text_point xy, sequence text)

Display a text image in any text mode.

Parameters:

1. xy : a pair of 1-based coordinates representing the point at which to start writing
2. text : a list of sequences of alternated character and attribute.

Comments:

This routine displays to the active text page, and only works in text modes.

You might use save_text_image()/display_text_image() in a text-mode graphical user interface, to allow "pop-up" dialog boxes, and drop-down menus to appear and disappear without losing what was previously on the screen.

Example 1:

clear_screen()
display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},
                           {'C', RED+16*WHITE},
                           {'D', BLUE}})
-- displays:
--     AB
--     C
--     D
-- at the top left corner of the screen.
-- 'A' will be white with black (0) background color,
-- 'B' will be green on black,
-- 'C' will be red on white, and
-- 'D' will be blue on black.

See Also:

save_text_image, put_screen_char

8.3.5.8 save_text_image

include std/console.e
namespace console
public function save_text_image(text_point top_left, text_point bottom_right)

Copy a rectangular block of text out of screen memory

Parameters:

1. top_left : the coordinates, given as a pair, of the upper left corner of the area to save.
2. bottom_right : the coordinates, given as a pair, of the lower right corner of the area to save.

Returns:

A sequence, of {character, attribute, character, ...} lists.

Comments:

The returned value is appropriately handled by display_text_image.

This routine reads from the active text page, and only works in text modes.

You might use this function in a text-mode graphical user interface to save a portion of the screen before displaying a drop-down menu, dialog box, alert box etc.

Example 1:

-- Top 2 lines are: Hello and World
s = save_text_image({1,1}, {2,5})

-- s is something like: {"H-e-l-l-o-", "W-o-r-l-d-"}

See Also:

display_text_image, get_screen_char

8.3.5.9 text_rows

include std/console.e
namespace console
public function text_rows(positive_int rows)

Set the number of lines on a text-mode screen.

Parameters:

1. rows : an integer, the desired number of rows.

Platforms:

Not Unix

Returns:

An integer, the actual number of text lines.

Comments:

Values of 25, 28, 43 and 50 lines are supported by most video cards.

See Also:

graphics_mode, video_config

8.3.5.10 cursor

include std/console.e
namespace console
public procedure cursor(integer style)

Select a style of cursor.

Parameters:

1. style : an integer defining the cursor shape.

Platform:

Not Unix

Comments:

In pixel-graphics modes no cursor is displayed.

Example 1:

cursor(BLOCK_CURSOR)

Cursor Type Constants:

• NO_CURSOR
• UNDERLINE_CURSOR
• THICK_UNDERLINE_CURSOR
• HALF_BLOCK_CURSOR
• BLOCK_CURSOR

See Also:

graphics_mode, text_rows

8.3.5.11 free_console

include std/console.e
namespace console
public procedure free_console()

Free (delete) any console window associated with your program.

Comments:

Euphoria will create a console text window for your program the first time that your program prints something to the screen, reads something from the keyboard, or in some way needs a console. On WINDOWS this window will automatically disappear when your program terminates, but you can call free_console() to make it disappear sooner. On Linux or FreeBSD, the text mode console is always there, but an xterm window will disappear after Euphoria issues a "Press Enter" prompt at the end of execution.

On Unix-style systems, free_console() will set the terminal parameters back to normal, undoing the effect that curses has on the screen.

In an xterm window, a call to free_console(), without any further printing to the screen or reading from the keyboard, will eliminate the "Press Enter" prompt that Euphoria normally issues at the end of execution.

After freeing the console window, you can create a new console window by printing something to the screen, or simply calling clear_screen(), position() or any other routine that needs a console.

When you use the trace facility, or when your program has an error, Euphoria will automatically create a console window to display trace information, error messages etc.

There's a WINDOWS API routine, FreeConsole() that does something similar to free_console(). You should use free_console() instead, because it lets the interpreter know that there is no longer a console to write to or read from.

See Also:

clear_screen

8.3.5.12 display

include std/console.e
namespace console
public procedure display(object data_in, object args = 1, integer finalnl = - 918_273_645)

Displays the supplied data on the console screen at the current cursor position.

Parameters:

1. data_in : Any object.
2. args : Optional arguments used to format the output. Default is 1.
3. finalnl : Optional. Determines if a new line is output after the data. Default is to output a new line.

Comments:

• If data_in is an atom or integer, it is simply displayed.
• If data_in is a simple text string, then args can be used to produce a formatted output with data_in providing the text:format string and args being a sequence containing the data to be formatted.
  • If the last character of data_in is an underscore character then it is stripped off and finalnl is set to zero. Thus ensuring that a new line is not output.
  • The formatting codes expected in data_in are the ones used by text:format. It is not mandatory to use formatting codes, and if data_in does not contain any then it is simply displayed and anything in args is ignored.
• If data_in is a sequence containing floating-point numbers, sub-sequences or integers that are not characters, then data_in is forwarded on to the pretty_print() to display.
  • If args is a non-empty sequence, it is assumed to contain the pretty_print formatting options.
  • if args is an atom or an empty sequence, the assumed pretty_print formatting options are assumed to be {2}.

After the data is displayed, the routine will normally output a New Line. If you want to avoid this, ensure that the last parameter is a zero. Or to put this another way, if the last parameter is zero then a New Line will not be output.

Examples:

display("Some plain text")
        -- Displays this string on the console plus a new line.
display("Your answer:",0)  
       -- Displays this string on the console without a new line.
display("cat")
display("Your answer:",,0) 
        -- Displays this string on the console without a new line.
display("")
display("Your answer:_")   
       -- Displays this string, 
       -- except the '_', on the console without a new line.
display("dog")
display({"abc", 3.44554}) 
       -- Displays the contents of 'res' on the console.
display("The answer to [1] was [2]", {"'why'", 42}) 
       -- formats these with a new line.
display("",2)
display({51,362,71}, {1})

Output would be ...

Some plain text
Your answer:cat
===== Your answer:
Your answer:dog
{
"abc",
3.44554
}
The answer to 'why' was 42
""
{51'3',362,71'G'}