
Title; Window Manager 3.03 and the future.
Authors; David De Vorchik
History;
        08-Jan-91 DDV Created
        10-Jan-92 DDV Added notes on Wimp 3.04
        19-Jan-92 DDV Some bits on Wimp 3.05
        23-Jan-92 DDV Updated to describe the new rotation speed.
        05-Feb-92 DDV Updated to reflect Window Manager 3.06.
        11-Feb-92 DDV Some more ramblings.
        11-Feb-92 DDV Documentation on Wimp_SetColourMapping/AddMessages/RegisterFilter
        12-Feb-92 DDV Some more bits on 3.06, including Wimp_RemoveMessages and change to Wimp_Initialise.
        14-Feb-92 DDV Note on template loading.
        16-Feb-92 DDV Notes on indirected menu titles.
        18-Feb-92 DDV Service_WimpRegisterFilters doc added.
        23-Feb-92 DDV Updated before passing over to RMokady.
        13-Apr-92 LVR Updated after bug fixing prior to Green release


Window Manager 3.03
-------------------

The following changes apply to the Window Manager version 3.04 and
beyond.  They relate to various improvements in the handling of colour
and window borders.

Firstly the Wimp has been modified to use ColourTrans to lookup the wimp
physical colours and map them onto screen values this has the side effect
that some different effects can be noticed, firstly the inversion of sprites
can result in different colours than before due to then way the inversion
is handled.

8BPP sprites now work correctlyunder the desktop, as do icons with palettes
rather than being plotted incorrectly or the palette being ignored.  The concept
of physical palette and the Wimp colours has now been introduced, this means
that in screen modes less than 8BPP there is a palette which is programmed, and
then there is the phsyical colours associated with the Wimp colours 0-15.

CMOS location &1C,b4 controls wether dithering is always applied to Wimp
colours (outside monochrome modes).  This is not always active due to
compatibility problems with some third party applications.


Window Manager 3.04
-------------------

In monochrome modes the first eight Wimp colours are dithered and the
meaning of Wimp_ReadPalette and Wimp_SetPalette is finalised.

Setting of the palette using Wimp_SetPalette now preserves the supremacy
bits used by VIDC if the palette is reprogrammed, this cures a bug in
the palette utility.

New inversion routines applied, these require ColourTrans 1.03 to work
correctly as they take advantage of the transfer function to work
correctly.


Window Manager 3.05
-------------------

Some further changes to the handling of palettes, mostly bug fixing though.

The rotation speed of the dot dash line now made processor speed independant
by timing based on 2 centi-second intervals, this makes the display on Perth 
look alot better.


Window Manager 3.06
-------------------

Handling of IconSprites and sprite plotting improved, the new algorithm means
that rather than performing a linear search through both the RAM and the ROM 
areas a table of pointers is built, then when a sprite address is required a 
binary chop is performed (the list is stored alphabetically).

If the sprite pools have to move then the following service call is
issued:

        Service_WimpSpritesMoved
        in      R1 = Service_WimpSpritesMoved
                R2 -> ROM area
                R3 -> RAM area
        out     should not be claimed                              

Window Manager now uses OS_FindMemMapEntries, rather than its own cumbersom
slow implementation.
                       
The Window Manager notices if a template file is within ResourceFS, then it is
accessed in situ rather than being copied away into a RAM buffer or accessed
via filing system calls.

If a task has specified Window Manager version >= 306 then Wimp_CreateMenu 
expects that R4 contains a set of icon flags, this is mainly used for indirected
text so that extended title bars can be used.  It is assumed that all sub-levels
of the menu use the same flags for the title bar, to this extent Wimp_CreateSubMenu
ignores the value passed in R4, and uses the original value specified on Wimp_CreateMenu.

When the Window Manager is reset a service call is issued to allow tasks to
install filters with it, this is used by the Filter Manager to register itself.

        Service_WimpRegisterFilters
        in      R1 = Service_WimpRegisterFilters
        out     -

This is issued when ever the Wimp resets the filter table back to its default
state.

There have been some changes to the B qualifier in validation strings; it is
still postfixed with two numbers, the first is the border number as follows:

        0 => normal single pixel border
        1 => slab out
        2 => slab in
        3 => ridge
        4 => channel
        5 => action button (highlights when icon selected)
        6 => default action button (highlights when icon selected)
        7 => editable field

     >= 8 => normal single pixel border

The bordering is only applied when the task has specified a version >= 306
to Wimp_Initialise.  The second number relates to the highlight colour applied
on border types 5,6.  By default this is 14 but the validation string can
over-ride this, when the icon is selected the foreground colour is retained and
the background changes to the highlight colour.

The borders are still plotted on the inside of the icon border and only if the
border bit is set aswell.  

A new Wimp_ReadSysInfo has been added:

        Wimp_ReadSysInfo
        in      R0 = 5 
        out     R0 = task handle / =0 for no active task
                R1 = version number specified by task on Wimp_Initialise 

This is used by the Font Manager and MessageTrans to decide if indirected menu
titles should are allowed.

A new *Command has been added for loading the Wimp border sprites, this is:

        *ToolSprites <fsp>

When issued the Window Manager attempts to locate the border sprites, it does
not attempt to add the various suffixes (as applied on IconSprites) as the sprites
within the pool can have suffixes to their names.

