routine or constant name search

8.3 Console

8.3.1 Information

8.3.1.1 has_console

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

determines if the process has a console (terminal) window.

Returns:

An atom,

  • 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.
Comments:
  • On Unix systems always returns 1 .
  • On Windows client systems earlier than Windows XP the function always returns 0 .
  • On Windows server systems earlier than Windows Server 2003 the function always returns 0 .
Example 1:
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.

Example 1:
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)

changes 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.
Returns:

An integer,

  • 0 means no error.
  • -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.
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.

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 cursor constants 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.

Note: Windows only.

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()

returns the key that was pressed by the user, without waiting. Special codes are returned for the function keys, arrow keys, and so on.

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 .../euphoria/demo/key.ex 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)

sets the behavior of Control+C and Control+Break keys.

Parameters:
  1. b : a boolean, TRUE ( != 0 ) to enable the trapping of Control+C and Control+Break, FALSE ( 0 ) to disable it.
Comments:

When b is 1 (true), Control+C and Control+Break can terminate your program when it tries to read input from the keyboard. When b is 0 (false) your program will not be terminated by Control+C or Control+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 and Control+Break key presses.

Returns:

An integer, the number of times that Control+C or Control+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 Control+C or Control+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 Control+C nor Control+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)

displays a prompt to the user and waits 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)

displays a prompt to the user and waits 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 Unix systems this will not pause even when needed.

Example 1:
maybe_any_key() -- "Press Any Key to continue..."
Example 2:
maybe_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 = {})

Displays a prompts then waits for the user to enter a number, which is returned.

Parameters:
  1. prompt : is a string of text that will be displayed on the screen before accepting the user's response.
  2. range : is either an empty sequence (the default), or a sequence of exactly two atoms {lower, upper} that determine the range of values that the user is allowed enter. If range is empty, {}, there are no restrictions.
Returns:

An atom. The number that the user entered. A sequence. The user cancelled the prompt by pressing Control+Z.

Errors:

If puts cannot display prompt on standard output, or if either element of range is a sequence, a runtime error will be raised.

Comments:

If the user enters a number that is outside the range, the user will be prompted again.

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)

prompts the user to enter a string of text.

Parameters:
  1. prompt : 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()

clears the screen using the current background color.

Comments:

The background color can 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)

gets 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.
  • With get_screen_char and put_screen_char you can save and restore a character on the screen along with its attribute_code.
  • The fg_color and bg_color are integers in the range 0 to 15 which correspond to the values in the table:

Color Table

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
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 and 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 two.

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 is 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, an 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)

displays 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 and 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)

copies 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, and so on.

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)

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

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

Windows

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)

selects a style of cursor.

Parameters:
  1. style : an integer defining the cursor shape.
Platform:

Windows

Comments:

In pixel-graphics modes no cursor is displayed.

Example 1:
cursor(BLOCK_CURSOR)

Cursor Type Constants:

See Also:

graphics_mode, text_rows

8.3.5.11 free_console

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

frees (deletes) 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 Unix 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 free_console will set the terminal parameters back to normal, undoing the effect that curses has on the screen.

In a Unix terminal 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, 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, and so on.

There is a WINDOWS API routine, FreeConsole() that does something similar to free_console. Use the Euphoria free_console 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.

Example 1:
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'}