NOTE: All information in this manual is valid as of 24th October, 1999. I
will try to keep this updated.

Some useful graphical interface routines for mode 18,
(c) Andrew Greenwood, 1999.

E-mail: andrew@goldcroft6.freeserve.co.uk
WWW:    http://www.goldcroft6.freeserve.co.uk/index.html

These routines may work in other resolutions, but be warned that they assume
the text characters to be each of size 8x16 pixels (which is what mode 18
uses). THEY REQUIRE A MOUSE.

You can use these routines for whatever you want, for no charge. However, I'd
appreciate a mention in the credits of any programs you write using them.

NOTE: The user is NOT allowed to switch windows until the active one has been
destroyed. This limitation is caused by the fact that each window knows what
was underneath it before it was created. This shouldn't really be a problem,
since most programs use one window at a time.

Co-ordinates for window components are referenced from the top-left of the
window, NOT the top-left of the screen.


The component co-ordinates are designed to be compatible with text output.
Therefore, you must specify text co-ordinates for the components, NOT the
graphics.


The interface routines consist of the following files:

buttons.e   Button Manager
die.e       "Death Manager"
filelist.e  File selectors
list.e      Listbox Manager
menu.e      Menu Manager
message.e   Message Box
mouse.e     Direct Mouse (improvement over original)
window.e    Window Manager



The procedure for using the interface is pretty simple - create, display,
destroy. Handles are used extensively, and invalid ones are usually picked up
on and your program will halt.

If a routine is not mentioned here, it's because it's not important to you.
There are quite a few internal things you should ignore, such as the
CheckButtons() function, which are managed by the get_key() routine
replacement.


-----------------------------------------------------------------------------

Buttons.e  routines:

function
CreateButton(integer parent, sequence text, sequence coords, object key)

-   Use this to create a button. All this does is set the parameters and
    allocate a handle to the button.
    parent  is the handle of the parent window (see window.e)
    text    is the text to be displayed on the button
    coords  is the location of the top-left of the button (column/row format)
    key     is the virtual key to be returned via get_key()

    A handle for the button is returned.


procedure
DestroyButton(integer handle)

-   Destroys a button previously created and displayed.
    handle  is the handle of the button, returned from CreateButton.


procedure
DisplayButton(integer handle)

-   Displays the button at the co-ordinates specified.


function
old_get_key()

-   The original get_key(), which should only be used if you don't want the
    user to be able to interact with the interface.


function
get_key()

-   A replacement for the Euphoria built-in routine. THIS IS THE MAIN
    ROUTINE. Every time your program calls get_key(), it will check for
    keypresses and mouse clicks and perform the appropriate actions.
    A key/virtual key value will be returned.



-----------------------------------------------------------------------------

Die.e  routines:

procedure
FatalExit(object Module, object Message)

-   If your program needs to halt due to an error, use this.
    Module      is the name of the module the error occurs in.
    Message     is the error message to display.


function
GetWinVer()

-   Returns the version of Windows running, or 0 if it isn't. Useful if your
    program doesn't work under Windows, or only runs under Windows 95.


function
MousePresent()

-   Returns 1 if a mouse driver is installed, or 0 if one isn't.



-----------------------------------------------------------------------------

FileList.e  routines:

function
OpenDialog(sequence path, sequence filters)

-   Display an open file dialog box. This is a modified version of Jacques's
    FileList.e. A sequence is returned if a file has been chosen (with the
    filename in it), otherwise a -1 is returned.
    path    is the default path
    filters is a list of filters, eg: {{"Filter1","*.ABC"},
                                       {"Filter2","*.DEF"}}



-----------------------------------------------------------------------------

List.e  routines:

function
CreateListBox(integer parent, sequence origin, sequence size, integer colour)

-   This will allocate a handle to a new list box.
    parent  is the handle of the parent window (see window.e)
    origin  is a 2-element sequence, which defines where the top-left of the
            list box will be. The first element is the X-position (1 - 80, if
            using mode 18), the second is the Y-position (1 - 25). Positions
            are referenced from the top left of the window.
    size    is another 2-element sequence, this time specifying the size of
            the listbox. This is similar to "origin" except here you specify
            the size, NOT co-ordinates.
    colour  defines the colour of the items in the listbox.


