The WIMP

Priority sprite pool

The concept of priorities for sprites was introduced in RISC OS 4 as a minor extension to the standard ROM/RAM shared Wimp sprite pools. This allowed users to configure the ROM pool as taking priority over application installed sprites. The intention with this facility was to ensure that a safe, consistent set of sprites were used and that applications which replaced components of the system sprites would be forced to use the default, consistent set.

Whilst the principle was sound, it failed to take into account the fact that users wish to configure their system to look how they want it to and not how any other company might like them to have it. Thus, for many users this was not sufficient. In order to accommodate this Select introduces the concept of the 'Priority Sprite Pool'. This pool is intended solely for use by users and designers of system customisation tools (generally known as 'theme managers'). Applications outside of this category should not modify the Priority Sprite Pool.

Technical details

The contents of the Priority Sprite Pool always override any sprites installed in either the ROM or RAM sprite pools, regardless of the configuration of the standard sprite priorities (*Configure WimpSpritePrecedence). It would be most common for users to select ROM sprite precedence and then to use the Priority Sprite Pool to override the ROM settings with their own customisations.

The Priority Sprite Pool is held in a dynamic area, managed in the same manner as the standard Wimp sprite pool. Because sprites may come from either the Priority Sprite Pool, the ROM sprite pool, or the original RAM sprite pool, it is necessary to use new calls to locate these pools. Two new calls have been added to the WindowManager to allow the extra pool to be accessed.

As with the standard RAM sprite pool, write operations should not be performed on the pool.

Use of the system sprite area

Although the Window Manager supports the use of the System Sprite Area by applications supplying 0 as the sprite area, such use is now regarded as obsolescent and may be removed in a future version of the WindowManager.

* Commands

      *IconSprites

Syntax:

      *IconSprites [-priority] <file> | -priorityclear

The *IconSprites command will add sprites to either the standard Wimp sprite pool or the Priority Sprite Pool. If the -priority option is supplied, the file specified will be added to the Priority Sprite Pool, otherwise it will be added to the standard sprite pool. The -priorityclear option is intended for 'theme' managers to reset the pool to its initial state in order to assert a new set of customised sprites.

SWIs

Wimp_ReadSysInfo 19 [BaseOfSprites2]

On entry

   R0 = 19

On exit

   R0 = priority sprite pool
   R1 = 'high' priority sprite pool
   R2 = 'low' priority sprite pool

This call provides information about the sprite areas used for looking up sprites in the order they are used. This call is provided for information only. These are the sprite pools used by the WindowManager in the order in which they have been configured. If the ROM sprites are protected with the ROM precedence option then the ROM pool will appear as the 'high' priority sprite pool, and the RAM pool as the 'low' priority sprite pool. If ROM precedence is selected then this is reversed.

If specific sprites are required clients should use Wimp_Extend 13. Clients wishing to perform searches of the sprite pools without Wimp_Extend 13 should examine the pools in R0, R1, then R2 in that order.

See also:

Wimp_ReadSysInfo 16, Wimp_BaseOfSprites

Wimp_Extend 256 [GetSpriteAddress]

On entry

   R0 = 256
   R1 = 0 to search the sprite sprite area
        1 to search the Wimp sprite area
        or pointer to sprite pool to search
   R2 = sprite name to find

On exit

   R1 = pointer to sprite pool
   R2 = pointer to sprite

This SWI is used to locate a sprite in the same manner that the Window Manager does. The sprite pool specified in R1 will be searched first, followed by the priority sprite pool, then the 'high' priority sprite pool and finally the 'low' priority sprite pool. If the sprite is not found an error will be returned. Because this SWI can use the WindowManager's cached tables of sprites it will be faster than a manual search of each of the pools.

Note: Under Select 3i1 this call was Wimp_Extend 13 but this was found to clash with an undocumented call under RISC OS 5. It has been reallocated.

Services

Service_WimpSpritesMoved (&85)

On entry

   R1 = &85 (Service number)
   R2 = pointer to ROM sprite pool
   R3 = pointer to RAM sprite pool

This service call is issued by the Wimp when any of the sprite pools change, as documented in PRM 3-77. In addition, it will be issued if the priority sprite pool has changed, although its area is not passed in registers (in order to conform to the original service call definition).

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015