Wimp_SetMode
Wimp_SetPalette
Wimp_ReadPalette
Wimp_ReadPixTrans
Wimp_SetCaretPosition
Wimp_SetColour
Wimp_TextColour
Wimp_SetFontColours
Wimp_PlotIcon
*Configure WimpMode <number>
*WimpPalette <filename>
The new Wimp has been designed to operate in any of the graphics modes available under Arthur, so that it is as easy as possible for applications to work without knowing much about which mode is currently in use.
When a task is the only client of the Wimp, it is OK for it to select the mode of its choice, and to always operate in that mode. When many tasks are running simultaneously, however, each of the tasks must be prepared to work in whichever mode is currently selected, since they can't all decide that the mode will be what they want.
Under the new system, the choice of which mode and which palette to use is given to the user, rather than the application program - the central palette management utility provides the necessary facilities, and the other applications simply respond to whatever mode is currently in use.
To get round the problem of different modes having differing pixel aspect ratios, the Wimp performs automatic scaling of sprites, and also of the system font (see Wimp.Text).
To get round the palette problem, there is a common understanding of what each colour is used for, based on the 16 colours available in modes 9, 12 and 20. In modes with more or less colours, the Wimp uses a translation table to select the closest colours available. The use of this table means that application programs should normally not have to worry about which mode is actually in use - as long as all colour selections are done through the Wimp, the best available colour will be chosen.
The standard colour uses are as follows:
0-7 linear grey scale, usually from white (0) to black (7)
(these colours are used for the anti-aliased fonts)
(4 = scroll bar outer colour also)
8 yellow
9 blue
10 green
11 red
12 light input focus background colour for title bar
13 light normal background colour for title bar
14 dark foreground colour for title bar (usually black)
15 darkish desktop background colour
Applications should rely on these colours having been set up as above, and should not set the palette at all. The palette is set up by the palette utility using the Wimp_SetPalette call, which associates an RGB value with each of the 16 wimp colours. What effect this actually has on the screen palette is determined by the number of colours available as follows:
1 bit per pixel (2 colours):
Palette: colour 0 is set to wimp colour 0
colour 1 is set to wimp colour 7
0 logical colour 0 - font background colour
1-6 ecf pattern 4 (stippled in one of 6 patterns with colours 0,1)
7 logical colour 1 - font foreground colour
8-14 either colour 0 or 1 (whichever is closest in brightness)
15 ecf pattern 4 (the closest brightness ecf is used)
2 bits per pixel (4 colours):
Palette: colours 0..3 are set to the linear greyscale from wimp colours 0 to 7
0-15 logical colour with closest brightness
4 bits per pixel (16 colours):
Palette: all colours are set to their corresponding wimp colour
0-15 same logical colour
8 bits per pixel (256 colours):
Palette: set to the default
0-15 closest approximation to the R,G,B value set in the wimp palette
The Wimp colour table is used by the Wimp in the following circumstances:
when reading the colours for a given window from its definition
- unless bit 10 of the window flags is set
- in this case the colours are used unchanged
when reading the colours for an icon
- text colours are looked up in the table
- sprite colours are translated
if the sprite has 1, 2 or 4 bits per pixel
(8 bit per pixel sprites are illegal as Wimp icons)
when reading the caret colour
- default caret colour is wimp colour 11
- if bit 26 of R4 (Wimp_SetCaretPosition) set, bits 16..23 = colour
- if bit 27 of R4 set, this colour is a 'real' colour
- note that the EOR colour of the caret is EORed with wimp colour 0
(this only matters in 256-colour modes)
See Wimp.Text for further details.
In the above description, a 'real' colour is defined as follows:
In non 256-colour modes, the colour is simply the logical colour In 256-colour modes, bits 0..1 are bits 6..7 of the tint
bits 2..7 are bits 0..5 of the colour (gcol)
The Wimp colour table is not used if the application simply plots a sprite in its window, or if the GCOL command is used to set colours.
To select a Wimp colour explicitly, use:
Wimp_SetColour
Entry: R0=gcol action/wimp colour
bits 0..3 = colour
bits 4..6 = gcol action
bit 7 = foreground / background colour flag
Exit: appropriate gcol/tint commands have been issued
note that ecf pattern 4 may be used in 2-colour modes
Another call has been provided to facilitate the matching of (VDU 4) text colours to graphics colours (it is used by Wimp_CommandWindow and on exit from the Wimp). For obvious reasons, however, it is unable to use an ECF pattern to represent grey levels in monochrome modes:
Wimp_TextColour
Entry: R0 = wimp colour/fg/bg
bits 0..3 = colour
bit 7 = foreground / background colour flag
Exit: appropriate colour/tint commands have been issued
In a similar vein, the Wimp can set up anti-aliased font colours, either by programming the validation string of an icon (see Wimp.Icons), or by using the following explicit call:
Wimp_SetFontColours
Entry: R1 = wimp colour (background)
R2 = wimp colour (foreground)
The Wimp works out how many colours can be used for anti-aliasing, and also
takes care of mode-dependent decisions (eg. in 256-colour mode 16 shades can
always be used, but in other modes the number of shades available depends on
the colours).
NOTE: Applications should NOT assume the setting of the font colours after a
Wimp_Poll operation, but should instead explicitly set up the font
colours as required. This also means that there is no need to reset
the font colours afterwards.
To plot an icon explicitly (inside a Redraw/Update loop), use:
Wimp_PlotIcon
Entry: R1 --> icon definition
+ 0..15 = bounding box (relative to window origin)
+ 16 = icon flags
+ 20..31 = icon data
Normally these calls will only be used by the palette utility, in response to spcific actions made by the user. However, the calls are detailed here for reference:
To set up the default mode used by the Wimp on startup:
*Configure WimpMode <number>
The next time the Wimp is started up, the specified mode is used. The value is also remembered in CMOS RAM, so it is remembered after power-off. On new machines, the default wimp mode is 12.
To change the Wimp mode in use:
Wimp_SetMode
Entry: R0 = mode number
Exit: the Wimp palette is recomputed and re-output
the pointer is reprogrammed
the amount of screen memory is 'shrunk' as much as possible
If this call is made when no tasks are running, the mode change does not take place until a task is run. Note that changes to the Wimp mode made in this way are remembered the next time the Wimp is run, but do not affect the configured mode and so are not remembered after switch-off.
To set up the palette from a file:
*WimpPalette <filename>
Palette files are of type &FED, and can be in one of two formats (including or excluding the logical colour numbers). On Arthur 2, FileSwitch defaults the runtype of palette files as follows:
*Set Alias$@RunType_FED WimpPalette %0
Thus double-clicking a palette file from the Filer has the effect of activating that palette.
To set up the palette from RAM:
Wimp_SetPalette
Entry: R1 --> block of 20 words
words 0..15 are the wimp colours
word 16 is the border colour
words 17..19 are the pointer colours (1,2,3)
each word is of the form &BBGGRRxx (blue, green, red)
When this call is made, the palette is recomputed depending on the mode. If the mode in use does not have 16 colours, this may cause the logical colour mapping used by the Wimp to change, which will necessitate a screen redraw. The palette utility detects this automatically, and behaves appropriately.
To read the current Wimp palette settings:
Wimp_ReadPalette
Entry: R1 --> block of 20 words
Exit: block set up from the Wimp palette
words 0..15 are the wimp colours
word 16 is the border colour
words 17..19 are the pointer colours (1,2,3)
each word is of the form &BBGGRRxx (blue, green, red)
xx = actual 'real' colour used by Wimp
(0 for border and mouse colours)
To read the current Wimp scale factors and pixel translation table (used for plotting icons which are sprites):
Wimp_ReadPixTrans
Entry: R0 = 0 ==> sprite is in the system area
= &1xx ==> sprite is in a user area (R2 = name ptr)
= &2xx ==> sprite is in a user area (R2 = sprite ptr)
R1 = 0 ==> sprite is in the system area
= 1 ==> sprite is in the Wimp's shareable area
> 1 ==> R1 --> user sprite area
R2 --> name of sprite (if R0 = &1xx or &0xx)
--> sprite itself (if R0 = &2xx)
R6 --> 4-word block to receive scale factors
R7 --> 4-word block to receive pixel translation table
Exit: [R6] = scale factors (x-mul,y-mul,x-div,y-div)
[R7] = pixel translation table (16 bytes)
After this call, R6 and R7 can be passed to OS_SpriteOp (PutSpriteScaled). The scale factors returned depend on the mode the sprite is defined in, and the mode currently in use by the Wimp - the Wimp will attempt to correct for aspect ratio changes between different modes. Note that the pixel translation table is only suitable for use with sprites defined in 1, 2 or 4 bits per pixel, and the colours are translated as follows:
Sprite mode Colour associations
----------- -------------------
1 bpp colours 0,1 are treated as Wimp colours 0, 7
2 bpp colours 0..3 are treated as Wimp colours 0, 2, 4, 7
4 bpp colours 0..15 are treated as Wimp colours 0..15
8 bpp the translation table is meaningless
Note that the format of the bytes returned in the pixel translation table is not the same as those returned by Wimp_ReadPalette in 256-colour modes. The colours used when plotting sprites correspond to the actual values to be put into the screen memory, and are in the following format:
bits 0..3 = palette register
bit 4 = bit 7 of red value
bit 5 = bit 6 of green value
bit 6 = bit 7 of green value
bit 7 = bit 7 of blue value
Since the default palette is defined as 'brtt' (blue, red, tint, tint), this means:
Pixtrans = BGGRbrtt
colour/tint = BBGGRRtt
To get the pixtrans value from the colour/tint, rotate bits 3..6 left by 1.
NOTE: when programming the caret colour, the Wimp assumes that the colour
supplied (if bit 27 is set) is of the colour/tint form. When passing
this value to the Font Manager, however, it must translate the value
into the 'pixtrans' form, since that is what the latter expects.