|
www.riscos.com Technical Support: |
Major changes were made to the desktop in RISC OS 3.5, many of them to improve its appearance. This introduction outlines those changes; the rest of the chapter details the changes they have introduced to the programmers' interface. Incidentally, some of the changes below are entirely handled by RISC OS, and so have introduced no new interfaces.
There have been sprite and template changes to give a 3D appearance to the windows. You should refer to the RISC OS 3 Style Guide for more information in this area.
The desktop now uses a proportional font in the desktop and can tile the window backgrounds with a texture.
The Filer was changed so that:
The Wimp error messages were changed to be more helpful, consistent and user friendly. Applications can now provide a more suitable wording on Error messages and buttons.
The Pinboard was changed to support outline fonts. The *Backdrop command was extended so you can remove a backdrop.
DragASprite was changed so that the dragged sprite will by default be dithered (ie semi-transparent). You can then see the area underneath a drag, and hence where you are moving a large sprite.
Currently, if a program goes into an 'infinite loop' (eg it keeps posting an error box without polling) there is no way to stop it. The Wimp now has a watchdog triggered by a hot-key combination, which can be used to kill such rogue programs.
Throughout this chapter, when we refer to the desktop's system font, we are referring to text that the Wimp outputs using VDU calls (as in earlier versions), and not to text output using the outline System.Fixed font.
In previous versions of RISC OS, the Wimp plotted text in icons using the OS_Write... calls and VDU commands; this uses the system font, which is a bit-mapped fixed width font. From RISC OS 3.5 onwards the Wimp can instead call the Font Manager, and use a single proportionally spaced outline font for text output.
In this chapter, we shall refer to the current font used by the Wimp as the desktop font, whether it be an outline font or the system font.
If painting an outline font generates an error for any reason, then the Wimp does not report an error, but reverts to the system font. This avoids loops where reporting an outline font error generates the same error itself.
There are some characters that are present in the system font and used in the desktop, but are not present in most outline fonts. A new font named WIMPSymbol has been created that holds outline versions of the most commonly used such characters. It only has these characters defined:
| Code | Character | Source |
|---|---|---|
| &80 | 3 | Selwyn, &62 |
| &84 | 7 | Selwyn, &63 |
| &88 | 
| Sydney, &DC |
| &89 | 
| Sydney, &DE |
| &8A | ![[DOWN]](../symbols/entities/8659.png)
| Sydney, &DF |
| &8B | ![[UP]](../symbols/entities/8657.png)
| Sydney, &DD |
If the Wimp is using an outline font, it switches to the WIMPSymbol font when outputting these characters.
When designing templates, you should ensure that they work with the system font, with Homerton Medium at 12 point, and (preferably) with Trinity Medium at 12 point.
Where text may change, ensure there is enough space for a 'worst case'. To help you in this, you may find it useful to know that the widest Homerton character is '@', and the widest alphanumeric character is 'W'. In Trinity the corresponding characters are '...' (amongst others), and 'W'.
You should be aware that you can no longer use spaces to align columns (such as those in the Filer's Full Info output). Instead you must use a separate icon for each column, or use the new SWI Wimp_TextOp 2 within a redraw loop.
There is a CMOS bit that users can set to indicate whether they prefer to use a 2D or 3D desktop (see CMOS RAM allocation).
We do not require your application to provide both 2D and 3D templates. Should you choose to do so, you should select the appropriate set by examining this bit at startup, and whenever there is a mode change.
When the Wimp loads a template, it now forces the sprite area control block pointer in any window definitions to 1. This is because some template editors do not set this field correctly, but the Wimp now uses it to search for a tiling sprite (see Tiled window backdrops); an invalid value can have disastrous consequences.
The Wimp works out menu widths for you, even for outline fonts. Your application need not worry about setting the correct width for a menu entry - except for a writable field, when the supplied width will be used as minimum. Menus will be just wide enough to contain the title, and all of the entries, in the menu.
In menus, keyboard shortcuts must be displayed right-aligned. Previously this was done by using spaces to align the shortcuts, but this is no longer possible with outline fonts. From RISC OS 3.5 onwards the Wimp automatically finds and right aligns any shortcut at the end of a menu entry, using simple rules.
For the Wimp to recognise a menu entry as having a shortcut, both the following must be true:
and at least one of the following must also be true:
^ ^ ^
Esc ESC F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 Print PRINT Break BREAK Pause PAUSE Tab TAB Return RETURN Insert INSERT Home HOME PageUp PAGE UP Delete DELETE Copy COPY End END PageDown PAGE DOWN Enter ENTER Up UP Down DOWN Left LEFT Right RIGHT Select SELECT Menu MENU Adjust ADJUST
If the above conditions are satisfied, the Wimp right aligns everything after the last space.
By holding the lists in the Wimp's messages file, they can be internationalised, so (for example) the modifiers could be a whole word rather than just a symbol. We encourage you to follow the guidelines in the RISC OS 3 Style Guide for giving shortcuts.
Some applications put icons on the icon bar that have text as well as a sprite. Obviously the width of such icons can change as the desktop font is changed. From RISC OS 3.5 onwards, the Wimp calculates the width of all text and sprite icons that it places on the icon bar.
Where the text of an icon is fixed, you should specify the icon's width to be the same as the sprite's. The Wimp then calculates the actual width to make all the text readable, both on the icon's creation and on a font change.
Where the text may change (for example if it is used to display a status), you must instead handle things yourself. You must measure the length of all potential strings using Wimp_TextOp 1, and hence find the maximum width of the icon. You must then create the icon with this width, disabling the Wimp's auto-sizing by including an 'X' in the icon's validation string. When you receive Message_FontChanged to tell you the desktop font has changed, you must recalculate the widths, and resize the icon by calling Wimp_ResizeIcon.
An alternative to the above is to delete and recreate the icon each time the text changes, and rely upon the Wimp to auto-size it (ie don't include an 'X' in the icon's validation string). However, this causes much redrawing of the whole icon bar, and so is deprecated.
If the Wimp finds a sprite named tile_1 in either a window's sprite area or its own (eg loaded with *IconSprites), then this is used to tile the background of a window that normally has colour 1 as its background. To improve performance the Wimp sprite pool is also searched for a sprite named tile_1-xx, where xx is the number of bits per pixel for the current screen mode; if one is found, this avoids the overhead of converting the tiling sprite between different pixel depths.
Tiling sprites must not have a palette.
There is a CMOS bit to enable and disable this feature; see CMOS RAM allocation.
Considerable changes were made to the Wimp's error system in RISC OS 3.5. The sections below provide an overview of the changes; Wimp_ReportError on Wimp_ReportError (page 3-176) details how the programmers' interface has changed.
Many applications use the Wimp's error system to relay information just as much as to raise errors, so we now refer to the dialogue boxes as reports rather than as error boxes. To reflect this, the title bar has been changed to say 'Message from' rather than 'Error from'.
The appearance of reports has been improved, and messages have been changed to be more helpful, consistent and user friendly. Applications can now provide more suitable wording for messages.
The 'OK' button has been changed so it instead says 'Continue', provided the calling application is aware of the new error system. (Old applications will still use an 'OK' button.). This button is the default, and can be selected by pressing the Return key. The 'Cancel' button has not changed its wording.
However, you do not have to use just these buttons, and can add to them or replace them with any number of buttons that use any words that fit. In the rare event that your buttons do not fit on the standard window, the Wimp automatically makes it wider to accommodate them; but the buttons themselves are a fixed size, at least under RISC OS 3.5 and 3.6.
New service calls make it easy to hook into your own buttons, and in particular to make your buttons themselves open reports - say to give debugging information, or extra help.
RISC OS 3.5 introduces a new scheme to categorise reports. Each category uses a different sprite in the report, taken from the Wimp's Sprites resource file.
The other types of errors are referred to as running reports. They are errors that, sadly, are to be expected in the normal running of the machine, or which have to be understood by the user. Of these:
There are two main problems faced by applications which wish to use the new error system, and yet still work on earlier versions of RISC OS (ie 3.1 and before):
The first problem is easily solved by using alternative files for the text of reports. You should use lines similar to the following in your !Run file:
Set App$Dir <Obey$Dir> Set App$Messages <Obey$Dir>.NewMessages RMEnsure WindowManager 3.21 Set App$Messages <Obey$Dir>.OldMessages
and then in your code, instead of opening <Obey$Dir>.Messages as is customary, you should open App$Messages.
The second problem is more involved. Let's say you wish to display a report that has 'Discard', 'Cancel' and 'Save' buttons:
Using the new error system, you can display this report using the extensions to Wimp_ReportError.
However, if you try to use the same extensions user an earlier version of RISC OS, it will ignore your custom buttons, and instead display an 'OK' button. Furthermore, when the user clicks on 'OK' a value of 1 is returned, rather than values of 3 upwards expected from your custom buttons.
The only workround is to switch conditionally between the two methods, either by use of an environment variable as above, or by examining the version number returned by Wimp_Initialise. This maintains backwards compatibility, but uses the more efficient new features when possible.
A final issue is that report categorisation is not supported by earlier versions of RISC OS, although this has no side affects on actual behaviour, just on appearance - since the old warning sprite appears for all errors.
Some supplied applications have been moved, for example between the RISC OS ROM image and the disc; in future releases they may move again. If your software uses another RISC OS application !App, it must not assume App's location, but should instead find it by reading the value of the App$Dir system variable.
The new 3D window surrounds introduced in RISC OS 3.5 ignore the scroll bar inner and outer colours declared in bytes 36 and 37 of the window block. 2D windows still behave as in earlier versions of RISC OS.
The (K)eys command now restricts the caret to icons in the same ESG group from RISC OS 3.5 onwards, rather than cycling through all icons - just as we advised would happen in the RISC OS 3 Programmer's Reference Manual.
Bytes 4 - 7 of each menu item may contain a submenu pointer or window handle, or -1 if neither. The way they are distinguished changed in RISC OS 3.5:
However, you should not rely upon this in your code, as it may be subject to further change.
This call was extended in RISC OS 3.5 to support the new types of error report. If bit 8 of the flags word passed in R1 is set, the new types are being used, and specified using both further flag bits and other parameters passed in R3 - R5.
The new flag bits in R1 are:
| Bits | Meaning |
|---|---|
| 8 | Set use new types of error report, as given by bits 9 - 11 and R3 - R5
|
| 9 - 11 | 0 OLD ERROR SPRITE (NON CLASSIFIED)_ 1 information report,
|
| 2 ERROR REPORT_ 3 PROGRAM REPORT_ 4 question
|
The values passed in R3 - R5 (ignored unless bit 8 of R1 is set) are:
R3 = pointer to sprite name
R4 = pointer to sprite area, or 1 to use the Wimp sprite area
R5 = pointer to list of text for additional buttons, comma separated and control character terminated; or 0 if none
For consistent results, all sprites you use should be defined in a 16 colour mode.
If no sprite name is passed in R3, or the error is an old style one, then the Wimp tries !app as a sprite name. This is a desperate measure which may not internationalise well.
The strings passed in R5 are the text of additional buttons to create. If the dialogue box does not have a Continue or Cancel button (ie bits 0 and 1 of R1 are clear on entry), then the first additional button is the default one. If the first additional button is pressed, it always returns 3 in R1 - even if it is the default. Any further buttons return 4, 5, and so on. The Continue button is the rightmost one, followed by the Cancel one, followed by any additional buttons in the order they are specified, with the Describe button (if added by RISC OS - see below) appearing at the extreme left.
Certain potentially serious error numbers are treated slightly differently. This happens if one or more of the following are true:
These errors are always generated as a program report. The report always has a Cancel button, but the label on it is instead Quit. The error text is replaced by 'App may have gone wrong. Click Quit to stop App'. If the program did not request a Cancel/Quit button, but it is pressed, then the Wimp terminates the application without re-entering it. It does so by calling its exit handler, since the error handler may call Wimp_ReportError again, which would be confusing or may even go into an infinite loop. A Describe button is added; if this is pressed then the report is replaced by that originally provided by the application (ie the Describe button disappears).
This call accepts the following new system information index values from RISC OS 3.5 onwards:
This call was changed in RISC OS 3.5 so that the dragged sprite is by default dithered, and hence appears semi-transparent. A new bit has been added to the flags word in R0 to control this feature. If bit 8 is clear (as should be the case for all existing applications) then dithering occurs; if it is set then it is disabled.
The range of available *Desktop_... commands has changed in both RISC OS 3.5 and 3.6, as the range of ROM-based applications has changed. Some applications (eg !Palette) are no longer used, others have been added (eg the Display Manager), and others have moved between the ROM and the hard disc.
All such commands are - as ever - for internal use only, and so we don't list here the *Desktop_... commands available in each version of RISC OS. If you do need such a list, type *Help Desktop_..
From RISC OS 3.5 onwards, *Backdrop supports an extra parameter: -Remove. Its syntax is now:
*BackDrop [-Centre|-Scale|-Tile|-Remove] [filename]
The new -Remove parameter removes the current backdrop.
R1 = &400C0 (reason code)
R2-R7 = values of R0-R5 (respectively) intended for Wimp_ReportError - see Wimp_ReportError (Part 4) and Wimp_ReportError (Volume 5)
R1 preserved to pass on call
R2-R7 = values of R0-R5 (respectively) actually passed to Wimp_ReportError - see Wimp_ReportError and Wimp_ReportError (page 3-176)
This service call is issued immediately after Wimp_ReportError is called, and before Service_WimpReportError 1 is issued. It allows you to change the parameters passed to Wimp_ReportError by altering the values in R2 - R7. You must not alter any memory to which these registers point on entry; you should instead make a copy of the memory, alter that, and change the relevant register to point to your copy.
If you are adding to the list of additional buttons, you must append your new buttons rather than insert them. This avoids any confusion over button numbering should other clients add their own buttons. You should obviously keep track of the position of any buttons you have added.
This service call is only issued by RISC OS 3.5 and later.
You must pass this service call on.
R0 = 0
R1 = &400C1 (reason code)
R2 = button number (1 OK_ 2 CANCEL_ 3 rightmost additional button...)
R3 = pointer to button list as it appeared on the error report
R0 = 0 to return to application
R1 preserved to pass on call
R2 = button number to return (normally unchanged)
or
R0 = 1 to redisplay error report
R1 = 0 to claim call
R2 = pointer to block holding values for new report: words in same order as registers passed to Wimp_ReportError - see Wimp_ReportError and Wimp_ReportError (page 3-176)
This service call is issued when any button on an error report is pressed. You might use it to recognise if one of your additional buttons has been pressed by checking the button number. (Note that other clients may have added extra buttons after yours, and so the list may differ from when the initial Service_ErrorStarting call was issued. Button numbers should remain constant, though.) You can then take appropriate action, such as displaying an extra report.
This service call is only issued by RISC OS 3.5 and later.
You must claim the call if you are going to redisplay the error report.
R1 = &400C2 (reason code)
R2 = button number being returned to application
R1 = 0 to claim call
R2 = button number to return to application
This service call is issued immediately before an error report closes, after Service_WimpReportError 0 has already been issued. It allows you to alter the button number that is returned to the application that created the error report. This is only of real use if you have dealt with the error yourself in some way.
If you do change the button number, you should claim the call; otherwise you should pass it on.
This service call is only issued by RISC OS 3.5 and later.
Manipulates and displays text using the current desktop font
R0 = reason code and flags:
| bits 0 - 7 | reason code |
| bits 8 - 31 | flags (reason code dependent) |
R0 corrupted or used to return data
Other registers typically preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This SWI provides a number of calls to manipulate and display text using the current desktop font.
The particular action of Wimp_TextOp is given by a reason code in bits 0 - 7 of R0 as follows:
| R0 | Action | Page |
|---|---|---|
| 0 | Sets the colour to use for text plotting with Wimp_TextOp 2 | Wimp_TextOp 0 |
| 1 | Gets the width of a string for the current desktop font | Wimp_TextOp 1 |
| 2 | Plots text on the screen using the current desktop font | Wimp_TextOp 2 |
This call is only available from RISC OS 3.5 onwards.
None
None
R0 = 0 (reason code)
R1 = foreground colour (&BBGGRR00)
R2 = background colour (&BBGGRR00)
R0 corrupted
R1, R2 preserved
This call sets the colour to use for text plotting with Wimp_TextOp 2. If an outline font is in use, this sets up the values for the next call to Font_Paint. If the system font is being used, then this sets up the colours by calling ColourTrans_SetGCOL, which will affect future graphics as well as text.
This call is only available from RISC OS 3.5 onwards.
R0 = 1 (reason code)
R1 = pointer to control character terminated string
R2 = number of characters to include, or 0 for whole string
R0 = width of string for current font, in OS units
R1, R2 preserved
This call gets the width of a string for the current desktop font. The width returned is that of the first n characters where R2 = n. If there are less than n characters in the string or R2 
0 then the full string width is returned.
This call might be made before plotting the string in an icon, or before using Wimp_TextOp 2. For instance, it is used by the Filer when calculating the widths of the columns in a directory display.
This call is only available from RISC OS 3.5 onwards.
R0 = reason code and flags:
vertically justify text so baseline matches that of system font right justify text to position given by R4 and R5
This call plots text on the screen using the current desktop font. If bit 31 of R0 is set, then the text is right-justified to the given position. If bit 30 is set then the text will be vertically justified so that the baseline will be the same as for the system font.
This call should be made from a redraw loop; as such Wimp_SetColour or Wimp_TextOp 0 is used to determine what colours are used for the text. Because an outline font may be used, the background colour must be set, so that the antialiasing colours may be found.
This call does not preserve the current font, nor the font colours.
This call is only available from RISC OS 3.5 onwards.
R0 = state (0 DISABLE_ 1 enable)
R1 = code word, or 0 if none
R0, R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call sets the state of the watchdog, and is intended for use by screenlocks and protection mechanisms.
When disabling the watchdog a code word may be supplied, in which case the watchdog may only be re-enabled by supplying the same code word. In this way, another program may not turn the watchdog back on. If R1 was zero on disabling, no code word is required when re-enabling.
This call is only available from RISC OS 3.5 onwards.
None
None
This call is for internal use only; you must not use it in your own code.
R0 = window handle (-1 for iconbar)
R1 = icon handle
R2 - R5 = new icon bounding box
R0 - R5 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call resizes an icon that has already been created. As the icon's bounding box is given, this call may also be used to move an icon.
Although general purpose, it is most likely to be used by an application needing to resize icons after a font changed message. It does not invalidate the area of the icon, although this is not necessary on a font change since the message is always followed by a redraw request.
An error is given if either of the window or icon handle are invalid.
This call is only available from RISC OS 3.5 onwards.
None
This message is used by the Wimp to inform all tasks that the desktop font has changed. This message is only used by RISC OS 3.5 and later.
Tasks that change the desktop font
Any task that changes the desktop font (see *Configure WimpFont) must call Wimp_SendMessage to request that the Wimp broadcast this message. The message itself must include no message data (ie the block is 20 bytes long).
Informing tasks of a change to the desktop font
The Wimp checks for a change in the desktop font at desktop startup, at a mode change, and whenever a task requests that this message be broadcast. It does so by examining the CMOS bits and system variables used by *Configure WimpFont (see *Configure WimpFont).
If it detects a change it loses the current font, and attempts to find the new font with the font manager. If successful, then it selects that font; otherwise it reverts to the system font. The Wimp then broadcasts Message_FontChanged to all tasks, with one word of message data:
R1+20 - Font handle, or 0 for system font
Tasks can use the font handle as they see fit.
The Wimp then issues redraw requests to all windows, so that old applications which do not understand this message will still appear correctly.
Sets the configured value for the font to use on the desktop
*Configure WimpFont n
| n | A number 0 - 15 specifying the font to use: | |
| 0 | use Wimp$Font... variables (see below)
| |
| 1 | use System font
| |
| 2 - 15 | use font from ResourceFS (see below)
| |
*Configure WimpFont sets the configured value for the font to use on the desktop.
A parameter of 1 sets the System font.
Parameters 2 - 15 set a font from ResourceFS, used at a size of 12 points. Starting at Resources:$.Fonts, every directory which has a descendant IntMetric* (eg. IntMetrics, IntMetric0) is numbered consecutively, starting from 2. So on a standard RISC OS 3.5 system the mapping would be:
| Value | Font |
|---|---|
| 2 | Corpus.Bold |
| 3 | Corpus.Bold.Oblique |
| 4 | Corpus.Medium |
| 5 | Corpus.Medium.Oblique |
| 6 | Homerton.Bold |
| 7 | Homerton.Bold.Oblique |
| 8 | Homerton.Medium |
| 9 | Homerton.Medium.Oblique |
| 10 | Trinity.Bold |
| 11 | Trinity.Bold.Italic |
| 12 | Trinity.Medium |
| 13 | Trinity.Medium.Italic |
| 14 | WIMPSymbol |
You must not assume this mapping, since fonts can be added to ResourceFS.
A parameter of 0 tells RISC OS to find the font and size to use from system variables:
| Wimp$Font | the name of the font to use |
| Wimp$FontSize | the size (height) of the font in 1/16ths of a point |
| Wimp$FontWidth | the width of the font in 1/16ths of a point |
The font size and width are both optional. If the size is unset, a value of 192 is used (ie 12 point); if the width is unset, it is the same as the size.
This command is only available from RISC OS 3.5 onwards.
*Configure WimpFont 1 Use system font
*Configure WimpFont 8 Use 12pt Homerton.Medium from
ResourceFS (assuming standard mapping)
Set Wimp$Font NewHall.Medium Set variables specifying NewHall font,
Set Wimp$FontWidth 160 and width of 160/16 points (ie 10 point)
*Configure WimpFont 0 Use system variables to set font
*WimpKillSprite sprite_name
| sprite_name | name of a sprite in the Wimp sprite pool |
*WimpKillSprite removes the given sprite from the Wimp's RAM sprite pool. It should be used with care, as deleting certain sprites will cause some applications to fail.
An error is given if the sprite to be removed is not in the Wimp's RAM sprite pool.
This command is only available from RISC OS 3.5 onwards.