Wimp_ProcessKey
Wimp_Poll: reason code 11 (Lose_Caret)
Wimp_Poll: reason code 12 (Gain_Caret)
Wimp_SetCaretPosition
system font size
escape handling
In conjunction with the colour translations detailed in Wimp.Colours, the Wimp also sets up the system font size to be constant (in OS unit terms) in any mode, thus making the job of application programs easier.
Basically the system font is scaled so that it is always 16 x 32 OS units in size, whatever the resolution of the screen mode in use. This results in double-height characters in mode 20, for example.
The basic approach is for applications to work in OS unit terms, so that if a high-resolution monitor is used, object sizes are NOT changed to reflect the size of the pixels available. Instead, a large monitor would support a mode where the screen is more than 1280 pixels across - thus it is only the Wimp which needs to have special knowledge of the screen dimensions, since all other programs are working inside windows anyway.
The Arthur 1.20 Wimp left escape handling up to the current application, which meant that the application was responsible for acknowledging escape after it had detected it.
In a multi-tasking world, however, the handling of escape must be done differently. The Wimp actually programs the escape key to return the ascii code 27, and so it is the application which owns the caret that deals with escape. No escape events or escape conditions are generated.
If an application wishes to use escape in the old way, it is only allowed to do this as long as it is not calling Wimp_Poll. Thus, if the application intends to perform some long-winded operation without calling Wimp_Poll, it might re-enable escape (*FX 229,0) during the operation to allow it to be aborted. If it does so, it must reset the escape key state (*FX 229,1) before it calls Wimp_Poll again. Note that when restoring the escape key state it is also necessary to acknowledge escape (*fx 126) AFTER the *fx 229,1.
Note that when the Wimp finally exits, it restores the escape handling status to that when it was first invoked (along with function keys, cursor keys etc).
Wimp_ProcessKey was available in Arthur 1.20, but has now been improved to allow for soft key expansion in writeable icons, as follows:
It also allows other utility programs to provide a 'hot key' facility, whereby a special function key code performs some function, without the application needing to have the input focus.
If bit 12 of a window's flag word is set (wf_grabkeys), then any calls to Wimp_ProcessKey will be passed on to the window if it is open. The Wimp will call the topmost window with this bit set first: if the application recognises the code, it should act on it, but if it does not it should call Wimp_ProcessKey with the same code, thereby passing it on to any other windows with this bit set. The Wimp simply returns a Key_Pressed event to the application from Wimp_Poll: note that the values in the block refer to the position of the actual input focus at the time, which may not necessarily be the same as the window with the wf_grabkeys bit set.
If an application wishes to grab keys, but does not want any windows to be visible, it should open a window off the visible screen area with bit 6 set (wf_nochecks). Negative x-coordinates are to be preferred to large positive ones, since the screen size should not be assumed in advance!
If no applications grab the key code, the Wimp will give up and expand the
soft key string if the key was a function key, and the caret is in a
writeable icon.
NOTE: It is not a good idea for the application to act on the key, and then
also pass it on. This kind of behaviour is not helpful to the user!
The Wimp_Poll reason codes 11 and 12 (Lose_Caret and Gain_Caret) have been added so that, if an application displays its caret itself, it can remove it from the screen when another application takes it away.
Wimp_Poll
Exit: R0 = 11
R1 --> block:
R1!0 = window handle of window which HAD the caret
R1!4 = icon handle
R1!8 = x-offset in window
R1!12 = y-offset in window
R1!16 = caret height/flags
R1!20 = index
In theory the application might wish to display some sort of 'stunted' caret in place of the real one, to show where the caret would reappear if it was returned to the window (NB useful if select-block / copy-block used between windows - the actual caret may have moved to a dialogue box in the middle of this operation, but one still wants to know where the destination of the move is).
Wimp_Poll
Exit: R0 = 12
R1 --> block:
R1!0 = window handle of window which HAS the caret
R1!4 = icon handle
R1!8 = x-offset in window
R1!12 = y-offset in window
R1!16 = caret height/flags
R1!20 = index
If the window handle is changing, then a lose_caret message is generated for the old caret position, and a gain_caret message is generated for the new position - note that the caret position may be restored to a position which is not owned by the task which is calling Wimp_SetCaretPosition.
Note that the messages are generated even if the windows are both owned by the same task, and irrespective of whether the application is in control of the caret, or the Wimp is (eg. caret inside a writeable icon).
The specification of R4 (caret height) in this call has been extended:
R4 bits 0..15 = caret height (OS units)
bits 16..23 = caret colour (if bit 26 set)
bit 24 set => use VDU-5 type caret, else font manager caret
bit 25 set => the caret is invisible (application must draw it)
bit 26 set => bits 16..23 are the caret colour (else Wimp colour 11)
bit 27 set => bits 16..23 are a 'real' colour, else Wimp colour
If bits 26 and 27 are set, the caret is plotted by EORing with the colour in bits 16..23 (in 256-colour modes, bits 16,17 are bits 6,7 of the tint, while bits 17..23 are the gcol colour).
If bit 26 is set and bit 27 unset, then bits 16..23 represent a Wimp colour (in the range 0..15). In this case the caret is plotted by EORing with the 'real' colour associated with this wimp colour EORed with the real colour for Wimp colour 0.
If bit 26 is unset, the caret is drawn by EORing with the EOR of Wimp colours 0 and 11 (so that the caret will appear as wimp colour 11 when plotted on a background of wimp colour 0).
Note that if you wish to display the caret on a background which is not Wimp colour 0, you must perform the following: