
Improved User Interface Library
*******************************

In many 'old-stype' Forth applications the user interface was very rudimentary 
and uncomfortable.  Most modern Window&Menu driven OS interfaces offer much 
better service.  'Better' means better looking and a common look&feel of all 
applications.  A WIMP interface has not been designed so far, i feel the speed 
penalty is too high for most Forthish applications.  So i choose another way 
so far - the WIMP interface will be available sometime.  

To write a nice, well looking, robust and easy to use frontend for all your 
applications would be very time consuming and would probably be full of 
'features'.  

So here is a RISC OS Forthmacs library consisting of several source files 
offering menus, mouse-reactive 'Hot-Spots', Enter-boxes and more.  This 
library is available under TOOLS.INTERFACE for your applications.  

These words are rather easy to use.  See the 'tools.modem' file for an 
example.  There is just one tricky part, as i want to call the 
RS-232-CONFIGURE menu until connect is selected there is a flag set.  But 
otherwise it gives some idea about the concept.  

One more point, the hotspots might have a textual/pictorial representation on 
the screen.  The library doesn't include this part, you have to include this 
so far on your own.  


More tools to come
==================

Some more tools will be added to this library rather soon.  Sliders are on top 
priority.  

Hanno Schwalm 31.10.97 

schwalm@bre.winnet.de 




Glossary of Interface Library
=============================


____ box-number     ( name default len -- n  )              
A coloured box - as the menus - is opened at the current cursor position.  
name is displayed as the name of the box.  Now a number consisting at most of 
len characters might be entered - base is always decimal.  

After pressing cr, the box is closed, the screen is restored and the number 
entered is tested for a valid number.  If so, the number is left on the stack, 
otherwise a default value is returned.  

The editing takes place in multitasking mode, the flag menu-output? is set to 
true while the box is open, so all text output should be stopped.  


See: menu-output? edit-box 
____

____ edit-box       ( name addr n1 -- addr n2  )            
A coloured box - as the menus - is opened at the current cursor position.  
name is displayed as the name of the box.  The string entered is strored at 
addr, n1 is the maximum length.  

After pressing cr, the box is closed, the screen is restored and the string 
represented by addr and the actual number of characters n2 is returned.  

The editing takes place in multitasking mode, the flag menu-output? is set to 
true while the box is open, so all text output should be stopped.  


See: menu-output? box-number 
____

____ fast-mouse     ( --  )                                 
move mouse fast 
____

____ get-mouse-position  ( --  )                            
Reads the mouse position and button status from the operating system and saves 
the data in mouse-x, mouse-y and mouse-button. 
____

____ help-text-pos  ( -- x y  )                             
Menus and hot-spots may have a defined help text for each element.  This text 
is displayed at a fixed position defined by help-text-pos. 

You may set it by: 
    10 10 is help-text-pos

If you don't want the help text to appear set the help-text-pos to a value 
less than zero like in 
    -1 -1 is help-text-pos
____

____ l-butt?        ( -- n  )                               
left mouse button is pressed? 
____

____ m-butt?        ( -- n  )                               
middle mouse button is pressed? 
____

____ menu-output?   ( -- flag  )                            
The display of the menu uses save-screen-block and restore-screen-block when 
starting and ending the menu display.  Other tasks also using the display 
might be disturbed, they might test for menu-output? and stop writing to the 
screen until the menu-output? flag gets false again.  
    temp-single multi begin MENU-OUTPUT? while pause repeat single
    .....
    ;
would do want you wanted.  
____

____ menu:          ( -- cfa|0  )  'name'                   
Define a menu including help texts.  
    menu: your-menu
defines a menu with the name YOUR-MENU .  You may later call this menu by 
executing YOUR-MENU .  This call will display the menu and will will wait for 
a mouse-click on one of the menu items.  If this is the case, the execution 
token - cfa - of the clicked word is returned, otherwise it's 0.  

Now you may define all menu entrys.  Each entry consists of a 'word' defined 
in the current search path followed by an optional help text.  
    menu: your-menu
         entry1
         entry2 p" This is the text" ;
defines a menu YOUR-MENU with two entries, ENTRY1 and ENTRY2 .  ENTRY1 doesn't 
have a help text - that means it's a nullstring and ENTRY2 has p" This is the 
text" as the text.  ; finishes the definition as usual.  

The latest release alo supports submenus.  Every submenu has a dynamically 
bound root-menu entry at the top place.  



See: menu-output? 
____

____ mouse-action-field  ( help action upper-x upper-y width height --  )   
Define a hotspot action.  'help' is a counted string, 'action' is the 
execution token - or cfa - of the word to be executed when a mouse-button is 
pressed.  'upper-x' and 'upper-x' define the left upper edge of the screen 
block, 'width' and 'height' mean their textual meaning :-) Those last 4 
parameters are all in pixels! 

When a mouse-button is pressed, the MOUSE-SERVER task regularly checks for any 
hotspot beeing clicked on.  If this is the case, the cursor-status ( colour, 
position, on/off ) is saved and the mouse set to slow-mouse. 

Then the cursor is placed at the hot-spot and the word defined by 'action' is 
executed in single mode.  You may switch to multi mode, the MOUSE-SERVER will 
then prohibit further actions to be taken.  
____

____ mouse-action-p-field  ( help action upper-cx upper-cy cwidth cheight --  ) 
                                                            
Define a hotspot action.  'help' is a counted string, 'action' is the 
execution token - or cfa - of the word to be executed when a mouse-button is 
pressed.  'upper-x' and 'upper-x' define the left upper edge of the screen 
block, 'width' and 'height' mean their textual meaning :-) Those last 4 
parameters are all in 16x8 characters! 

When a mouse-button is pressed, the MOUSE-SERVER task regularly checks for any 
hotspot beeing clicked on.  If this is the case, the cursor-status ( colour, 
position, on/off ) is saved and the mouse set to slow-mouse. 

Then the cursor is placed at the hot-spot and the word defined by 'action' is 
executed in single mode.  You may switch to multi mode, the MOUSE-SERVER will 
then prohibit further actions to be taken.  
____

____ mouse-button   ( -- n  )                               
the status of the mouse buttons after get-mouse-position 
____

____ mouse-on       ( --  )                                 
switch mouse on 
____

____ mouse-off      ( -- )                                  
switch mouse off 
____

____ mouse-x        ( -- n  )                               
the x coordinate of the mouse after get-mouse-position 
____

____ mouse-y        ( -- n  )                               
the y coordinate of the mouse after get-mouse-position 
____

____ r-butt?        ( -- n  )                               
right mouse button is pressed? 
____

____ restore-screen-block  ( block --  )                    
restore part of the screen using a buffer defined by save-screen-block 
____

____ save-screen-block  ( width height -- block  )          
Allocate a dynamic buffer and save part of the screen to it.  The screen block 
is defined by the current cursor and width&height measured in characters.  
____

____ serve-hotspot  ( --  )                                 
Start the task serving the defined hotspots as task MOUSE-SERVER .  All 
hotspots are cleared, all text-messages are nullstrings.  You may now define 
up to 256 different hotspot actions with a help string for each action.  


See: mouse-action-field mouse-action-p-field 
____

____ slow-mouse     ( --  )                                 
move mouse slow 
____
