system icons
scrollable icons
validation strings
sprite + text icons
button type 9
button type 11
inverting sprites
In Arthur 1.2, it was not possible to tell the difference between the pointer being over the work area of a window and being over one of the system icons (eg. title bar, scroll bar and so on).
When running new-style tasks (see Wimp.Desktop), the Wimp now returns different icon handles from Wimp_GetPointerInfo for each of the system icons, as follows:
-1 work area (as before)
-2 back box
-3 quit box
-4 title bar
-5 toggle box
-6 scroll up button
-7 vertical scroll bar
-8 scroll down button
-9 size box
-10 scroll left button
-11 horizontal scroll bar
-12 scroll right button
-13 the line surrounding the window (not on an icon)
Most normal applications should not need to know about these icon handles, but it is occasionally useful for things like interactive help.
Some extra functions have been added to these icons since Arthur 1.2, so a full summary follows:
back SELECT sends the window to the back of the stack,
with the same coordinates
quit SELECT closes the window
ADJUST opens the parent directory (for Filer windows)
title bar SELECT brings the window to the front and allows the
position to be altered
ADJUST is similar but leaves the window at the same
height in the stack
toggle SELECT if the window is not at its full size, opens
the window at the front at its full size
if already full size, the window is returned
to its last non-full position in the stack
ADJUST is similar but leaves the window at the same
height in the stack when making full-size
scroll up SELECT scrolls the window up 32 OS units
ADJUST scrolls the window down 32 OS units
vertical scroll SELECT above the sausage scrolls up a page
ADJUST above the sausage scrolls down a page
SELECT in the sausage drags up and down,
opening the window at the front
ADJUST in the sausage drags up and down,
at the same height in the stack
SELECT below the sausage scrolls down a page
ADJUST below the sausage scrolls up a page
scroll down SELECT scrolls the window down 32 OS units
ADJUST scrolls the window up 32 OS units
size SELECT alters the window size, bringing it to the front
ADJUST leaves the window at the same height in the stack
scroll left }
horizontal scroll } these are analagous to the other scroll bar
scroll right }
User interface:
SELECT puts caret into icon
Typing / moving the caret can cause the icon to scroll.
Application:
Create icon with 'writeable' bit set, as normal. Length of buffer determines max string length, Size of icon determines amount displayed.
If an icon is indirected, it can have a validation string associated with it as well as its own text string and maximum buffer size. In the case of a writeable icon, this allows the application to tell the Wimp which characters it would like the user to be allowed to type into the icon. Any characters disallowed by the validation string will be passed back to the application via Wimp_Poll (Key_Pressed), so they could still be meaningful.
The syntax of validation strings has been designed to be open-ended, to allow further enhancement in the future, but for the moment (Wimp 2.00) the following syntax prevails:
<validation string> ::= <command> { ; <command> }*
<command> ::= a <allow-spec> | d <display-spec>
<allow-spec> ::= { <char_spec> }* { ~ { <char-spec> }* }*
<char-spec> ::= <char> | <char> - <char>
<char> ::= \- | \; | \\ | \~ | <any character other than - ; \ ~>
<display-spec> ::= <char>
command letters are case-insensitive, and spaces are significant.
In simple terms, a validation string consists of a series of 'commands', each starting with a single letter, followed by various parameters and separated by ';'s. The interpretation of the parameters depends on the initial letter of the command:
The (A)llow command tells the Wimp which characters are to be allowed in the icon string. When a key is typed by the user, and the input focus is inside this icon, the Wimp checks the validation string to see if the character is to be allowed in the string. If it is, then the character will be inserted in the icon string: otherwise, it will be returned to the application via Wimp_Poll (Key_Pressed).
Control keys such as the arrow keys and delete are automatically dealt with by the Wimp - any other codes outside the range 32-255 will be returned to the application whatever happens, and the other codes will be returned unless the 'allow' string says that they can be included in the icon string.
Basically each <char-spec> in the 'allow' string specifies a group of characters which are to be included or excluded from the icon string. The ~ character is used to toggle whether the Wimp is including or excluding the specified characters, as follows:
a0-9a-z~dpu
In this case the Wimp would allow the digits 0-9 and the lower-case letters a-z (except for 'd', 'p' and 'u'). Note that the initial state of whether the letters are allowed or not is determined by whether the first letter following the 'a' is a ~ or not:
a~0-9
Here all the normal characters except for the digits are allowed.
The \ character is used as an escape character for ~ - ; \ to avoid syntax problems, so for example to disallow ~ - ; \ one would use the following validation string:
a~\~\-\;\\
The (D)isplay command is used for password icons, where the icon is to be entered into the computer in the normal way, but each character is to be displayed differently, to avoid onlookers seeing the password:
d*
would cause the password to be displayed as a row of '*'s. Note that if the character is any of the four 'special' characters above, it must be preceded by a '\', eg:
d\-
The (F)ont colours command is used to specify the foreground and background colours of an anti-aliased icon. The problem is that the 'colour' field in the icon flag word is re-used for the font handle, so the validation string must be used to specify the font colour. The 'F' is followed by 2 hex digits, which specify the background and foreground (wimp) colours respectively. The Wimp then calls Wimp_SetFontColours (see Wimp.Colours) to set up the font colours before printing the text. The default colours are 0 and 7.
The (L)ine spacing command can be used to tell the Wimp that a text icon may be formatted: that is, that if the text is too wide for the icon, it may be split over several lines. A decimal number should follow the 'L', which indicates the vertical spacing between lines of text - if omitted, the default is 40 (OS units).
Currently this option should only be used with icons which are horizontally and vertically centred, and do not contain an anti-aliased font. The icon should not be writeable, since the caret will not be positioned correctly inside it.
The (S)prite name command can be used if the icon has been defined with bits 0 and 1 both set (ie. it is a text and sprite icon). In this case the 'S' command in the validation string can be used to specify the sprite name, so that it can be different from the text!
Sfoosprite
Note that no space should follow the 'S', and the sprite name is at most 12 characters long.
You can also put two sprite names after the 'S', separated by a comma, to indicate that the first sprite should be used when the icon is not highlighted, and the second one when it is.
(See below for a full description of the Sprite+Text facility).
In the Arthur 1.20 Wimp, it was possible (but not very useful) to specify an icon as containing text and a sprite. There were two reasons why this was not very useful:
(1) The positioning of the text and the sprite depend on the various flags combinations as follows:
V = vertically centred (bit 5 of icon flags)
H = horizontally centred (bit 4)
R = right justified (bit 9)
~ = not set, otherwise set
Vertical:
V ==> both vertically centred <== as before
HR~V ==> text at top, sprite at bottom
~V ==> text at bottom, sprite at top
Horizontal:
~V ~H~R ==> both at left <== as before
~V ~H R ==> both at right <== as before
~V H ==> both centred <== as before
V ~H~R ==> sprite at left, text +6 units to right (LJ)
V H~R ==> both centred (text visible) <== as before
V ~H R ==> text at left, sprite at right
V H R ==> sprite at left, text at right (RJ)
Thus the relative positions of the text and the sprite can be varied simply by altering the dimensions of the overall icon.
(2) The sprite name can be made to be different from the text, as follows:
a) the icon must be indirected
b) the text field, validation string and buffer length all have their
usual meanings for text icons
c) the sprite name is determined by the S field in the validation
string. This can be used in conjunction with any other fields
(separated by ';') in the string. Note that if you put two sprite
names after the 'S', separated by a comma, the Wimp will use
either the first or second sprite depending on whether the icon is
selected or not (and will not invert the sprite).
d) The sprite areaCBptr must be the same as the window's areaCBptr.
In particular, this means that icons on the iconbar which contain
text as well as a sprite must refer to a sprite in the Wimp's
common sprite pool (see Wimp.Sprites and Wimp.IconBar).
The sprite+text icon suffers from the following drawbacks (if any of these are a problem, use two icons instead!):
a) The text field can be writeable, and can even scroll, but
unfortunately the sprite will be redrawn every time a key is
pressed!
b) Because icon inversion causes the text to be redrawn with the
foreground and background colours swapped, even non-filled
sprite+text icons have the text filled (even when not inverted).
This is so that Wimp_SetIconState can toggle the inversion state
without redrawing the window behind the icon.
c) Shading the icon <<<< is this true ???
d) If the text is anti-aliased, the icon must not have a filled
background, since the background of the anti-aliased text is
filled in after the sprite is drawn, thus obscuring it!
e) Mouse clicks will not be clipped to the sprite and text
individually (only the full box is considered).
The text+sprite facility is primarily intended as a means of getting a sprite/text pair onto the iconbar. It is also useful for representing files (in any of the formats which the Filer supports) - note that 'small' files can be represented by setting bit 11 of the icon flags, which causes the sprite to be displayed at half size (see also Wimp.Colours for a description of the Wimp's default sprite scaling).
It has come to my attention that some people do not believe that the 'menu icon' button type (9) works correctly. In fact it does, but is only meaningful if the ESG of the icon is non-zero, since otherwise the continuous selections that it makes when the pointer is over the icon cause it simply to flash.
This button type is extremely useful when constucting dialogue boxes that are intended to simulate menus, or for 'action' buttons.
Meaning:
SELECT/ADJUST ==> select icon, and return &01/&04 to application
SELECT/ADJUST drag ==> return &10/&40 to application
Icon button type 11 is intended to facilitate the maintaining of an icon (or group of icons) in a dialogue box, so that the Wimp will automatically select the icon, and also notify the application when the icon is clicked, without doing any of the more esoteric actions, such as returning double-clicks.
ESG's, and the 'allow adjust' bit (bit 10) can be set in conjunction with this button type to produce the required effects.
Remember that there is also a new facility when specifying a text+sprite icon to have the Wimp alternate between two different sprites when selecting the icon (see above).
On the Arthur 1.2 Wimp, inverting and shading of sprites was done by plotting the sprite's mask over it, using GCOL 3,<fg colour> and GCOL 2,2 modes respectively.
This meant that the desired effect was not produced in mode 15, where the meaning of the logical colours is completely different from that in mode 12.
On Arthur 2.0, true to the tradition of mode independence, the effect is achieved instead by manipulating the translation table used to plot the sprite, so that rather than inverting the colours that are plotted on the screen, the 'Wimp colours' of the sprite are inverted in the translation table.
The net effect of this is that sprites are inverted correctly in mode 15, and they also do not flicker when selected, as they used to do.