[an error occurred while processing this directive]
<h1>Understanding the Scout Notation</h1>

<p>
Scout describes a display as (potentially) overlapping windows.  For
example, if display <em>disp</em> is defined as
</p>
<pre>disp = &lt; win1 / win2 &gt;</pre>

<p>
this means that display <em>disp</em> consists of two windows <em>win1</em>
and <em>win2</em>, should <em>win1</em> and <em>win2</em> overlap,
<em>win1</em> overlays <em>win2</em>.
</p>

<p>
The best way of understanding what Scout windows are is through the
formula below:
</p>
<pre>
window = region X content X attributes
</pre>

<p>

A window defines a region in which something will be displayed in a
certain way.  There are four kinds of windows in the current Scout
notation: text window, textbox window, DoNaLD window and image window.
Because of the different nature of the windows, their definitions of
region, content and attributes may differ.

</p>

<p>
For a text window,
</p>

<dl><dt><code>region</code> (called a frame) = list of boxes</dt>
<dd>The string is filled into the first box, the remaining characters
are filled into the second box and so on.</dd>
<dt><code>content</code> = a character string</dt>
<dd>- a character string</dd>
<dt><code>attribute</code> = { <code>fgcolour</code>, <code>bgcolour</code>, <code>border</code>, <CODE>bdcolour</CODE>, <CODE>relief</CODE>, <code>alignment</code> }</dt>
<dd>These attributes indicate the colour of the text string, the colour
of the background, whether the boxes have borders, the border colour,
the kind of border and the alignment of
strings in relation to the boxes respectively.  
The acceptable reliefs are raised, sunken flat, ridge and groove.</dd></dl>

<p>
For a textbox window,
</p>

<dl><dt><code>region</code> = a box</dt>
<dt><code>content</code> = a character string</dt>
<dt><code>attribute</code> = { <code>fgcolour</code>, <code>bgcolour</code>, <code>border</code>, <CODE>bdcolour</CODE>, <CODE>relief</CODE>, <code>alignment</code> }</dt>
<dd>As for the text window, but the alignment attribute defaults to
LEFT.</dd></dl>

<p>
For a DoNaLD window,
</p>

<dl><dt><code>region</code> = a box</dt>
<dd>- a box</dd>
<dt><code>content</code> = a drawing (name of the drawing)</dt>
<dd>- a drawing</dd>
<dt><code>attribute</code> = { <code>xmin</code>, <code>ymin</code>, <code>xmax</code>, <code>ymax</code>, <code>fgcolour</code>, <code>bgcolour</code>, <code>border</code>, <CODE>bdcolour</CODE> <CODE>relief</CODE> }
</dt>
<dd><code>xmin</code>, <code>ymin</code>, <code>xmax</code>, <code>ymax</code>
defines the coordinate system of the drawing; <code>fgcolour</code> and
<code>bgcolour</code> defines the foreground and background colour, <code>border</code>
determines whether to draw borders of the box, <CODE>bdcolour</CODE> 
defines the border colour and <CODE>relief</CODE> how
the border is drawn.</dd>
</dl>

<p>
For an image window,
</p>

<dl><dt><code>region</code> = a box</dt>
<dd>- a box</dd>
<dt><code>content</code> = an image (name of the image variable)</dt>
<dd>- an image</dd>
<dt><code>attribute</code> = { <code>bgcolour</code>, <code>border</code>, <CODE>bdcolour</CODE> <CODE>relief</CODE> }
</dt>
<dd>
<code>bgcolour</code> defines the colour to be filled when the image
is not large enough to cover the whole area of the window.
<code>border</code>
determines whether to draw borders of the box.
<CODE>bdcolour</CODE> 
defines the border colour and <CODE>relief</CODE> how
the border is drawn.</dd>
</dl>

<p>
The <code>sensitive</code> attribute is common to all four types of
windows.  It is used to declare that a window is sensitive to mouse and
keypress actions.  When this attribute is <code>ON</code>, a mouse action
or a keypress action within the region of this window will cause a
definition to be generated.  If a mouse action occurs in a window and it
is a DoNaLD or image window, then the window name concatenated with <code>_mouse</code>
will be the name of the variable to be defined; if it occurs in a text
window, the window name concatenated with <code>_mouse_</code> followed by
the box number will be the variable name.  The value assigned to the
appropriate variable records the nature and the location of the mouse
action.  It is a 5-tuple of (<em>button</em>, <em>type</em>, <em>state</em>, <em>x</em>, <em>y</em>) where
</p>

<dl><dt><em>button</em></dt>
<dd>the button number pressed or released;</dd>
<dt><em>type</em></dt>
<dd>the button action (4 = pressed, 5 = released);</dd>
<dt><em>state</em></dt>
<dd>the state before the button action occurred (shift (+1), caplock
(+2), control (+4), meta (+8) and was-pressed (+256)).  For example, if
a button is released while the shift and control keys are depressing,
state will be 1 + 4 + 256 = 261;
</dd>
<dt><em>x</em>, <em>y</em></dt>
<dd>the x- and y- coordinates of the mouse in the coordinate system of
the window in which the mouse action occurred.</dd></dl>
<p>
As with mouse events, a stroke on the keyboard will generate a
definition.  Instead of <code>_mouse</code> or <code>_mouse_</code> followed
by a box number, the variable name of the generated definition will end
with <code>_key</code> or <code>_key_</code> followed by a box number.  The
value defined will also be a 5-tuple: (<em>key</em>, <em>type</em>, <em>state</em>, <em>x</em>, <em>y</em>), where
<em>key</em> is the ascii code of the key pressed.
</p>

<p>
In principle, there could be many types of windows, many more
attributes and many ways of defining regions.  The current notation only
demonstrates the principle of using definitions in describing screen
layout.
</p>

[an error occurred while processing this directive]