<!-- Forthmacs Formatter generated HTML V.2 output -->
<html>
<head>
<title>Improved User Interface Library</title>
</head>
<body>
<h1>Improved User Interface Library</h1>
<hr>
<p>
In many 'old-stype' Forth applications the user interface was very rudimentary 
and uncomfortable.  Most modern Window&amp;Menu driven OS interfaces offer much 
better service.  'Better' means better looking and a common look&amp;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.  
<p>
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'.  
<p>
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 <strong>tools.interface</strong> for your applications.  
<p>
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 <strong>RS-232-Configure</strong> 
menu until connect is selected there is a flag set.  But otherwise it gives some 
idea about the concept.  
<p>
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.  
<p>
<p>
<h2>More tools to come</h2>
<p>
Some more tools will be added to this library rather soon.  Sliders are on top 
priority.  
<p>
Hanno Schwalm 31.10.97 
<p>
schwalm@bre.winnet.de 
<p>
<p>
<p>
<p>
<h2>Glossary of Interface Library</h2>
<p>

<hr><h3><A name="69">box-number</A></h3> <h5> ( name default len -- n  )</h5>
<br>
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.  
<p>
After pressing <code><A href="_smal_AQ#1C0">cr</A>,</code> 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.  
<p>
The editing takes place in multitasking mode, the flag <code><A href="_smal_AQ#70">menu-output?</A></code> 
is set to true while the box is open, so all text output should be stopped.  
<p>

See: <code><A href="_smal_AQ#70">menu-output?</A></code> <code><A href="_smal_AK#6A">edit-box</A></code> 

<hr><h3><A name="6A">edit-box</A></h3> <h5> ( name addr n1 -- addr n2  )</h5>
<br>
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.  
<p>
After pressing <code><A href="_smal_AQ#1C0">cr</A>,</code> the box is closed, 
the screen is restored and the string represented by addr and the actual number 
of characters n2 is returned.  
<p>
The editing takes place in multitasking mode, the flag <code><A href="_smal_AQ#70">menu-output?</A></code> 
is set to true while the box is open, so all text output should be stopped.  
<p>

See: <code><A href="_smal_AQ#70">menu-output?</A></code> <code><A href="_smal_AJ#69">box-number</A></code> 

<hr><h3><A name="6B">fast-mouse</A></h3> <h5> ( --  )</h5>
<br>
move mouse fast 

<hr><h3><A name="6C">get-mouse-position</A></h3> <h5> ( --  )</h5>
<br>
Reads the mouse position and button status from the operating system and saves 
the data in <code><A href="_smal_AX#77">mouse-x</A>,</code> <code><A href="_smal_BA#78">mouse-y</A></code> 
and <code><A href="_smal_AU#74">mouse-button</A>.</code> 

<hr><h3><A name="6D">help-text-pos</A></h3> <h5> ( -- x y  )</h5>
<br>
Menus and hot-spots may have a defined help text for each element.  This text is 
displayed at a fixed position defined by <code><A href="_smal_AN#6D">help-text-pos</A>.</code> 
<p>
You may set it by: 
<p><pre>  10 10 is help-text-pos</pre><p>
<p>
If you don't want the help text to appear set the <code><A href="_smal_AN#6D">help-text-pos</A></code> 
to a value less than zero like in 
<p><pre>  -1 -1 is help-text-pos</pre><p>

<hr><h3><A name="6E">l-butt?</A></h3> <h5> ( -- n  )</h5>
<br>
left mouse button is pressed? 

<hr><h3><A name="6F">m-butt?</A></h3> <h5> ( -- n  )</h5>
<br>
middle mouse button is pressed? 

<hr><h3><A name="70">menu-output?</A></h3> <h5> ( -- flag  )</h5>
<br>
The display of the menu uses <code><A href="_smal_BD#7B">save-screen-block</A></code> 
and <code><A href="_smal_BC#7A">restore-screen-block</A></code> when starting 
and ending the menu display.  Other tasks also using the display might be 
disturbed, they might test for <code><A href="_smal_AQ#70">menu-output?</A></code> 
and stop writing to the screen until the <code><A href="_smal_AQ#70">menu-output?</A></code> 
flag gets <code><A href="_smal_AM#21C">false</A></code> again.  
<p><pre>  temp-single multi begin MENU-OUTPUT? while pause repeat single</pre><p>
<p><pre>  .....</pre><p>
<p><pre>  ;</pre><p>
would do want you wanted.  