The borders are loaded into a seperate sprite pool rather than the one
used for normal sprites, if the sprites are within ResourceFS then they are
bound directly rather than being copied down into user RAM. 

When the borders have been loaded the Window Manager then attempts to update
the screen refereshing all the borders, this is just total screen redraw.


New SWIs / Changes
------------------
            
        Wimp_Initialise (&400C0)
        in      R0 = latest known version of Wimp * 100 (300)
                R1 = "TASK"
                R2 -> task name string
                R3 -> list of message numbers / terminated by 0
                        in Wimp >= 306 then =0 indicates all messages rather than NONE!
        out     -
                                
This SWI has changed since its 3.00 definition, this is that if the version
of the Window Manager is >= 306 then it is possible to specify 0 to indicate
that all messages are important to this task.

                  
        Wimp_CreateMenu (&400D4)
        in      R1 -> menu block / = window handle / = -1 to close
                R2 = x co-ordinate to open at
                R3 = y co-ordinate to open at

                IF WimpKnown >= 306 THEN
                        R4 = flags for title bar icon

        out     -

The Wimp_CreateMenu has been extended in the Window Manager for tasks which
known about newer versions of the OS.  If a task has specified a version >=
306 to Wimp_Initialise then it is assumed that R4 on entry to
Wimp_CreateMenu are the flags for the title bar.

This allows indirected title bars to be used which is important for
internationalised applications.  If the indirected bit is set then the first
12 bytes of the menu structure are not the title string but are the same as
the data passed to Wimp_CreateIcon for an  indirected icon.  Within the
flags word the only data which is changed is the button type and the
colours.

Only the indirection, text and sprite bits are passed through from R4.


        Wimp_SysInfo (&400F2)
        in      R0 = 5 => return current task info      
        out     R0 = task handle / =0 if none active
                R1 = version specified by task to Wimp Initialise

This is just a new reason code introduced after Window Manager 3.00, the
first returns info on the current.


        Wimp_RegisterFilter (&400F5)
        in      R0 = filter number
                        = 0 => pre-poll filter
                        = 1 => post-poll filter
                        = 2 => rectangle copy filter
                        = 3 => get rectangle filter

                R1 -> routine / =0 for none
                R2 -> workspace to pass in R12
        out     -

Calling this will install a routine to be called prior to certain operations
being performed.  Routines called will be in SVC mode with interrupts enabled,
the routine called should preserve all registers, except where documented.  R2 contains
the task handle of the task about to be paged in.


        Wimp_AddMessages (&400F6)
        in      R0 -> word array of messages to add for task
        out     -

This call allows to you update the list of messages known by a certain task,
this routine updates the messages list for the current task.  It is only
of any use for tasks that have specified 300 or greater to Wimp_Initialise.
               
                                     
        Wimp_RemoveMessages (&400F7)
        in      R0 -> word array of messages to remove from task
        out     -

This SWI allows the caller to remove messages from the list specified either
on Wimp_Initialise or by Wimp_AddMessages.  This SWI only works if the task 
has specified a version >= 300 to Wimp_Initialise.


        Wimp_SetColourMapping (&400F8)
        in      R1 -> palette to be used for converting Wimp colours to physical colours
                R2 -> 2 byte array for mapping 1BPP sprites to Wimp colours
                R3 -> 4 byte array for mapping 2BPP sprites to Wimp colours
                R4 -> 16 byte array for mapping 4BPP sprites to Wimp colours
                R5,R6,R7 must be zero
        out     -

Using this SWI you can change the way in which the Window Manager maps
its own Wimp colours to physical colours.

On entry R1 contains a pointer to a 16 word set of physical colours (&BBGGRRxx),
when converting a wimp colour to its physical colour it indirects through this
to get the physical colour required.  By default this is the same as the palette
defined using Wimp_SetPalette.

If -1 is specified then the default Wimp palette is used, if 0 is specified then
the palette defined by Wimp_SetPalette is used, else the table is copied away.

R2,R3,R4 point to byte arrays which are used when converting non-paletted
sprite colours to their physical colours.  Basicly the system uses the values stored
within the byte array as an index into the palette being used for ColourTrans
calls.  Passing 0 indicates no change, -1 indicates the default setting.

Window Manager 3.10
-------------------

Released in RISC OS 3.08.  Various bug fixes have been applied for this
version together with some minor functional changes:

 - The border command in icon validation strings is changed to an R
character.
 - The menu tick and arrow icons are reverted back to sprites.
 - The KA command in an icon validation string causes the caret to be
positioned to the end of next writable icon when the up/down arrow keys are
pressed.
 - *WimpPalette now checks that there are exactly 16 entries in a palette
file
 - Sprite highlighting has changed again.  Greys are inverted in intensity
(i.e 0 -> 1, 0.25 -> 0.75).  While colours are reduced to 5/8 of their
original intensity.  Graying is accomplished by mapping all colours to a
corresponding gray level and compressing the brightness range 0..1 into the
range 0.7 .. 1.0, basically emulating RISC OS 2 functionality.
 - The wimp now responds to Service_InvalidateCache and thus correctly
tracks applications that modify the colour palette.