procedure
DestroyListBox(integer handle)

-   This will hide and remove the listbox.
    handle  is the handle returned by CreateListBox.


procedure
DisplayListBox(integer handle)

-   Displays the list box and creates the scroll buttons.
    handle  is the handle returned by CreateListBox.


procedure
HighlightItem(integer handle, integer index)

-   Highlights an item in a list box. Useful if you need an item highlighted
    by default.
    handle  is the handle returned by CreateListBox.
    index   is the index of the item in the listbox (1 is the first item)


procedure
ScrollBox(integer handle, integer direction)

-   Scrolls a list box up or down by one item.
    handle      is the handle returned by CreateListBox.
    direction   should be -1 to scroll up, or +1 to scroll down.


procedure
AddListBoxItem(integer handle, sequence caption, sequence data)

-   Appends an item to the end of a list box.
    handle  is the handle returned by CreateListBox.
    caption is the text to be displayed in the list box.
    data    is hidden data which is related to the caption.


function
GetListData(integer handle, integer index)

-   Returns the data set with CreateListBox.
    handle  is the handle returned by CreateListBox.
    index   is the index number of the list box item whose data is being
            requested. The index for item 1 is 1.


function
GetListCaption(integer handle, integer index)

-   Returns the caption (displayed text) set with CreateListBox.
    handle  is the handle returned by CreateListBox.
    index   is the index number of the list box item whose caption is being
            requested. The index for item 1 is 1.


procedure
ClearListBox(integer handle)

-   Clears a listbox.
    handle  is a handle returned by CreateListBox.


function
GetSelected(integer handle)

-   Return the index of the selected item in a list box, or 0 if none
    selected.
    handle  is a handle returned by CreateListBox.


procedure
ClearSelection(integer handle)

-   Deselects all items in a listbox.
    handle  is a handle returned by CreateListBox.



-----------------------------------------------------------------------------

Menu.e  routines:

function
CreateMenu(integer parent, sequence title, integer xp, integer yp,
           integer colour)

-   Creates a new menu, but doesn't display it. Use DisplayMenu to do this.
    parent  is the handle of the parent window (ie: the window to which this
            menu belongs).
    title   is the text to be displayed as the menu name.
    xp      is the X-position (in columns) of the menu.
    yp      is the Y-position (in rows) of the menu.
    colour  defines the colour of the text which will be used for the title.


function
CreateMenuItem(integer handle, sequence title, integer colour, object vkey)

-   Adds a menu item to the menu specified by "handle". You must create a
    menu before you can add menu items to it.
    handle  is the handle returned by CreateMenu.
    title   is the text to be displayed on the menu. If you want to specify
            a break in the menu, use a single dash (-) as the menu title.
    colour  is the colour of the menu item.
    vkey    is a virtual key code to be returned via get_key().


procedure
DisplayMenu(integer handle)

-   Makes a menu visible.
    handle  is a handle returned by CreateMenu.


procedure
CloseMenu()

-   Closes an open menu if one is open. This is called automatically and
    will probably not be used in most cases.


procedure
DisableMenu(integer handle)

-   Makes a menu unusable.
    handle  is a handle returned by CreateMenu.


procedure
EnableMenu(integer handle)

-   Makes a menu usable.
    handle  is a handle returned by CreateMenu.


procedure
DisableMenuItem(integer handle, integer subhand)

-   Makes a menu item unusable.
    handle  is the handle of the menu containing the menu item to be disabled.
    subhand is the handle of the menu item to be disabled.


procedure
EnableMenuItem(integer handle, integer subhand)

-   Makes a menu item usable.
    handle  is the handle of the menu containing the menu item to be enabled.
    subhand is the handle of the menu item to be enabled.


procedure
DestroyMenu(integer handle)

-   Destroys a menu, hides it too.
    handle  is a handle returned by CreateMenu.



-----------------------------------------------------------------------------

Message.e  routines:

function
Message(sequence Msg, integer Buttons)

-   Creates a window, displays a message in it, with some buttons. The
    buttons defined in message.e are MB_OK and MB_YESNO.
    Msg     is the message to be displayed.
    Buttons is an integer specifying which set of buttons to use.



