| Platform: | DOS32 |
| Syntax: | include graphics.e ellipse(i1, i2, s1, s2) |
| Description: | Draw an ellipse with color i1 on a pixel-graphics screen. The ellipse will neatly fit inside the rectangle defined by diagonal points s1 {x1, y1} and s2 {x2, y2}. If the rectangle is a square then the ellipse will be a circle. Fill the ellipse when i2 is 1. Don't fill when i2 is 0. |
| Example: | |
ellipse(MAGENTA, 0, {10, 10}, {20, 20})
-- This would make a magenta colored circle just fitting
-- inside the square:
-- {10, 10}, {10, 20}, {20, 20}, {20, 10}.
| |
| Example Program: | demo\dos32\sb.ex |
| See Also: | polygon, draw_line |
| Syntax: | i = equal(x1, x2) |
| Description: | Compare two Euphoria objects to see if they are the same. Return 1 (true) if they are the same. Return 0 (false) if they are different. |
| Comments: | This is equivalent to the expression: compare(x1, x2) = 0
This routine, like most other built-in routines, is very fast. It does not have any subroutine call overhead. |
| Example 1: | |
if equal(PI, 3.14) then
puts(1, "give me a better value for PI!\n")
end if
| |
| Example 2: | |
if equal(name, "George") or equal(name, "GEORGE") then
puts(1, "name is George\n")
end if
| |
| See Also: | compare, equals operator (=) |
| Syntax: | i = find(x, s) |
| Description: | Find x as an element of s. If successful, return the index of the first element of s that matches. If unsuccessful return 0. |
| Example 1: | |
location = find(11, {5, 8, 11, 2, 3})
-- location is set to 3
| |
| Example 2: | |
names = {"fred", "rob", "george", "mary", ""}
location = find("mary", names)
-- location is set to 4
| |
| See Also: | match, compare |
| Syntax: | include machine.e a1 = float32_to_atom(s) |
| Description: | Convert a sequence of 4 bytes to an atom. These 4 bytes must contain an IEEE floating-point number in 32-bit format. |
| Comments: | Any 32-bit IEEE floating-point number can be converted to an atom. |
| Example: | |
f = repeat(0, 4)
fn = open("numbers.dat", "rb") -- read binary
f[1] = getc(fn)
f[2] = getc(fn)
f[3] = getc(fn)
f[4] = getc(fn)
a = float32_to_atom(f)
| |
| See Also: | float64_to_atom, atom_to_float32 |
| Syntax: | include machine.e a1 = float64_to_atom(s) |
| Description: | Convert a sequence of 8 bytes to an atom. These 8 bytes must contain an IEEE floating-point number in 64-bit format. |
| Comments: | Any 64-bit IEEE floating-point number can be converted to an atom. |
| Example: | |
f = repeat(0, 8)
fn = open("numbers.dat", "rb") -- read binary
for i = 1 to 8 do
f[i] = getc(fn)
end for
a = float64_to_atom(f)
| |
| See Also: | float32_to_atom, atom_to_float64 |
| Syntax: | x2 = floor(x1) |
| Description: | Return the greatest integer less than or equal to x1. (Round down to an integer.) |
| Comments: | This function may be applied to an atom or to all elements of a sequence. |
| Example: | |
y = floor({0.5, -1.6, 9.99, 100})
-- y is {0, -2, 9, 100}
| |
| See Also: | remainder |
| Syntax: | include file.e flush(fn) |
| Description: | When you write data to a file, Euphoria normally stores the data in a memory buffer until a large enough chunk of data has accumulated. This large chunk can then be written to disk very efficiently. Sometimes you may want to force, or flush, all data out immediately, even if the memory buffer is not full. To do this you must call flush(fn), where fn is the file number of a file open for writing or appending. |
| Comments: | When a file is closed, (see close()), all buffered data is flushed out.
When a program terminates, all open files are flushed and closed
automatically. Use flush() when another process may need to see all of the data written so far, but you aren't ready to close the file yet. |
| Example: | |
f = open("logfile", "w")
puts(f, "Record#1\n")
puts(1, "Press Enter when ready\n")
flush(f) -- This forces "Record #1" into "logfile" on disk.
-- Without this, "logfile" will appear to have
-- 0 characters when we stop for keyboard input.
s = gets(0) -- wait for keyboard input
| |
| See Also: | close, lock_file |
| Syntax: | include machine.e free(a) |
| Description: | Free up a previously allocated block of memory by specifying the address of the start of the block, i.e. the address that was returned by allocate(). |
| Comments: | Use free() to recycle blocks of memory during execution. This
will reduce the chance of running out of memory or getting into
excessive virtual memory swapping to disk. Do not reference
a block of memory that has been freed. When your program
terminates, all allocated memory will be returned to the system.
Do not use free() to deallocate memory that was allocated using allocate_low(). Use free_low() for this purpose. |
| Example Program: | demo\callmach.ex |
| See Also: | allocate, free_low |
| Platform: | WIN32, Linux, FreeBSD |
| Syntax: | include dll.e free_console() |
| Description: | 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 (similar to a DOS-prompt window). On WIN32 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 Linux or FreeBSD, free_console() will set the terminal parameters back to normal, undoing the effect that curses has on the screen. In a Linux or FreeBSD 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 WIN32 API routine, FreeConsole() that does something similar to free_console(). You should use free_console(), because it lets the interpreter know that there is no longer a console. |
| See Also: | clear_screen, platform.doc |
| Platform: | DOS32 |
| Syntax: | include machine.e free_low(i) |
| Description: | Free up a previously allocated block of conventional memory by specifying the address of the start of the block, i.e. the address that was returned by allocate_low(). |
| Comments: | Use free_low() to recycle blocks of conventional memory during
execution. This will reduce the chance of running out of
conventional memory. Do not reference a block of memory that has
been freed. When your program terminates, all allocated memory
will be returned to the system.
Do not use free_low() to deallocate memory that was allocated using allocate(). Use free() for this purpose. |
| Example Program: | demo\dos32\dosint.ex |
| See Also: | allocate_low, dos_interrupt, free |
| Syntax: | include get.e s = get(fn) |
| Description: | Input, from file fn, a human-readable string of characters representing a Euphoria object. Convert the string into the numeric value of that object. s will be a 2-element sequence: {error status, value}. Error status codes are: |
GET_SUCCESS -- object was read successfully
GET_EOF -- end of file before object was read
GET_FAIL -- object is not syntactically correct
| |
| get() can read arbitrarily complicated Euphoria objects. You
could have a long sequence of values in braces and separated by
commas, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}.
A single call to get() will read in this
entire sequence and return it's value as a result.
Each call to get() picks up where the previous call left off. For instance, a series of 5 calls to get() would be needed to read in: 99 5.2 {1,2,3} "Hello" -1 On the sixth and any subsequent call to get() you would see a GET_EOF status. If you had something like: {1, 2, xxx} in the input stream you would see a GET_FAIL error status because xxx is not a Euphoria object. Multiple "top-level" objects in the input stream must be separated from each other with one or more "whitespace" characters (blank, tab, \r or \n). Whitespace is not necessary within a top-level object. A call to get() will read one entire top-level object, plus one additional (whitespace) character. | |
| Comments: | The combination of print() and get() can be used to save a
Euphoria object to disk and later read it back. This technique
could be used to implement a database as one or more large
Euphoria sequences stored in disk files. The sequences could be
read into memory, updated and then written back to disk after
each series of transactions is complete. Remember to write out
a whitespace character (using puts()) after each call to print().
The value returned is not meaningful unless you have a GET_SUCCESS status. |
| Example: | Suppose your program asks the user to enter a number from the keyboard. |
-- If he types 77.5, get(0) would return:
{GET_SUCCESS, 77.5}
-- whereas gets(0) would return:
"77.5\n"
| |
| Example Program: | demo\mydata.ex |
| See Also: | print, value, gets, getc, prompt_number, prompt_string |
| Platform: | DOS32 |
| Syntax: | include image.e i = get_active_page() |
| Description: | Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying a different page. get_active_page() returns the current page number that screen output is being sent to. |
| Comments: | The active and display pages are both 0 by default.
video_config() will tell you how many pages are available in the current graphics mode. |
| See Also: | set_active_page, get_display_page, video_config |
| Platform: | DOS32 |
| Syntax: | include image.e s = get_all_palette() |
| Description: | Retrieve color intensities for the entire set of colors in the current
graphics mode. s is a sequence of the form: {{r,g,b}, {r,g,b}, ..., {r,g,b}} Each element specifies a color intensity {red, green, blue} for the corresponding color number, starting with color number 0. The values for red, green and blue will be in the range 0 to 63. |
| Comments: | This function might be used to get the palette values needed by save_bitmap(). Remember to multiply these values by 4 before calling save_bitmap(), since save_bitmap() expects values in the range 0 to 255. |
| See Also: | palette, all_palette, read_bitmap, save_bitmap, save_screen |
| Syntax: | include get.e s = get_bytes(fn, i) |
| Description: | Read the next i bytes from file number fn. Return the bytes as a sequence. The sequence will be of length i, except when there are fewer than i bytes remaining to be read in the file. |
| Comments: | When i > 0 and length(s) < i you know
you've reached the end of file. Eventually, an
empty sequence will be returned
for s.
This function is normally used with files opened in binary mode, "rb". This avoids the confusing situation in text mode where DOS will convert CR LF pairs to LF. |
| Example: | |
include get.e
integer fn
fn = open("temp", "rb") -- an existing file
sequence whole_file
whole_file = {}
sequence chunk
while 1 do
chunk = get_bytes(fn, 100) -- read 100 bytes at a time
whole_file &= chunk -- chunk might be empty, that's ok
if length(chunk) < 100 then
exit
end if
end while
close(fn)
? length(whole_file) -- should match DIR size of "temp"
| |
| See Also: | getc, gets |
| Platform: | DOS32 |
| Syntax: | include image.e i = get_display_page() |
| Description: | Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying another. get_display_page() returns the current page number that is being displayed on the monitor. |
| Comments: | The active and display pages are both 0 by default.
video_config() will tell you how many pages are available in the current graphics mode. |
| See Also: | set_display_page, get_active_page, video_config |
| Syntax: | i = get_key() |
| Description: | Return the key that was pressed by the user, without waiting. Return -1 if no key was pressed. Special codes are returned for the function keys, arrow keys etc. |
| 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. |
| See Also: | wait_key, getc |
| Platform: | DOS32, Linux |
| Syntax: | include mouse.e x1 = get_mouse() |
| Description: | Return the last mouse event in the form: {event, x, y} or
return -1 if there has not been a mouse event since the last
time get_mouse() was called.
Constants have been defined in mouse.e for the possible mouse events: |
global constant MOVE = 1,
LEFT_DOWN = 2,
LEFT_UP = 4,
RIGHT_DOWN = 8,
RIGHT_UP = 16,
MIDDLE_DOWN = 32,
MIDDLE_UP = 64
| |
| x and y are the coordinates of the mouse pointer at the time that
the event occurred. get_mouse() returns immediately with either
a -1 or a mouse event. It does not wait for an event to occur.
You must check it frequently enough to avoid missing an event.
When the next event occurs, the current event will be lost, if
you haven't read it. In practice it is not hard to catch almost
all events. Losing a MOVE event is generally not too serious,
as the next MOVE will tell you where the mouse pointer is.
Sometimes multiple events will be reported. For example, if the mouse is moving when the left button is clicked, get_mouse() will report an event value of LEFT_DOWN+MOVE, i.e. 2+1 or 3. For this reason you should test for a particular event using and_bits(). See examples below. | |
| Comments: | In pixel-graphics modes that are 320 pixels
wide, you need to divide the x value by 2 to get the correct position on
the screen. (A strange feature of DOS.)
In DOS32 text modes you need to scale the x and y coordinates to get line and column positions. In Linux, no scaling is required - x and y correspond to the line and column on the screen, with (1,1) at the top left. In DOS32, you need a DOS mouse driver to use this routine. In Linux, GPM Server must be running. In Linux, mouse movement events are not reported in an xterm window, only in the text console. In Linux, LEFT_UP, RIGHT_UP and MIDDLE_UP are not distinguishable from one another. You can use get_mouse() in most text and pixel-graphics modes. The first call that you make to get_mouse() will turn on a mouse pointer, or a highlighted character. DOS generally does not support the use of a mouse in SVGA graphics modes (beyond 640x480 pixels). This restriction has been removed in Windows 95 (DOS 7.0). Graeme Burke, Peter Blue and others have contributed mouse routines that get around the problems with using a mouse in SVGA. See the Euphoria Archive Web page. The x,y coordinate returned could be that of the very tip of the mouse pointer or might refer to the pixel pointed-to by the mouse pointer. Test this if you are trying to read the pixel color using get_pixel(). You may have to read x-1,y-1 instead. |
| Example 1: | a return value of: |
{2, 100, 50}
| |
| would indicate that the left button was pressed down when the mouse pointer was at location x=100, y=50 on the screen. | |
| Example 2: | To test for LEFT_DOWN, write something like the following: |
object event
while 1 do
event = get_mouse()
if sequence(event) then
if and_bits(event[1], LEFT_DOWN) then
-- left button was pressed
exit
end if
end if
end while
| |
| See Also: | mouse_events, mouse_pointer, and_bits |
| Platform: | DOS32 |
| Syntax: | x = get_pixel(s) |
| Description: | When s is a 2-element screen coordinate {x, y}, get_pixel()
returns the color (a small integer) of the pixel on the
pixel-graphics screen
at that point. When s is a 3-element sequence of the form: {x, y, n} get_pixel() returns a sequence of n colors for the points starting at {x, y} and moving to the right {x+1, y}, {x+2, y} etc. Points off the screen have unpredictable color values. |
| Comments: | When n is specified, a very fast algorithm is used to read the pixel colors on the screen. It is much faster to call get_pixel() once, specifying a large value of n, than it is to call it many times, reading one pixel color at a time. |
| Example: | |
object x
x = get_pixel({30,40})
-- x is set to the color value of point x=30, y=40
x = get_pixel({30,40,100})
-- x is set to a sequence of 100 integer values, representing
-- the colors starting at {30,40} and going to the right
| |
| See Also: | pixel, graphics_mode, get_position |
| Syntax: | include graphics.e s = get_position() |
| Description: | Return the current line and column position of the cursor as a 2-element sequence {line, column}. |
| Comments: | get_position() works in both text and
pixel-graphics modes.
In pixel-graphics modes no cursor will be
displayed, but get_position() will return the line and column where the
next character will be displayed.
The coordinate system for displaying text is different from the one for displaying pixels. Pixels are displayed such that the top-left is (x=0,y=0) and the first coordinate controls the horizontal, left-right location. In pixel-graphics modes you can display both text and pixels. get_position() returns the current line and column for the text that you are displaying, not the pixels that you may be plotting. There is no corresponding routine for getting the current pixel position. |
| See Also: | position, get_pixel |
| Syntax: | include image.e s = get_screen_char(i1, i2) |
| Description: | Return a 2-element sequence s, of the form {ascii-code, attributes} for the character on the screen at line i1, column i2. s consists of two atoms. The first is the ASCII code for the character. The second is an atom that contains the foreground and background color of the character, and possibly other information describing the appearance of the character on the screen. |
| Comments: | With get_screen_char() and put_screen_char() you can save and restore a character on the screen along with its attributes. |
| Example: | |
-- read character and attributes at top left corner
s = get_screen_char(1,1)
-- store character and attributes at line 25, column 10
put_screen_char(25, 10, {s})
| |
| See Also: | put_screen_char, save_text_image |
| Platform: | DOS32 |
| Syntax: | include machine.e s = get_vector(i) |
| Description: | Return the current protected mode far address of the handler for interrupt number i. s will be a 2-element sequence: {16-bit segment, 32-bit offset}. |
| Example: | |
s = get_vector(#1C)
-- s will be set to the far address of the clock tick
-- interrupt handler, for example: {59, 808}
| |
| Example Program: | demo\dos32\hardint.ex |
| See Also: | set_vector, lock_memory |
| Syntax: | i = getc(fn) |
| Description: | Get the next character (byte) from file or device fn. The character will have a value from 0 to 255. -1 is returned at end of file. |
| Comments: | File input using getc() is buffered, i.e. getc() does not actually
go out to the disk for each character. Instead, a large block of
characters will be read in at one time and returned to you one
by one from a memory buffer.
When getc() reads from the keyboard, it will not see any characters until the user presses Enter. Note that the user can type control-Z, which the operating system treats as "end of file". -1 will be returned. |
| See Also: | gets, get_key, wait_key, open |
| Syntax: | x = getenv(s) |
| Description: | Return the value of an environment variable. If the variable is undefined, return -1. |
| Comments: | Because either a sequence or an atom (-1) might be returned, you
should probably assign the result to a variable declared as
object.
Both the argument and the return value, may, or may not be, case sensitive. You might need to test this on your system. |
| Example: | |
e = getenv("EUDIR")
-- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc.
| |
| See Also: | command_line |
| Syntax: | x = gets(fn) |
| Description: | Get the next sequence (one line, including '\n') of characters from file or device fn. The characters will have values from 0 to 255. The atom -1 is returned on end of file. |
| Comments: | Because either a sequence or an atom (-1) might be returned, you
should probably assign the result to a variable declared as
object.
After reading a line of text from the keyboard, you should normally output a \n character, e.g. puts(1, '\n'), before printing something. Only on the last line of the screen does the operating system automatically scroll the screen and advance to the next line. The last line in a file might not end with a new-line '\n' character. When your program reads from the keyboard, the user can type control-Z, which the operating system treats as "end of file". -1 will be returned. In SVGA modes, DOS might set the wrong cursor position, after a call to gets(0) to read the keyboard. You should set it yourself using position(). |
| Example 1: | |
sequence buffer
object line
integer fn
-- read a text file into a sequence
fn = open("myfile.txt", "r")
if fn = -1 then
puts(1, "Couldn't open myfile.txt\n")
abort(1)
end if
buffer = {}
while 1 do
line = gets(fn)
if atom(line) then
exit -- -1 is returned at end of file
end if
buffer = append(buffer, line)
end while
| |
| Example 2: | |
object line puts(1, "What is your name?\n") line = gets(0) -- read standard input (keyboard) line = line[1..length(line)-1] -- get rid of \n character at end puts(1, '\n') -- necessary puts(1, line & " is a nice name.\n") | |
| See Also: | getc, puts, open |
| Platform: | DOS32 |
| Syntax: | include graphics.e i1 = graphics_mode(i2) |
| Description: | Select graphics mode i2. See graphics.e for a list of valid graphics modes. If successful, i1 is set to 0, otherwise i1 is set to 1. |
| Comments: | Some modes are referred to as text modes
because they only let you display text. Other modes are referred to as
pixel-graphics modes because you can
display pixels, lines, ellipses etc., as well as text.
As a convenience to your users, it is usually a good idea to switch back from a pixel-graphics mode to the standard text mode before your program terminates. You can do this with graphics_mode(-1). If a pixel-graphics program leaves your screen in a mess, you can clear it up with the DOS CLS command, or by running ex or ed. Some graphics cards will be unable to enter some SVGA modes, under some conditions. You can't always tell from the i1 value, whether the graphics mode was set up successfully. On the WIN32 and Linux/FreeBSD platforms, graphics_mode() will allocate a plain, text mode console if one does not exist yet. It will then return 0, no matter what value is passed as i2. |
| Example: | |
if graphics_mode(18) then
puts(SCREEN, "need VGA graphics!\n")
abort(1)
end if
draw_line(BLUE, {{0,0}, {50,50}})
| |
| See Also: | text_rows, video_config |