OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.2 Command Line Handling | Up: 8 API Reference | 8.4 Date and Time > | 9 Release Notes >>

## 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:

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

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'}

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.2 Command Line Handling | Up: 8 API Reference | 8.4 Date and Time > | 9 Release Notes >>