-----------------------------------------------------------------------------

Mouse.e  routines:


procedure
mouse_pointer(integer show_it)

-   Shows or hides the mouse pointer. These routines monitor if the pointer is
    on or off and won't perform duplicate actions (ie: it won't turn the
    pointer on if it's already on).
    show_it must be 1 to turn the pointer on, or 0 to turn it off.


function
get_mouse_position()

-   Returns the X and Y co-ordinates of the mouse pointer without displaying
    it. The returned value is a 2-element sequence.


procedure
mouse_position(integer xpos, integer ypos)

-   Sets the location of the mouse pointer.
    xpos    is the X co-ordinate
    ypos    is the Y co-ordinate


function
mouse_button(integer button_number)

-   Retrieves the state of a mouse button. Three constants are defined for
    the button numbers: LEFT_BUTTON, MIDDLE_BUTTON and RIGHT_BUTTON.
    button_number   is the button whose status is to be returned.


COMPATIBILITY NOTE: The original mouse.e is also included inside this version
of mouse.e. It's generally a good idea not to use both sets of routines as
you may miss events.



-----------------------------------------------------------------------------

Window.e  routines:

procedure
rectangle(integer colour, sequence tl, sequence br)

-   Draws a rectangle from tl to br. This can be done with the default
    polygon command but is easier this way.
    colour  is the colour to be used for the rectangle.
    tl      is a 2-element sequence of co-ordinates (top left)
    br      is another 2-element sequence of co-ordinates (bottom right)


procedure
rectangle_fill(integer colour, sequence tl, sequence br)

-   Draws a rectangle from tl to br. This can be done with the default
    polygon command but is easier this way. The rectangle will be filled.
    colour  is the colour to be used for the rectangle.
    tl      is a 2-element sequence of co-ordinates (top left)
    br      is another 2-element sequence of co-ordinates (bottom right)


procedure
SetActiveWindow(integer newone)

-   Sets the active window manually. Make sure the active window you are
    setting does not overlap another window!
    newone  is the handle of the window to set active.


function
CreateWindow(sequence origin, sequence size)

-   Creates a window (but doesn't display it).
    origin  is a 2-element sequence with the top left co-ordinates of the
            window (text co-ordinates, NOT graphics!) in it.
    size    is another 2-element sequence controlling the size of the window.
            Size is in text blocks, not pixels.


procedure
DestroyWindow(integer handle)

-   Destroys the window specified by the handle.
    handle  is a handle returned by CreateWindow.


procedure
DisplayWindow(integer handle)

-   Displays a window.
    handle  is a handle returned by CreateWindow.


function
GetActiveWindow()

-   Returns the handle of the currently active window.


function
GetWindowParams(integer handle)

-   Returns the parameters of a window. This is a 3-element sequence:
    [1] Origin (2-element sequence, X position, Y position)
    [2] Size (2-element sequence, width, length)
    [3] Menu handle
    handle  is a handle returned by CreateWindow.


procedure
polygon_w(integer handle, integer colour, integer fill, sequence points)

-   See the Euphoria reference manual for details of how to use the polygon
    routine. This is basically a modified version which uses points
    referenced from the top-left of the window, rather than the screen.
    handle  is a handle returned by CreateWindow.
    colour  is the colour of the polygon.
    fill    is 1 to fill, or 0 for outline only.
    points  a sequence of X and Y co-ordinates.


procedure
rectangle_w(integer handle, integer colour, integer fill, sequence tl,
            sequence br)

-   Draws a rectangle in the window specified.
    handle  is a handle returned by CreateWindow.
    colour  is the colour of the rectangle.
    fill    is 1 to fill, or 0 for outline only.
    tl      specifies the top left co-ordinate of the rectangle.
    br      specifies the bottom right co-ordinate.


procedure
w_puts(integer handle, object data)

-   Same as puts, but for a window. THIS IS INCOMPLETE. I plan to add some
    routines to retrieve text from the screen soon.
    handle  is a window handle returned by CreateWindow.
    data    is a string to be displayed.


procedure
w_position(integer y, integer x)

-   Sets the cursor location to that specified in the parameters.
    y   is the new row
    x   is the new column
