Wimp_BlockCopy
Wimp_GetWindowOutline
Wimp_PollIdle
Wimp_CommandWindow
Wimp_ReadSysInfo
window flags bit 10 ==> don't use colour translation table
window flags bit 11 ==> don't open any other windows below this one
window flags bit 12 ==> grab 'hot keys' (see Wimp.Text)
window areaCBptr =1 ==> use common sprite area
window bounds changed to cover whole screen
window min x,y can be supplied
Service_MouseTrap provided for mouse-exec utilities
Wimp_GetPointerInfo bug fixed (oldbuttons not returned now)Entry: R1 --> block
+16 icon handle
On Arthur 1.20, this call used to return an extra word in [R1+20], which was not documented. It now doesn't return it.
R5,R6 = bottom-left of destination (in window coordinates)
This call can be used to copy an area of a window's work area to another position within the window. It will block-copy as much of the rectangle as it can, and will mark invalid any parts of the destination rectangle which could not be copied from the source (because it was not visible).
This call allows text editors, for example, to optimise the repainting of their data when inserting or deleting lines of text. It copes with the problems involved with dealing with multiple visible rectangles.
+4 x0, y0, x1, y1 (bounding box of window outline on screen)
This call should be used if, for example, a program wishes to confine the mouse pointer to the rectangle covering the window (including the borders).
This call is useful for programs which maintain an animated display of some sort (eg. a clock), allowing them to wait for a specified amount of time without chewing up CPU time.
The time specified in R2 relates to the values returned by OS_ReadMonotonicTime, which the Wimp calls to work out when the time limit is up. When a null event is received, the application should perform its normal graphical output, then add the appropriate amount of time to the time it previously passed to Wimp_PollIdle (rather than adding on to the current time). In this way the problem of time 'slipping' is avoided.
One problem with this approach, however, is that if some program decides to 'hog' the CPU for several seconds, then a clock can find itself several seconds behind. When called again, instead of immediately catching up, it may end up being called continuously for a while until its internal time catches up with the actual time. To get round this problem, it is recommended that programs such as clocks move forward in whole seconds from their previous time until the new time is greater than the current time.
R0 =-1 ==> close command window, without any fuss
This facility has been provided to deal with those awkward situations where old-style text-based programs need to be run, which rely on the screen being organised like a teletype (ie. they run in 'VDU 4' mode).
When Wimp_CommandWindow is called with R0>0, the Wimp marks the command window as 'pending', and intercepts WrchV. When the first character is sent to the screen, the command window is displayed and a text window opened within it. The command also causes the setting of the escape enabled bit, the soft keys and cursor keys to be set to their normal values outside the Wimp. When the command window is closed, these values are restored.
This facility is used by the Wimp itself when starting tasks, since it is not possible to determine in advance whether a task will use the Wimp for its output, or will simply send 'printable' characters to the screen. If the task calls Wimp_Initialise, the command window is closed and never appears on the screen, but if characters are sent to the screen, the window is opened to receive them.
Note that the Wimp_ReportError command takes note of whether a command window is pending or active: if the window is active, the error is reported within the text window, but if the window is dormant or merely pending, it is marked as 'suspended' for the duration of the error report, and the error is reported in a window. Note that UpCalls to deal with disc swapping use Wimp_ReportError, and so benefit from this code (see Wimp.Errors for further details). For this reason the ShellCLI module calls Wimp_CommandWindow with R0 = 1, so that the Wimp treats the command window as being open, and reports errors as lines of text (rather than in the error window).
The Filer and ADFS Filer also use the Wimp_CommandWindow facility, when invoking old-fashioned commands such as *Copy and *Backup. The command is especially useful for *Copy, since depending on the user's setting of the Copy$Options variable, the command may or may not result in output being sent to the screen.
This call is provided to cover all those niggling little things that do not fit nicely anywhere else.
Currently the only value that is returned by this call is the number of active tasks. This value may be used by an application to determine whether or not it is running in the Wimp environment. If it is, then the number of active tasks will be greater than zero; if not, the number of tasks will be zero.
bit 10 set ==> don't use colour translation table
If this bit is set, the window colour bytes are to be used directly, rather than indirecting via the Wimp colour table (see Wimp.Colours). This feature is intended for use in 256-colour modes, where the range of colours available via the Wimp colour table is limited.
Note that any application using this facility must ensure that it takes special action in other modes, since the Wimp's automatic mode-independence will not apply to such windows. There is also a problem with this: colour 255 in the work area background colour or title foreground colour means 'not present', ie. don't paint work area background / window has no border.
bit 11 set ==> don't open any other windows below this one
This bit is set in the iconbar window (see Wimp.IconBar) and the 'background window', used when an old-style task is started up (see Wimp.Desktop).
bit 12 set ==> grab 'hot keys' if the window is open (see Wimp.Text)
window areaCBptr =1 ==> use common sprite area
See Wimp.Sprites for further details.
window bounds: changed to cover whole screen
window min x,y
Wimp_CreateWindow: block!68 = min x,y window size (low 16 bits = min x, high 16 bits = min y). The actual minimum size of the window is the maximum of this value and the minimum size as calculated by the Wimp.
Note that this word was reserved on Arthur 1.2 - this means that it should be set to 0, but just in case the Wimp actually sets this word to zero if the task is an old-style one.
This service call is provided by the Wimp to facilitate the contruction of utility programs which remember mouse movements by the user, usually in order to play them back. The problem is that, in order to save memory, such programs usually only record the mouse position when one or more of the buttons change state, or after a specified time delay. Unfortunately there are certain user operations which do not require a change in button state, but whose timing is critical (eg. moving onto a menu arrow or performing a drag operation). The problem is that if the program 'misses' the crucial mouse position, the result of playing back the mouse events recorded is different from the original effect.
So, to get round the problem the Wimp issues a Service_MouseTrap at the crucial moments (ie. wherever an important mouse position has been acted on, but which did not require a change in the button state. Thus a utility which was recording mouse events would explicitly include the one given by the Service_MouseTrap (in addition to any which required a change in the button state).
Note that any Wimp applications which also respond to a particular mouse position, without requiring a change in the button state (in practice this is rare) should also issue this service.
To issue the service call one should perform the following:
SWI OS_ServiceCall
R0 = mouse x
R1 = Service_MouseTrap (&52)
R2 = mouse button state (cf. OS_Mouse)
R3 = time of mouse event (cf. OS_ReadMonotonicTime)
R4 = mouse y
Note that R4 = mouse y rather than R1, since that register is already used!
In service call handlers, never corrupt any of R0-R6, unless the issuer of the service call is explicitly expecting certain registers to change. For example, it is OK to set R1=0 in order to claim a service call, but none of the other registers below R7 should be affected unless they are used to pass back results.
The importance of not corrupting these registers cannot be over-emphasised - some of the most insidious bugs of all stem from registers not being preserved over service calls.
You have been warned!