Wimp.Colours

New Calls

        Wimp_SetMode
        Wimp_SetPalette
        Wimp_ReadPalette
        Wimp_ReadPixTrans
        Wimp_SetCaretPosition
        Wimp_SetColour
        Wimp_TextColour
        Wimp_SetFontColours
        Wimp_PlotIcon
        *Configure WimpMode <number>
        *WimpPalette <filename>

Overview

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

Using the mode-independent facilities

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

Setting the mode/palette

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.