<hr><h3><A name="71">menu:</A></h3> <h5> ( -- cfa|0  ) <kbd> 'name'</kbd> </h5>
<br>
Define a menu including help texts.  
<p><pre>  menu: your-menu</pre><p>
defines a menu with the name <strong>your-menu</strong> .  You may later call 
this menu by executing <strong>your-menu</strong> .  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.  
<p>
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.  
<p><pre>  menu: your-menu</pre><p>
<p><pre>       entry1</pre><p>
<p><pre>       entry2 p" This is the text" ;</pre><p>
defines a menu <strong>your-menu</strong> with two entries, <strong>entry1</strong> 
and <strong>entry2</strong> .  <strong>entry1</strong> doesn't have a help text 
- that means it's a nullstring and <strong>entry2</strong> has p" This is the 
text" as the text.  ; finishes the definition as usual.  
<p>
The latest release alo supports submenus.  Every submenu has a dynamically bound 
root-menu entry at the top place.  
<p>
<p>

See: <code><A href="_smal_AQ#70">menu-output?</A></code> 

<hr><h3><A name="72">mouse-action-field</A></h3> <h5> ( help action upper-x upper-y width height --  )</h5>
<br>
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! 
<p>
When a mouse-button is pressed, the <strong>mouse-server</strong> 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 <code><A href="_smal_BF#7D">slow-mouse</A>.</code> 
<p>
Then the cursor is placed at the hot-spot and the word defined by 'action' is 
executed in <code><A href="_smal_AB#301">single</A></code> mode.  You may switch 
to <code><A href="_smal_AK#A">multi</A></code> mode, the <strong>mouse-server</strong> 
will then prohibit further actions to be taken.  

<hr><h3><A name="73">mouse-action-p-field</A></h3> <h5> ( help action upper-cx upper-cy cwidth cheight --  )</h5>
<br>
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! 
<p>
When a mouse-button is pressed, the <strong>mouse-server</strong> 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 <code><A href="_smal_BF#7D">slow-mouse</A>.</code> 
<p>
Then the cursor is placed at the hot-spot and the word defined by 'action' is 
executed in <code><A href="_smal_AB#301">single</A></code> mode.  You may switch 
to <code><A href="_smal_AK#A">multi</A></code> mode, the <strong>mouse-server</strong> 
will then prohibit further actions to be taken.  

<hr><h3><A name="74">mouse-button</A></h3> <h5> ( -- n  )</h5>
<br>
the status of the mouse buttons after <code><A href="_smal_AM#6C">get-mouse-position</A></code> 

<hr><h3><A name="75">mouse-on</A></h3> <h5> ( --  )</h5>
<br>
switch mouse on 

<hr><h3><A name="76">mouse-off</A></h3> <h5> ( -- )</h5>
<br>
switch mouse off 

<hr><h3><A name="77">mouse-x</A></h3> <h5> ( -- n  )</h5>
<br>
the x coordinate of the mouse after <code><A href="_smal_AM#6C">get-mouse-position</A></code> 

<hr><h3><A name="78">mouse-y</A></h3> <h5> ( -- n  )</h5>
<br>
the y coordinate of the mouse after <code><A href="_smal_AM#6C">get-mouse-position</A></code> 

<hr><h3><A name="79">r-butt?</A></h3> <h5> ( -- n  )</h5>
<br>
right mouse button is pressed? 

<hr><h3><A name="7A">restore-screen-block</A></h3> <h5> ( block --  )</h5>
<br>
restore part of the screen using a buffer defined by <code><A href="_smal_BD#7B">save-screen-block</A></code> 

<hr><h3><A name="7B">save-screen-block</A></h3> <h5> ( width height -- block  )</h5>
<br>
Allocate a dynamic buffer and save part of the screen to it.  The screen block 
is defined by the current cursor and width&amp;height measured in characters.  

<hr><h3><A name="7C">serve-hotspot</A></h3> <h5> ( --  )</h5>
<br>
Start the task serving the defined hotspots as task <strong>mouse-server</strong> 
.  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.  
<p>

See: <code><A href="_smal_AS#72">mouse-action-field</A></code> <code><A href="_smal_AT#73">mouse-action-p-field</A></code> 

<hr><h3><A name="7D">slow-mouse</A></h3> <h5> ( --  )</h5>
<br>
move mouse slow 
</body>
</html>
