> net#arf:$.a500.RiscOS+.doc.Wimp Author: Neil Raine Status: changes to Wimp documentation for PRM History: 13-Sep-89 NRaine History section added. 14-Sep-89 NRaine Changes for Wimp 2.34 added. 21-Sep-89 NRaine Changes up to Wimp 2.38 added. 2-Oct-89 NRaine Added 'hints and tips' section 18-Oct-89 NRaine Changes up to Wimp 2.45 added. 20-Oct-89 NRaine Stuff for TaskManager 0.32 added. 24-Oct-89 NRaine Stuff about icon flags bit 7 added. 25-Oct-89 NRaine Changes up to Wimp 2.50 added. 25-Oct-89 NRaine Extra documentation added to last section 26-Oct-89 NRaine Fixed bug in Message_PreQuit section 27-Oct-89 NRaine Changes up to Wimp 2.52 added. 16-Nov-89 NRaine Changes up to Wimp 2.61 added. 9-Dec-89 NRaine Added Wimp_SlotSize bug, reworded mode change stuff 26-Feb-90 NRaine Added *WimpWriteDir, Wimp_ReadSysInfo (4), backward menus 26-Feb-90 NRaine Added Wimp_CreateIcon stuff with handle -5 to -8 10-Apr-91 RMokady Updated to reflect Wimp 3.00 for Risc OS 2.5 Documentaton updates since RISC OS 2.00 release (Wimp 2.00) ----------------------------------------------------------- As the Wimp is developed, it is often necessary to make alterations or additions to the application interface. Sometimes this can be done in such a way that the new behaviour is 'back-compatible' with the old (ie. it will not confuse applications which do not know about the extension), for example where a reserved field can be set non-zero to enable the new feature. However, it is occasionally necessary to make changes that could potentially confuse an application which was not aware of them. In order to cope with this, the Wimp allows an application to inform it of how much it knows, by supplying the version number of the latest release of the Wimp which the programmers have taken into account: SWI Wimp_Initialise R0 = latest known version of Wimp * 100 R1 = "TASK" R2 -> task name string Applications written for RISC OS 2.00 should all have R0 set to 200 when calling Wimp_Initialise. This allows the Wimp to provide 'incompatible' new facilities only to those applications which it knows are aware of them, thereby avoiding compatibility problems with the others. In many cases a 'compatible' extension can be made, where it is clear to the Wimp whether or not the application is trying to use the new facility, so not all extensions require the application to 'know' about the later version of the Wimp. The following extensions are grouped according to which version of the Wimp the application must know about: note that extensions for a given version of the Wimp also apply to any subsequent versions, so if R0 is set to 300, then all features up to and including those in Wimp 3.00 are enabled. Under Risc OS 2.5 an application can only pass 200 or 300 to Wimp_Initialise. The wimp will give an error if any other value is passed in. Changes applying to Wimp 2.00 ----------------------------- The following changes apply to any task, even those passing 200 to Wimp_Initialise * If you press ESCAPE when a Wimp_ReportError box is up, Wimp 2.00 would always return R1=1, even if the CANCEL box was highlighted. The new Wimp actually returns the code for the NON-highlighted box, ie. R1=2 if OK was highlighted, and R1=1 if CANCEL was highlighted. Pressing any other key selects the highlighted box, and returns 1 or 2 as appropriate. In either case, if the box that would have been selected is not present, the other box is selected. * If any error occurs inside Wimp_Poll (apart from an error in the parameters to the call), it is reported by the Wimp itself, and is not passed back to any of the applications. * If an Escape Condition is pending when Wimp_Poll is called, or if Escape Conditions are enabled, the Wimp will report an error, and will cancel the escape condition and disable escape condition generation. The old Wimp would simply go wrong if an escape condition became pending during Wimp_Poll (keyboard scanning would cease to work). * If a window is deleted while being dragged, an error is reported by the Wimp, except in the case of a menu, where pressing escape causes the drag to terminate and the menu tree to be deleted. * The pointer position is preserved over a mode change. * Wimp_CreateMenu now correctly returns an error if the top-level menu window could not be created (rather than just leaving it half-created). * When the pointer moves over a writeable menu item, the previous menu item is deselected. Also, if right-click is pressed on a writeable item, the caret correctly returns to the item when the menu tree is reopened. * On the next call to Wimp_Poll after a mode change, the Wimp issues Message_ModeChanged and Open_Window_Requests for all open windows. If the new mode is smaller than the previous one, the windows are also forced back onto the screen. * The mode change message and the re-open window messages are suppressed if the current task is an old-style one (ie. R1<>"TASK" on entry to Wimp_Initialise). Another mode change will always occur before the task exits back to the desktop. * The new command *WimpMode can be used to set the current Wimp mode without affecting the configured value. If the desktop is active, the mode change will be executed immediately, otherwise it will take effect when the desktop starts. Note that this command should not be used in the product-release form of applications: it is provided so that the user can set up the Wimp mode in his boot file. It may also be useful in the !Run sequence of an Arthur 1.2 task, where setting WimpMode 12 will improve the compatibility of the Wimp with the Arthur version. Note that it is not implemented in Wimp 2.00, though! * Window extent supplied in Wimp_CreateWindow and Wimp_SetExtent is automatically rounded to be a whole number of pixels (and is re-rounded on a mode change). The Wimp cannot properly cope with extents which are not a whole number of pixels, so it used to be possible to confuse it. * If bit 14 of a window's flags is set, then when the size box of the window is dragged, the right-hand extent is ignored. Thus the window owner can receive OpenWindowRequests for positions outside the current extent of the window. It can then call Wimp_SetExtent as required, and call Wimp_OpenWindow - in this way a window's extent can be made 'elastic'. Bit 15 of the window flags performs the same function for the lower extent of the window. * Double-click can no longer be accomplished using different mouse buttons for the first and second clicks. * During the time that a double-click is 'pending' (ie. after the first click but before the second), the Wimp changes pointer shape 1 to the sprite "ptr_double" in the common Wimp sprite area. As soon as the double-click is cancelled, the pointer reverts to the "ptr_default" shape. Note that the displayed pointer shape will not immediately change if an application has set pointer shape 2 at the time. * New configuration values have been added to configure the delay and distance the mouse has to move before a drag is started, and the delay and distance the mouse has to move before a double click is canceled. * A pending double-click will be immediately cancelled if any of the following occur: + Wimp_DragBox is called (eg. in response to a drag button event). + The pointer moves by more than the configured number of OS units. + The mouse is not clicked again inside the configured amount of time. (*Configure WimpDragMove, WimpDragDelay) * The time-limit for a drag button event is now configurable by the user A drag will be immediately reported if a mouse button is held down and the pointer is then moved by more than the configured number of OS units. (*Configure WimpDoubleClickDelay, WimpDoubleClickMove) * Right-dragging on either scroll bar of a window with 2 scroll bars causes a bi-directional scroll, where both scroll bars can be dragged at once. This can alo be started up by calling Wimp_DragBox type 12 (other parameters are as for drag types 1..4). The pointer is turned off during the drag. * Wimp_StartTask now returns R0=handle of task started, if it is still alive (0 otherwise). * If WimpFlags bit 5 is set, then windows which do not have bit 6 set (no screen bounds) are still allowed to move partly off the screen in response to a drag of the title bar. Windows are only allowed to go off the screen down and to the right. * If WimpFlags bit 6 is set, then windows which do not have bit 6 set (no screen bounds) are still allowed to move partly off the screen in all directions. In fact the windows are still restricted in the following circumstances: 1) If window flags bit 13 is set 2) If the window is being opened, and was closed 3) If a toggle-to-full-size occurs 4) While you are dragging the size box 5) Immediately after a mode change 6) On the next call to Wimp_OpenWindow after Wimp_SetExtent is called for a window which is fully on-screen at the time. In cases (3) to (6), the Wimp sets bit 21 of the window flags, which causes the window to be restricted to the screen area for one call to Wimp_OpenWindow only (this causes the bit to be cleared). Case (2) means that when a window is first opened it will be forced onto the screen, but can subsequently be dragged off by the user. If you are dragging the size box of a window, and you move the pointer off the bottom-right of the screen, the Wimp will try to make the window bigger. If it succeeds, the window will be forced onto the screen, so it will appear to grow upwards and left. The speed of growing can be controlled by how far the pointer is off-screen. Window flags bit 21 is also set automatically by the Wimp when a menu or a dialogue window is opened as a result of the pointer moving over the relevant submenu icon, or as a result of a call to Wimp_CreateMenu or Wimp_CreateSubMenu. This forces the menus onto the screen normally, but allows them to be dragged off-screen if desired. Bit 13 of a window's flags can be set to indicate that it should be kept permanently on-screen. * The iconbar scrolls if the pointer is moved over either end, even if an object is being dragged. { The following should not be documented in the PRM !!!!!!!!!!! } {--------------------------------------------------------------------} * Wimp_CreateIcon can have more parameters which relate to creating icons on the iconbar: [R1,#0] = -3 => create icon on iconbar to left of icon handle R0 -4 => create icon on iconbar to right of icon handle R0 R0 = handle of icon to open next to, if [R1,#0] = -3 or -4 R0 = -1 => create icon at extreme left (-3) or right (-4) This allows icons to be recreated and deleted (in order to change their width, for example) such that they stay in the same relative position on the iconbar. It also allows applications to keep groups of iconbar icons together. { -------------------------------------------------------------------- } The following is what should be in the PRM, it should say that -3 and -4 are reserved. Wimp 2.73 also supports prioritising of iconbar icons, so that for example, the RAM disc icon can be positioned immediately to the right of the Apps icon. [R1,#0] = -5 => create icon on left side, scanning from the left -6 => create icon on left side, scanning from the right -7 => create icon on right side, scanning from the left -8 => create icon on right side, scanning from the right R0 = signed 32-bit priority (higher priority => towards outside) The Wimp positions the icons so that they are sorted, with those of higher priority nearer the extreme ends of the iconbar. Where icons are of equal priority, the position of the new icon is determined by the scan direction. The priorities assumed for the other possible window handle values are: handle = -1 priority = 0 handle = -2 priority = 0 handle = -3, R0 = icon handle priority = same as matched icon handle = -3, R0 = -1 priority = &78000000 handle = -4, R0 = icon handle priority = same as matched icon handle = -4, R0 = -1 priority = &78000000 The various Desktop modules create icons with the following priorities: Task Manager &60000000 !Help &40000000 Palette Utility &20000000 Applications 0 ADFS hard discs &70000000 ADFS floppy discs &60000000 "Apps" icon &50000000 RAM disc &40000000 Ethernet &30000000 Econet &20000000 Other filing systems &10000000 Printer drivers &0F000000 TinyDirs -&40000000 * If R1 bit 7 is set on entry to Wimp_ReportError, the Wimp will not produce a 'beep' even if WimpFlags bit 4 is clear. * "*IconSprites " is now treated slightly differently by the Wimp: it will first try to add a suffix which depends on the properties of the configured Wimp mode, and if this doesn't work, will use the original filename as usual. If the configured Wimp mode is a hi-res mono mode (ie. bit 4 of the modeflags is set), then it will use the suffix "23"; otherwise the suffix is "". eg: Configured Wimp mode Suffix 23 "23" 20 "22" 12 "24" This allows applications to easily provide an alternative set of icons for hi-res mono modes (when using the new Wimp). For example, an application could provide a set of colour sprites in a file called "!Sprites", and an alternative monochrome set in a file called "!Sprites23", and then load one set or the other automatically by using "*Iconsprites .Sprites". * The Wimp now picks up its ROM sprite area from a file inside Resources: (without copying it into RAM). If the current Wimp mode is hi-res mono when the Wimp looks in Resources:, it will use "Resources:$.Resources.Wimp.Sprites23"; otherwise it uses "Resources:$.Resources.Wimp.Sprites". The Wimp re-finds the file when either it or the ResourceFS module is re-initialised (the latter issues Service_ResourseFSStarting and Service_ResourceFSDying to inform the Wimp). * SWI Wimp_ReadSysInfo takes the following extra possible arguments: In: R0=1 gives R0 = current Wimp mode on exit R0=2 gives R0 -> iconsprites filename suffix for the configured mode. When loading sprite files containing icons, the suffix should be tried - if the file does not exist, try the original filename. R0=3 gives R0 = 0 => we are in text output mode (ie. outside the desktop, or in the ShellCLI, or in a command window). R0 = 1 => we are in the desktop other values reserved (test for non-zero when looking to see whether we're in command mode or not). R0=4 gives R0 = 0 => left to right text entry R0 = 1 => right to left text entry this returns the state last set by *WimpWriteDir. * The Wimp supports a code variable "Wimp$State", which can take the following values: "commands" Wimp_ReadSysInfo (3) returns 0 "desktop" Wimp_ReadSysInfo (3) returns 1 other values should be treated as 'not "commands"'. * Maximum number of created windows is now unlimited (actually &7fff), not 64. * There is no limit on the number of memory pages that the Wimp can cope with. However, beyond 16Mb of memory, RISC OS will not work correctly, as it may not be possible to fit all the spare memory into application space. Previously the Wimp had a limit of 256 memory pages. * An attempt to set the Wimp into a double-pixel mode using Wimp_SetMode now returns a "Bad Wimp mode" error. * The following routines are now allowed to take a window handle of -2 to indicate the iconbar (in addition to those which allowed it in Wimp 2.00): Wimp_GetWindowState Wimp_GetWindowInfo Wimp_GetWindowOutline Wimp_ForceRedraw Wimp_DragBox Wimp_WhichIcon * The default action of Shift-f12 is to toggle the iconbar between front and back as follows: The 'backwindow' bit of the iconbar's window flags is toggled. If the 'back' bit of the iconbar is now set, it is sent to the back, otherwise it is brought to the front. When the iconbar is brought to the front, bit 11 of its window flags ('backwindow') is cleared, and when it is sent to the back, this bit is set. This ensures that the iconbar only has the 'backwindow' bit set when it is at the back. * In Wimp 2.45 onwards, the following extra features have been added: Wimp_GetWindowInfo R1 bits 2..31 -> buffer to receive data R1 bit 0 set => just return window header (without icons) R1 bit 1 reserved (must be 0) Wimp_LoadTemplate In R1 <= 0 => return R1 = size of buffer required R2 = size of indirected data Out [R5..] = actual name only if [R5..] on entry was wildcarded No error is generated for objects of type <> 1: the object is simply loaded into the buffer, and no indirected data processing occurs. This is different from Wimp 2.00, which reported an error in these circumstances. * The following new message has been defined: Message_TaskStarted (&400C8) This is sent by the Filer after it has started up all its children so that the TaskManager can 'renumber' it. This is so that during the deskboot saving sequence, the Filer_Boot and Filer_OpenDir commands are inserted after the logons returned by the NetFiler. * A change has been made to Message_PreQuit: R1!0 = 24 (size) R1!16 = Message_PreQuit (8) R1!20 = flag word: bit 0 set => just quit this task, else desktop being quit bits 1..31 reserved (ie. ignore them) This allows applications to tell whether they should restart the desktop closedown sequence after prompting the user to save any unsaved data. If bit 0 of the flag word is set, then the task should not send a ctrl-shift-f12 key_pressed event to the task which sent it the PreQuit message, to restart the closedown sequence, but should instead just terminate itself. Note that if the flag word is not present (ie. the block is too small), the task should treat the flag word as having been zero. * Clicking on a greyed-out menu item now has no effect. Previously it used to return a Menu_Selection event (9), with the menu selection index of the last item set to -1. Unfortunately this was indistinguishable from the result returned when clicking on the parent menu item. * Message_MenusDeleted (&400C9) is returned by the Wimp, with block!20 = menu pointer for the menu tree that was deleted, in the following circumstances: If a task has a menu tree open, and another task calls Wimp_CreateMenu, thereby deleting the first tree. If a task has a menu tree open, and it calls Wimp_CreateMenu with a different menu pointer than the one last used. If a task has a menu tree open, and the user clicks somewhere outside the menu tree, thereby closing it. The Wimp now sends mouse clicks as messages if the message queue is not empty, which ensures that the click event arrives after the Message_MenusDeleted. Note in particular that no message is returned if a menu selection event is returned, or if a menu tree is replaced by another with the same menu pointer. * The Wimp now deals with shaded menu items somewhat differently. If you click ADJUST on a greyed-out menu item, nothing happens, whereas if you click SELECT or MENU on a greyed-out menu item, the menu tree is deleted and no menu selection event is returned. This is because it was impossible for an application to distinguish between a click on a greyed-out menu item and a click on the parent item for that menu, as the selection index for a greyed-out menu item was -1, the same as the terminator. * Shaded icons in menus are treated differently from normal shaded icons, in that the latter are treated as being 'invisible' to the Wimp - Wimp_GetPointerInfo will never return them. In menus, however, the icons are not invisible, but are not allowed to be selected. This allows the interactive help program to see the icons and to ask for help on them. * If you set bit 4 of a menu item's flag word (not the icon flags), then even if the item is greyed-out (icon flags bit 22 set), you can open the submenu if it has one. This allows a non-leaf node to be greyed-out without preventing the user from seeing the submenu. * If a menu title starts with "\", then it and all submenus opened off it are reversed, that is: Ticks appear on the right, arrows on the left Submenus are opened to the left (including Message_MenuWarning ones) Left-justified menu items are right-justified, and vice-versa * The command "*WimpWriteDir {0|1}" allows the direction of writeable icon text entry to be reversed (0 => left to right, 1 => right to left). The default is left to right. * The command "*WimpTask" allows a Wimp task to be started from within a command script. It works as follows: If the command is issued from within a running Wimp task, then *Wimptask causes SWI Wimp_StartTask, R0 -> "". If the command is issued from outside the desktop, or from a task that has not called Wimp_Initialise, then *WimpTask causes the Window Manager module to be entered as an application with as its parameter string. The Wimp's application entry point calls Wimp_Initialise, then issues SWI Wimp_StartTask with R0 -> "", and then calls OS_Exit. The reason for all this messing about is that it is not possible to call Wimp_StartTask from within a "dead" task, since the Wimp would not know how to return to the dead task after starting the required task. In order to start a task, it is necessary to be a "proper" application, and to be running in USR mode - this is why the Wimp is entered. The important thing to know about *WimpTask is that it will exit via OS_Exit if you call it from outside a Wimp task. * Bugfix in SWI Wimp_SlotSize: this call used to corrupt R4 on exit if the current slot was made larger. This has now been fixed. * You can now set the size of the next slot as follows: *WimpSlot -next K The -min keyword in *WimpSlot is now optional. * The values returned from Wimp_ReadPalette are analogous to those returned by OS_ReadPalette, in that they always have the bottom nibbles clear. These colours are not correct for passing to ColourTrans: you have to make the bottom nibbles into copies of the top ones. * If shift is held down when the close tool of a window is clicked, the wimp does not close the window, but instead send a Message_Iconize containing: Message_Iconize: +20 Window handle. +24 Task handle for task which owns the window. +28 20 Bytes of title string. (last part of first word) +48 * Whenever a window is closed the Wimp broadcasts the following message: Message_WindowClosed +20 Window handle. +24 * It is now possible to open a window behind window -3, this will open the window behind the Wimp's backwindow, hiding it from sight. * The max. number of tasks that can be active at any one time is now 128 (was 32) * When Wimp_StartDrag is called, giving user Plot/Unplot/Move routines, the Plot routine is now called before the Unplot or Move routines, on 2.00 the Unplot routine was called first. * If Shift is held down when the Toggle Sixe tool is clicked, the window will be opened as big as possible without covering the icon bar. * Validation string for indirected text icons can now have a B (Border) command to set the border type for the icon. The border will only be drawn if the border bit for the icon is also set. B, To set the icon's border type (This will override the Wimp's default border for the icon). Where type is: 0: 3d raised border. 1: Group border. 2: Default action border. 3: Writable icon border. 4: Pressed 3d border. 5: Normal 2d border. 6: Pressed type 2 border. Border type 0 changes to 4 and 2 changes to 6 when a mouse event is about to be reported to the application, and changes back when you release the mouse button, or when you move the pointer away from the icon. It will not change if the icon's button type means that the click is not reported to the application. The Slab in colour is used to set the icon's background colour just before a mouse click is reported to the task. * Validation strings for indirected icons can now have a P (Pointer Shape) command. P,active_x,active_y To change the pointer shape while over the icon. Default sprites provided in the wimp sprite area are: Name Active point ptr_write 4,4 ptr_menu 6,5 ptr_direct 13,7 ptr_hand 12,8 ptr_cross 13,7 * The wimp supports a new SWI: Wimp_RegisterFilter Registers a filter to be called on call to or before return from Wimp_Poll Entry: r0 - reason code: 0 - Register / Deregister Pre-Filter 1 - Register / Deregister Post-Filter r1 - Address of filter, or 0 to de-register. r2 - Value to be passed in R12 on entry to filter. Exit: Registers preserved. A pre filter is called whenever a task calls Wimp_poll: On Entry: R0 = Event mask as passed to Wimp_Poll R1 -> User block as passed to Wimp_Poll. R2 = Task handle. R12 = Value of R2 when registered. On Exit: R0 May be modified by the filter. All other register and processor mode must be preserved A post filter is called when the Wimp is about to return an event to a task. On Entry: R0 - Event code for event that is about to be returned. R1 -> Event block for event to be returned. (Owner task paged in) R2 = Task handle of task that is about to receive the event. On Exit: The filter may modify R0 and the contents of the buffer pointed to by R1, to return a different event. R1,R2 must be preserved. If R0=-1 on exit, the event will not be passed to the task. This SWI is provided for the use of the FilterManager, and should not be used unless you want to replace the whole filter system. Use the FilterManager to register filters for specific tasks. * If WimpFlags bit 7 is set and the pointer is kept on a non-leaf menu item for more than the time specified by *Configure WimpAutoMenuDelay then the submenu will be opened automaticaly by the Wimp. Changes applying to Wimp 2.18 or later --------------------------------------- * If a message is sent to a menu window, then it will be delivered to the task which opened the menu tree. This applies to any reason code greater than CloseWindowRequest, as well as the messages (open, close and redraw are all dealt with automatically by the Wimp). Typically such a message will contain the window handle of the menu window, which will not be recognised by the menu owner. However, it cn make use of the following call to find out which part of the menu tree it corresponds to: Wimp_GetMenuState R0 = 0 => report current state of tree, ignoring R2,R3 R0 = 1 => report tree which leads up to R2,R3 R1 -> buffer to contain result R2 = window handle R3 = icon handle The tree is put into the buffer in R1 in the same format as that returned by Wimp_Poll reason code 9 (Menu_Select), ie. a list of selection indices terminated by -1. The tree returned will be null if R0=1 and the window/icon in R2/R3 is not in the tree, or if R0=0 or 1 and the menu tree is owned by a different application, or is closed altogether. If the window is a dialogue box, the tree returned will go up to (but not include) the dialogue box. Changes applying to Wimp 2.23 ----------------------------- * Wimp_Poll or Wimp_PollIdle can be called as follows: If R0 bit 13 is clear, then: R0 bit 22 set => scan 'poll word' pointed to by R3 R0 bit 23 set => scan the poll word at high priority R3 -> poll word (NOT in application space) The Wimp will normally scan the word after delivering any outstanding messages and issuing any Redraw_Window_Requests that are required, so that the application can then update its windows etc. as required. If R0 bit 23 was set, the poll word will be scanned before the messages or the Redraw_Window_Requests are delivered. Note that this means that the screen may not yet be up-to-date, and certain messages may not have been delivered (in particular Message_ModeChange). If the Wimp discovers that the word has become non-zero, it will return the following event from Wimp_Poll: R0 = 13 (PollWord_NonZero) [R1,#0] = address of poll word [R1,#4] = contents of poll word This facility is used to transfer control to a task's foreground process, where control is currently in an interrupt routine, service call handler or the like. For example, the NetFiler module intercepts a special service call which is issued by NetFS whenever a *Logon, *Bye or *SDisc is executed. This tells NetFiler that it should re-scan its list of fileservers and update the iconbar as appropriate, but it cannot do this directly because it needs to get control in the foreground in order to call the Wimp. It therefore sets a flag in its workspace, which tells it that it should rescan the list the next time the Wimp returns to it from Wimp_Poll. Using the new facility, it can use a 'fast poll' to get the Wimp to tell it BEFORE the screen is up-to-date, which means that if the user issues a *Logon from within ShellCLI, the NetFiler can update the iconbar before the screen is redrawn when ShellCLI returns, and so the iconbar does not have to be redrawn twice. A more normal application for this would be for a background process to buffer incoming data in the RMA, and to signal to its foreground process when there was enough data to use. It would normally use the 'slow' form of polling, so that it could update its window with the new data. Note that there is still no guarantee about how long it will take before the application regains control, since other applications can take control away from the Wimp for arbitrarily long periods of time (eg. ShellCLI). * Wimp_Poll or Wimp_PollIdle can be called as follows: R0 bit 24 set => save / restore FP registers R1 -> poll block R2 = earliest return time (for Wimp_PollIdle) R3 -> poll word (if R0 bit 22 set - see above) The floating point registers should only be saved if one or more of the following is true: * The task is controlling arbitrary applications 'underneath' it, which may use floating point instructions. An example of such a controlling task is the TaskWindow module. * The task requires to set up a floating point status register value that is different from that used by the C run-time system (which happens to be &70000). This is because in general other C programs running under the Wimp that use floating point will not save their FP registers, but will assume that the status register is still correct for the C run-time environment. To enable this to work, the Wimp resets the FP status register to the correct value for the C run-time environment immediately after saving the FP registers for a task that requests it. There is one complication with this: when the Wimp comes to save the floating point registers for a task, it is possible (when using the actual FP hardware, as opposed to the emulator) for an asynchronous exception to be generated (eg. after a divide by 0, the next FP instruction is the one that actually generates the error). In this case OS_GenerateError is called by the FP support code, once it has determined the cause of the exception. The important point here is that the error is passed to the task whose FP registers were being saved. When OS_GenerateError is called, the supervisor stack is cleared out, so it is as though the Wimp_Poll call never happened. Note that the error number here has the top bit set, which indicates to the error handler that execution cannot be resumed after the PC address where the error occurred. Changes applying to Wimp 2.86 and above ---------------------------------------- Tasks knowing about Wimp 2.86 or later have to provide an extra argument to Wimp_Initialise. Wimp_Initialise now becomes: R0 = latest known version of Wimp * 100 (300) R1 = "TASK" R2 -> task name string R3 -> A list of message numbers terminated by a 0 word. The task will only receive messages which are included in the list. the list should not (and cannot) include Message_Quit (0) as this message will always be delivered to all tasks. Documentation that relates to Wimp 2.00 as well ----------------------------------------------- Update of writeable icons: If an application wishes to update the contents of a writeable icon directly, while the caret is inside the icon, then it cannot in general simply write to the icon's indirected buffer and make sure it gets redrawn. The general routine goes as follows: REM In: window% = window handle of icon to be updated REM icon% = icon handle of icon to be updated REM buffer% = address of indirected icon text buffer REM string$ = new string to put into icon DEF PROCwrite_icon(window%,icon%,buffer%,string$) LOCAL cw%,ci%,cx%,cy%,ch%,ci% $buffer% = string$ SYS "Wimp_GetCaretPosition" TO cw%,ci%,cx%,cy%,ch%,ci% IF cw%=window% AND ci%=icon% THEN IF ci% > LEN($buffer%) THEN ci% = LEN($buffer%) SYS "Wimp_SetCaretPosition",cw%,ci%,cx%,cy%,-1,ci% ENDIF PROCseticonstate(window%,icon%,0,0) :REM redraw the icon ENDPROC Basically if the length of the string changes, it is possible for the caret to be positioned off the end of the string, in which case nasty effects can occur (especially if you delete the string terminator!). Deleting and creating icons: Using Wimp_CreateIcon and Wimp_DeleteIcon to create and delete icons has certain disadvantages: the window is not redrawn, and the icon handles can change. An alternative is to use Wimp_SetIconState to set and clear the icon's 'deleted' bit (bit 23). However, it should be noted that when calling Wimp_SetIconState to set bit 23 of the icon flags (ie. to delete it), the icon will not be 'undrawn' unless bit 7 of the icon flags ('needs help to be redrawn') is also set. This is because icons without this bit set are simply redrawn on top of their old selves without filling in the background, to avoid flicker. Thus to delete an icon, use: block%!0 = window_handle% block%!4 = icon_handle% block%!8 = &00800080 :REM set block%!12= &00800080 :REM bits 7 and 23 SYS "Wimp_SetIconState",,block% and to re-create it, use: block%!0 = window_handle% block%!4 = icon_handle% block%!8 = &00000000 :REM clear block%!12= &00800080 :REM bits 7 and 23 SYS "Wimp_SetIconState",,block% Note that when re-creating the icon, bit 7 should normally be cleared, to avoid flicker when updating the icon.