|
www.riscos.com Technical Support: |
The Character Input system can get characters from the computer's input devices. They can be any one of the following:
It gives full control of the operation of each of these devices. Since they all have different characteristics, they must be controlled in different ways.
It provides a means of directing characters from the selected device to the program that requests them. It can also hold them, waiting until the program is ready to take them.
For details of input to Wimp applications, see the chapter entitled The Window Manager.
Before you read this chapter, you should have read the Character Output. In many ways, character input and output are one entity, which has been logically split in this manual. So there are some things which are mentioned there and not here that apply to both chapters.
Like character output, a stream system is used by character input. Here, you can select from one of three streams; keyboard, serial and file. Only one stream can be selected at once otherwise data coming from two places would get jumbled. Direct control of devices is available, especially in the case of the keyboard.
Any program taking input from the stream system doesn't have to know where characters are coming from. Most programs don't since it will not affect the way they run.
The core of the input stream is OS_ReadC which gets a single character from the currently selected input stream. It is in turn called by many other SWIs, OS_ReadLine for example. This device independence makes programs much easier to write.
Like character output, all input streams are buffered. Input devices are asynchronous to programs and must have their characters stored in a temporary place in memory until required. A good example of buffering in use is a terminal emulator program. It waits until something appears at the serial input buffer, then sends it to the VDU. At the same time, it waits until something appears in the keyboard buffer and sends it to the serial output buffer. Because of the buffering of inputs and outputs, the program can do all this at its own pace.
The keyboard is the most used part of character input, and its driver the most complex. In principle it is simple enough, but many features are changeable and key presses can be looked at in a number of ways.
The keyboard driver is actually two sections. One, which is fixed, handles the keyboard interrupt and low-level control. It feeds the raw code onto the second part, the keyboard handler.
The keyboard handler converts the keycode into an ASCII form, with extensions for special characters. This can be replaced by a custom version if required.
At a basic level, the keyboard works like this:
When a program wants a character from the input stream (in this example, the keyboard):
Also, there are a number of extra operations that the keyboard driver can perform:
About 30 SWIs and six * Commands exist purely for keyboard control. The chapter entitled Technical Details covers how they work together.
These three terms can become very confused, especially so when talking about the keyboard versus a program's view of the keyboard driver.
Reset is a unique key. Unlike all others it does not send a key code to the keyboard driver. It is connected to a separate line on the keyboard connector and physically resets the computer. This cannot be stopped by a program. When a reset occurs, some parts of the system are initialised.
Pressing the Reset switch alone causes a 'soft' reset. This resets your machine, restarting RISC OS. You will lose any unsaved work.
You can get other types of Reset options by holding down certain keys whilst you press the Reset switch:
You can combine the effects of these keys; for example pressing *(on numeric keypad)-Ctrl-Shift-Reset on a machine configured to auto-boot would cause a hard reset, after which the Command Line would be entered, and the boot file would not be run.
BBC/Master users note that Reset is what used to be called Break on those machines.
Break is a key. You can separately configure Break, Shift-Break, Ctrl-Break and Ctrl-Shift-Break to cause a reset, an escape condition or do nothing.
By default, pressing the Break key (to the right of the twelve function keys) on its own acts like pressing the Escape key; for instance it may interrupt a program. However, if you press it whilst holding down any of the keys that affect the Reset switch it acts like the Reset switch, except that it does not reset the computer's hardware. For example:
The computer has a Break key as well as a Reset switch so that applications such as emulators can respond differently to them. For example, 65Host uses Break to reset the emulated computer, while Reset still resets the RISC OS computer itself.
Escape is a way of the user sending a signal to a program or its runtime environment. From a program's point of view, we talk about an escape condition. This can be caused by an escape key or the program itself.
By default, the key that causes an escape condition is Escape. RISC OS can be configured so that the escape key is any key on the keyboard.
When an escape condition occurs, RISC OS will call the escape handler of the program or the language environment. See the description of handlers in the section on Handlers. The escape handler or running program should then clear the escape condition and act in an appropriate way. Note that it is perfectly valid for a program to ignore an escape condition as long as it is cleared.
The escape event can also be enabled. This is called in place of the escape handler. (See the chapter entitled Events.)
A character which comes into the serial port interrupts the computer. It is then placed into the serial input buffer, if it is enabled. RISC OS can be configured so that serial input is ignored.
The computer can be set up so that input coming in from the serial port is treated exactly as if it had come from the keyboard. This means that the escape character and function key codes will be recognised.
If characters come in the serial port too quickly to be processed, then the serial input buffer would become full. After this point, data would be lost. To solve this problem, the serial driver will notify the sender to stop transmitting before it gets full. From a program's point of view, this all happens invisibly.
Calls that are specific to the serial port, whether they refer to input or output (eg those to set the baud rate, or to explicitly send/receive a character from/to the serial port), are gathered together in the chapter entitled Serial device.
There are a number of events associated with the character input system. In particular:
See the chapter entitled Events for more details of these events.
OS_ReadC is the core of the input stream system. It is called by many SWIs and it uses one of the three streams as an input source. The stream that it uses can be controlled by OS_Byte 2 for keyboard and serial port. To use the third stream, the file, then *Exec or OS_Byte 198 can be used. OS_Byte 177 can be used to read the setting of the last OS_Byte 2.
OS_ReadC is also responsible for handling cursor-editing during input.
OS_ReadLine, and its obsolete equivalent OS_Word 0, will read a line of input from the current input stream. It copes with the deleting of characters or the whole line. Thus, a single call which returns a simple string to the program allows the user much flexibility.
When a key is pressed (or released), a code unique to that key is transmitted to the computer through the keyboard connector cable. This code is read into some hardware, which causes an interrupt to occur. The keyboard driver responds to this interrupt by reading the keycode, and passing it on to the keyboard handler for further processing.
At this stage, a key press/release event may be generated, which you can handle as required. Also, at this level mouse button presses look exactly the same as any other key press. It is only when the mouse button presses reach the keyboard handler that they are recognised as such, and RISC OS is informed that the mouse button state has changed.
The keyboard buffer is often termed a type-ahead buffer, as it enables the user to type commands ahead of the program being ready for them. You must not assume it to be any particular length.
OS_Byte 201 will stop the keyboard handler from putting any characters it gets into the keyboard buffer. This means that most keyboard reading calls will not work. Where this function is useful is if you want a program to insert codes directly into the buffer without any of the user's key strokes appearing in the middle of them.
If the key pressed (or released) is one of the shifting keys (Shift, Ctrl or Alt) or one of the locking keys (Caps Lock, Num Lock or Scroll Lock) is pressed, then the key handler just makes a note of this fact by updating its status information. Normally this doesn't cause any character to be inserted into the keyboard buffer; although the Alt key can in combination with the numeric keypad - see Table D: Character sets.
OS_Byte 202 allows reading and writing of the keyboard status byte. This is a bitfield that represents the state of Shift, Ctrl, Alt and all the Lock keys. If it is written and any of the Lock keys with LEDs are changed, then this will not be reflected in the LEDs. OS_Byte 118 must be called to do this.
The next time any key goes down or up, then the Shift, Alt and Ctrl states will reflect their real position and the LEDs will be updated to their current status.
You can use *Configure Caps, NoCaps and ShCaps *Configure Caps onwards) to set the default Caps Lock key state.
Scanning refers to being able to get the low level key codes without the buffering and interpretation that is placed on keys by the higher level routines. The internal key number returned is not the code that the keyboard itself sends the computer. This is translated to a standard internal key number that maintains compatibility with BBC/Master series keyboard codes.
There are three OS_Bytes that can scan the keyboard. OS_Byte 121 can scan a particular key or a range or keys. Like this call, OS_Byte 122 can scan a fixed range of keys, all but the Shift, Alt, Ctrl and mouse keys. OS_Byte 129 can scan a particular key, like OS_Byte 121. It can also read a key with a time limit. This is discussed later.
The character stored in the keyboard buffer is derived from a table in the key handler, which maps the low level key codes into buffer codes, using the state of the various shifting and locking keys to alter the character if appropriate. In addition, the key-press is recorded in a 'last key pressed' location. This is to enable auto-repeating keys to be implemented, as described below.
For the standard keys, eg the letters, digits, punctuation marks etc, the buffer code is the ASCII code of the symbol. Thus when the code comes to be removed from the keyboard buffer (by OS_ReadC, for example), it is returned directly to the user. The other keys, such as the function keys and cursor keys, are entered as top-bit set characters, in the range &80 - &FF.
The SWI OS_InstallKeyHandler allows replacing the module that decodes key numbers into ASCII. It is outside the scope of this manual to discuss this procedure in depth.
OS_Byte 129 supports two operations, one of which, low level keyboard scanning, was discussed in the earlier section on scanning keys.
The other allows reading a character from the keyboard buffer within a time limit. This is useful in cases where a program waits for a response for a time, and if none is entered, continues. It can be used in a situation where the keyboard buffer needs to be checked periodically, but the program doesn't wish to be trapped waiting in OS_ReadC for a character to be entered. To achieve this, this call would be used with no waiting time, so if no characters are available in the buffer, then the program can continue.
OS_Byte 219 reads or modifies the code inserted into the keyboard buffer when the Tab key is pressed (the default is 9). If the value specified is in the range &80 to &FF, then the value to be inserted is modified by the state of the Shift and Ctrl keys, in a similar fashion to the function keys.
The auto-repeat of keys has two aspects: the delay before the key starts repeating, and the rate of repeating. The delay can be read and changed with OS_Byte 196, or changed with OS_Byte 11. The rate can be read and changed with OS_Byte 197, or changed with OS_Byte 12. Both are adjustable from 1 to 255 centiseconds. Auto-repeat can also be disabled.
The delay and rate can be set up using *Configure Delay and Repeat *Configure Delay onwards), which use the same parameter as the appropriate OS_Bytes.
In a default system, these keys are used for on-screen editing. The arrows move a cursor and Copy copies the character that it is on to the second cursor.
OS_Byte 237 reads how the cursor keys are interpreted. As well as the default editing state, they can be in two other modes. In one, the keys return characters in the range 135 to 139. In the other, they act as function keys, and can be treated as all the other function keys.
Although you can also use OS_Byte 237 to change this state, OS_Byte 4 is the preferred way of doing so.
There is a base value for the numeric keypad. A key on the numeric keypad adds an offset to this to get the character that is placed in the keyboard buffer. The offset of each key is such that the default base value of 48 will give each key the ASCII value of the character on the key.
This base value can be changed with OS_Byte 238. See the documentation on this call for details of the offsets of each key.
Shift and Ctrl can alter the value returned from the keypad. By default, this feature is disabled, but you can enable it with OS_Byte 254.
When referring to function keys, we are talking about two separate things. There are the keys, many discussed earlier, that generate buffer codes in the range &80 to &FF. Then there is the interpretation placed upon these buffer codes by RISC OS as it reads them from the buffer.
Interpreting these keys as function keys is only one way of using them. OS_Bytes 221 - 228 allow control over how buffer codes from &80 to &FF are interpreted by RISC OS. Each OS_Byte handles a group of 16 characters. Each group can be configured so that its characters are:
If a character is read from the keyboard buffer and is in a group that is configured as function keys, then a special action is taken by the keyboard handler. First of all, it looks up the value of the Key$n system variable which corresponds to the function key. The function key number is the lower nibble of the character. Thus, if the character is &81, the variable read is Key$1.
The variable refers to a string, which is copied into the function key buffer. If the string was a null string (the function key wasn't set), then RISC OS continues, removing the next character from the input buffer.
Otherwise, the first character is removed from the function key buffer and returned to the calling program. Characters read from this buffer are returned without interpretation in any way.
Subsequent calls to OS_ReadC and OS_Byte 129 spot that a function key is being read, and remove characters from the function key buffer instead of looking in the input buffer. This continues until the last character has been read from the buffer. Input then reverts to the normal input buffer.
OS_Byte 216 is used to see how much of a function key string remains to be read from the function key buffer. It can also change this value, to terminate for instance, but must be used with care.
To set a function key, a number of commands can be called:
To reset one or more function keys, there is also a variety of commands that can be used:
When you press the Reset button, then the RISC OS ROM is paged into the bottom of memory and performs certain housekeeping actions. It then pages itself out and restarts the system.
A soft reset distinguishes itself from a hard reset in a matter of degree. A hard reset will initialise far more things in the system. A soft reset, for instance, will not change the settings for PrinterType and the printer ignore character, nor will it reinitialise relocatable modules. It will, however, reset vectors that have been claimed.
OS_Byte 200 sets whether a reset will act as described above or will cause a complete memory clear. This makes it a power-on reset. If this is used, then all things kept in memory will be lost and settings restored to the defaults stored in CMOS RAM. This command should be used with discretion because of its powerful effects.
OS_Byte 253 can be used to see what kind of reset the last one was.
Break is configurable with OS_Byte 247. This sets how Break, Shift Break, Ctrl Break and Ctrl Shift Break act. They can each be set to cause a reset or an escape or have no effect. A reset caused by the break key does not page the ROM into the bottom of memory (as one caused by the Reset button does); instead, it just jumps to the correct location in the ROM.
The diagram below illustrates how all the calls in the escape system work together. A description of this interaction follows the diagram.
Interaction of calls in the escape system
An escape condition can be caused by a key or under program control. By default, the escape key is Escape. OS_Byte 220 can read or alter which key will cause an escape condition. OS_Byte 247 can alter the Break key (or Shift and Ctrl modifiers of it) so that it causes an escape condition. Thus, it is possible to have two escape keys on the keyboard, and this is indeed the default state.
Under program control, OS_Byte 125 can force an escape condition to occur. Note that it will not generate an event, but the escape handler is called.
OS_ReadEscapeState can check whether an escape condition has occurred. It can be called at any time, even from within interrupts.
OS_Byte 229 controls recognition of this escape character. It can disable the effect of the escape character and allow it to pass through the input stream unaltered. OS_Byte 200 can disable all escape conditions apart from those caused by OS_Byte 125. In this case, any escape characters would be discarded.
OS_Byte 14,6 controls whether the escape event is enabled or not. If the escape event is enabled, then it will be called and not the escape handler.
OS_Byte 126 will acknowledge an escape condition and call the escape handler to clear up. OS_Byte 124 will clear an escape condition without calling the escape handler.
OS_Byte 230 controls whether the normal effects of an escape occur or not when it is acknowledged. These include flushing buffers, closing the Exec file, terminating any sounds and so on.
The serial device is provided as a DeviceFS (Device Filing System) device. For full details, see the chapter entitled DeviceFS, and the Serial device. The latter chapter also contains all calls that are specific to the serial port, whether they refer to input or output (eg those to set the baud rate, or to explicitly send/receive a character from/to the serial port).
There are two ways of causing a file to be made the input stream. The simplest is to use *Exec, which will open the specified file and attach it as the input stream. For more control, OS_Byte 198 does what *Exec does, and can also terminate the Exec stream at any time or change to another file.
The diagrams below show the BBC/Master compatible internal key numbers generated by different keyboards.
Some keys generate two numbers; this is for compatibility with Master computers. Codes 0 - 2 are generated by both of the Shift, Ctrl and Alt keys respectively; this is useful for testing if either or both of the left and right hand keys have been pressed.
Furthermore, the mouse buttons generate internal key numbers:
Internal key numbers for mouse
The standard Archimedes keyboard generates these internal key numbers:
Internal key numbers for standard Archimedes keyboard
The keyboard used in portable machines generates these internal key numbers:
Internal key codes for keyboard used in portable machines
When the key to the left of the space bar is pressed (labelled 'FN' for UK machines), some keys generate different internal key codes, as shown below:
Alternative internal key codes for keyboard used in portable machines
You should not rely on the behaviour of other keys when pressed in conjunction with the FN key, as this may change in the future.
R1 = &44 (reason code)
R2 = keyboard ID
R1 preserved to pass on (don't claim)
R2 preserved
This call is made on reset, when the OS has established which type of keyboard is present, and after an OS_InstallKeyHandler SWI (see OS_InstallKeyHandler). It is for the information of keyboard handler modules which need to know what sort of keyboard is present; it should not be claimed.
Standard Archimedes keyboards all have a keyboard ID of 1. The A4 internal keyboard, or a PC external keyboard, give a keyboard ID of 2, except under RISC OS 2, which does not support them.
Read a character from the input stream
--
if C flag = 0 then R0 = ASCII code
if C flag = 1 then R0 = error type: &1B in R0 means an escape
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
This call will read a character from the input stream. OS_Byte 2 can be used to change the selection of the current input stream.
Cursor key presses go into the buffer. When OS_ReadC reads a cursor key code from the buffer it handles the cursor editing for you, assuming the cursor keys are set up to do cursor editing. That is, if one of the arrow keys is pressed, cursor edit mode is entered, indicated by the presence of two cursors on the screen. You can copy characters from underneath the input cursor by pressing Copy. The character read is returned from the routine as if you had typed it explicitly.
Cursor editing only applies if enabled (see OS_Byte 4 on OS_Byte 4), and is cancelled when ASCII 13 is sent to the VDU driver.
RdchV
R0 = 2
R1 = stream selection (0, 1 or 2)
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call selects the device from which all subsequent input is taken by OS_ReadC. This is determined by the value of R1 passed as follows:
The difference between the 0 and 2 values is that the latter allows characters to be received into the serial input buffer under interrupts at the same time as the keyboard is being used as the primary input. If the input stream is subsequently switched to the serial device, then those characters can then be read.
Note that the value returned in R1 from this call is:
The state of this variable can be read by OS_Byte 177.
ByteV
R0 = 4
R1 = new state
R0 preserved
R1 = state before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call alters the effect of the four arrow keys and the Copy key. The value of R1 determines their state:
OS_Byte 237 may be used to write and read this state.
ByteV
R0 = 11
R1 = delay period in centiseconds
R0 preserved
R1 = previous delay period
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
You must hold down each key on the keyboard for a number of centiseconds before it begins to autorepeat. This call enables you to change the initial delay from the default set by *Configure Delay.
If the delay period is zero, then auto-repeat is disabled.
This variable may also be read and set using OS_Byte 196.
ByteV
R0 = 12
R1 = repeat rate in centiseconds (unless R1 = 0)
R0 preserved
R1 = previous repeat rate
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
After the auto-repeat delay specified by OS_Byte 11, each key will repeat until released at the rate passed to this call. This call enables you to change the initial rate from the default set by *Configure Repeat. One particular use of this is to speed up cursor editing.
If the rate is zero, then the auto-repeat and delay values are reset to their configured settings.
This variable may also be read and set using OS_Byte 197.
ByteV
R0 = 18
R0 preserved
R1, R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call removes the system variables Key$0 to Key$15, which contain the function key definitions. It also cancels any key string currently being read.
You can also clear individual strings by *Key n, or all of them by *Unset Key$*. Neither of these commands cancel the current key expansion, though.
None
ByteV
R0 = 118
R0 preserved
R1, R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The settings of Caps Lock, Scroll Lock and Num Lock are held in a location referred to as the keyboard status byte. See OS_Byte 202 on OS_Byte 202 for detail of this.
Under normal circumstances they are shown by the keyboard LEDs which are set into the keycaps. However, if the keyboard status byte is written to using OS_Byte 202, then the LEDs will not update. This call ensures that the current contents of the keyboard status byte are reflected in the LEDs.
ByteV
R0 = 121
R1 = key(s) to be detected
R0 preserved
R1 = if/which key has been detected
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call allows checking the keyboard to see whether a particular key or a range of keys is being pressed. It uses the internal key number (see the chapter entitled Internal key numbers for a complete list).
To check for a single key, R1 must contain the internal key number exclusive ORd with &80 (R1 EOR &80). The value returned in R1 will be &FF if that key is currently down and zero if it is not.
To check for a range of key values, it is possible to set the 'low tide' mark. That is, no internal key number below the value in R1 on entry will be recognised. Since Shift, Ctrl, Alt and the mouse keys are at the bottom then this is very convenient.
The value returned in R1 will be the internal key number if a key is currently down or &FF if no key is down.
ByteV
Keyboard scan (other than Shift, Ctrl, Alt and mouse keys)
R0 = 122
R0 preserved
R1 = internal key number of key, or &FF if none
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call allows checking the keyboard to see whether any key is being pressed. It uses the internal key number (see the chapter entitled Internal key numbers for a complete list). All key numbers below 16 are ignored. This excludes all Shift, Ctrl, Alt and mouse keys. It is equivalent to calling OS_Byte 121 with R1 = 16.
R0 = 124
R0 preserved
R1, R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call clears any escape condition by calling the escape handler with R11 = 0, and then returns.
ByteV
R0 = 125
R0 preserved
R1, R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call is used to set the escape flag and call the escape handler. An escape event is not generated.
ByteV
R0 = 126
R0 preserved
R1 = 255 if escape condition has been cleared, or 0 if none to clear
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call attempts to clear an escape condition if one exists. It may or may not need to perform various actions to tidy up after the escape condition depending on whether the escape condition side effects (see OS_Byte 230) have been enabled or not.
The escape handler is called to indicate clearing of the escape condition.
The value returned in R1 indicates whether or not the escape condition has been cleared. &FF indicates success, while zero means that there was no escape condition to clear.
ByteV
R0 = 129
To read a key within a time limit:
To read the OS version identifier:
To scan the keyboard for a range of keys:
To scan the keyboard for a particular key:
R0 preserved
If reading a key within a time limit:
If reading the OS version identifier:
If scanning the keyboard for a range of keys:
If scanning the keyboard for a particular key:
Interrupt status:
Fast interrupts are enabled for all operations
Processor is in SVC mode
Not defined
This OS_Byte is four separate operations in one:
In this operation, RISC OS waits up to a specified time for a key to be pressed, if there are none in the keyboard buffer.
The time limit is set according to the following calculation:
The upper limit is 32767 centiseconds. To indicate the time of (n) centiseconds, then:
If an escape condition is detected during this operation it should be acknowledged by the application using OS_Byte 126, or cleared using OS_Byte 124.
While RISC OS is waiting for a keyboard character during one of these calls, it also deals with cursor key presses. That is, if one of the arrow keys is pressed, cursor edit mode is entered, indicated by the presence of two cursors on the screen. You can copy characters from underneath the input cursor by pressing Copy. The character read is returned from the routine as if you had typed it explicitly. Cursor editing is cancelled when Return (ASCII 13) is sent to the VDU driver. Cursor editing can be disabled with OS_Byte 4.
If R2=&FF and R1=0, then the OS version identifier is read.
If R2=&FF and R1 is in the range &1 to &7F, then the keyboard is scanned for any keys that are being pressed, which have an internal key number greater than or equal to R1 EOR &7F. If found, the internal key number is returned. If no key is found, then &FF is returned.
If R2=&FF and R1 is in the range &80 to &7F, then the keyboard is scanned for a particular key with internal key number equal to R1 EOR &FF.
In BBC/Master series computers, the internal key numbers are the same as the keyboard scan numbers; but the two differ for other Acorn computers.
A list of all internal key numbers can be found in the Internal key numbers.
R0 = 177
R1 = 0
R2 = 255
R0 preserved
R1 = value of stream selection
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This returns the number of the buffer from which character input gets characters:
You must not alter this number with this call by using other values in R1 and R2.
ByteV
R0 = 196
R1 = 0 to read, or new delay to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 = keyboard auto-repeat rate (see OS_Byte 197)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The delay stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((delay AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call can read and set the keyboard auto-repeat delay value. OS_Byte 11 can also write this variable, and has more information about it.
ByteV
R0 = 197
R1 = 0 to read, or new rate to write
R2 = 255 to read, or 1 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The rate stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((rate AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call can read and set the keyboard auto-repeat rate value. OS_Byte 12 can also write this variable, and has more information about it. Note the difference between *FX 12,0 (which sets the auto-repeat rate and delay to their configured values) and *FX 197,0 (which sets the auto-repeat rate to zero).
ByteV
R0 = 198
R1 = 0 to read, or new handle to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The handle stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((handle AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This command can be used to read or write the location that holds the Exec file handle.
If reading, it can tell whether an Exec file is the current input stream or not. Any non-zero number is a handle and hence the input stream.
If writing a handle over a zero, then it causes the same effect as a *Exec command.
If writing over a Exec file handle, the current Exec file will be switched off. This handle, which is returned, should then be properly closed after use. If you write a new handle value in its place, then this has the effect of switching input in mid-stream. If you write a zero in this case, then it will have terminate the current input stream.
In both these cases care must be taken not to cause the Exec file to stop at an inconvenient point.
If you are writing a file handle, the new file must be open for input or update, otherwise a Channel error occurs. If an attempt is made to use a write-only file for the *Exec file, a 'Not open for reading' error is given.
None
ByteV
R0 = 200
R1 = 0 to read, or new state to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = state before being overwritten
R2 = keyboard disable flag (see OS_Byte 201)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The state stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((state AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call can read or change the effects of a reset (including resets caused by Break) and of Escape.
The bottom two bits of R1 have the following significance:
None
ByteV
R0 = 201
R1 = 0 to read, or new flag to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = flag before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The flag stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((flag AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call allows you to read and change the keyboard state (ie whether the keyboard is enabled or disabled). When it is enabled, all keys are read as normal. When it is disabled, the keyboard interrupt service routine does not place these keys into the keyboard buffer.
A value of zero will enable keyboard input, while any non-zero value will disable it.
None
ByteV
R0 = 202
R1 = 0 to read, or new status to write (with bit 0 clear)
R2 = 255 to read, or 1 to write
R0 preserved
R1 = status before being overwritten
R2 = serial input buffer space (see OS_Byte 203)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The status stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((status AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
The keyboard status byte holds information on the current status of the keyboard, such as the setting of Caps Lock. This call enables you to read and change these settings.
The bit pattern in R1 determines the settings. In this table, the State column has on and off in it. On means a LED is lit or a key is pressed, and off means the opposite. Take careful note of the state, because they are not all in the same order:
| Bit | Value | State | Meaning |
|---|---|---|---|
| 0 | -- | -- | Reserved for use by keyboard handler: must be preserved when writing |
| 1 | 0 | off | Scroll Lock |
| 1 | on | ||
| 2 | 0 | on | Num Lock |
| 1 | off | ||
| 3 | 0 | off | Shift |
| 1 | on | ||
| 4 | 0 | on | Caps Lock |
| 1 | off | ||
| 5 | Normally set | ||
| 6 | 0 | off | Ctrl |
| 1 | on | ||
| 7 | 0 | off | Shift Enable |
| 1 | on |
If Caps Lock is on, then Shift will have no effect on letters. If Shift Enable and Caps Lock are on, then Shift will get lower case. You can enter this state from the keyboard by holding Shift down and pressing Caps Lock.
This call does not update the LEDs. The next key down or up event will update them, or you can call OS_Byte 118.
ByteV
R0 = 216
R1 = 0 to read, or new length to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = length before being overwritten
R2 = paged mode line count (see OS_Byte 217)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The length stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((length AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call reads and changes the count of characters left in the currently active function key definition. An active function key is one that is being read by OS_ReadC instead of the current input stream.
If the length is zero, then no function key string is being read. A zero length must never be changed with this call.
A non-zero value shows that a function key string is active. Setting it to zero effectively cancels that function key from that point. Changing it to any non-zero value will have an indeterminate effect.
ByteV
R0 = 219
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
OS_Byte 219 reads or modifies the code inserted into the keyboard buffer when the Tab key is pressed (the default is 9). If the value specified is in the range &80 to &FF, then the value to be inserted is modified by the state of the Shift and Ctrl keys as follows:
The value inserted will be interpreted by OS_ReadC in the normal way. For example, if the value specified is &82, then the Tab key behaves in an identical way to the function key F2.
ByteV
R0 = 220
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call can read and change the character that will cause an escape condition when it is read from the input stream. Escape (ASCII 27) is the default.
For example:
| Value | Key that causes an escape condition |
|---|---|
| 27 | Escape |
| 53 | '5' |
| &81 | F1 |
| &A1 | Ctrl F1 |
ByteV
R0 = 221 - 228
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call provides a way of reading and changing how the codes from &80 to &FF are interpreted when read from the input buffer.
They are split into eight groups as follows:
| OS_Byte | Range of buffer codes controlled |
|---|---|
| 221 | &C0 - &CF |
| 222 | &D0 - &DF |
| 223 | &E0 - &EF |
| 224 | &F0 - &FF |
| 225 | &80 - &8F |
| 226 | &90 - &9F |
| 227 | &A0 - &AF |
| 228 | &B0 - &BF |
The list below shows the keys that can produce codes in these groups:
| Key | Code | +Shift | +Ctrl | +Ctrl-Shift |
|---|---|---|---|---|
| &80 | &90 | &A0 | &B0 | |
| F1 | &81 | &91 | &A1 | &B1 |
| F2 | &82 | &92 | &A2 | &B2 |
| : | : | : | : | : |
| F9 | &89 | &99 | &A9 | &B9 |
| Copy | &8B | &9B | &AB | &BB |
| &8C | &9C | &AC | &BC |
| &8D | &9D | &AD | &BD |
![[DOWN]](../symbols/entities/8595.png)
| &8E | &9E | &AE | &BE |
![[UP]](../symbols/entities/8593.png)
| &8F | &9F | &AF | &BF |
| Page Down | &9E | &8E | &BE | &AE |
| Page Up | &9F | &8F | &BF | &AF |
| F10 | &CA | &DA | &EA | &FA |
| F11 | &CB | &DB | &EB | &FB |
| F12 | &CC | &DC | &EC | &FC |
| Insert | &CD | &DD | &ED | &FD |
These SWIs only affect the codes generated by the Copy and arrow keys if they have been set up to act as function keys by calling OS_Byte 4 with R1 = 2. Normally this is not the case, and you should use OS_Byte 4 to control the action of these keys.
Also, when a reset occurs, the code &CA is inserted into the input buffer. This causes the key definition for function key 10 to be used for subsequent input if it is defined.
Some of these codes cannot be generated from the main keyboard, but must be produced via one of the following techniques:
The interpretation of these codes depends upon the value of R1 passed. This is the interpretation value. It determines what action will be taken with a code in the appropriate block:
| Value | Interpretation |
|---|---|
| 0 | discard the code |
| 1 | generates the string assigned to function key (code MOD 16) |
| 2 | generates a NULL (ASCII 0) followed by the code |
| 3 - &FF | acts as offset: ie (code MOD 16) + value |
If any block has been set to interpretation value 2, then a Ctrl-@ (ASCII 0) will be passed as two zeros to differentiate it from a high code. This mode is used with software that can cope with the international character set in the range &A0 - &FF. It is recommended that the function keys return a NULL followed by the key code, so that they can be distinguished from actual ASCII characters in this range.
This is the default setting for each of the blocks:
| Block | Default | Interpretation |
|---|---|---|
| &80 - &8F | 1 | function keys |
| &90 - &9F | &80 | return (buffer code - &10) |
| &A0 - &AF | &90 | return (buffer code - &10) |
| &B0 - &BF | 0 | discard |
| &C0 - &CF | 1 | function keys |
| &D0 - &DF | &D0 | return buffer code unchanged |
| &E0 - &EF | &E0 | return buffer code unchanged |
| &F0 - &FF | &F0 | return buffer code unchanged |
R0 = 229
R1 = 0 to read, or new status to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = status before being overwritten
R2 = escape effects (see OS_Byte 230)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The status stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((status AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call allows you to enable or disable the generation of escape conditions, and to read the current setting. Escape conditions may be caused by pressing the current escape character or by inserting it into the input buffer with OS_Byte 153.
If the value of R1 passed is zero, which is the default, then escape conditions are enabled. Any non-zero value will disable them. When they are disabled, the current escape character set by OS_Byte 220 will pass through the input stream unaltered.
OS_Byte 200 can also control the enabling of escape conditions.
ByteV
R0 = 230
R1 = 0 to read, or new status to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = status before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The status stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((status AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
By default, the acknowledgement of an escape condition produces the following effects:
This call enables you to determine whether the escape effects are currently enabled or disabled, and to change the setting if required.
If the value of R1 passed is zero, which is the default, then escape effects are enabled. Any non-zero value will disable them.
None
ByteV
R0 = 237
R1 = 0 to read, or new state to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 = numeric keypad interpretation (see OS_Byte 238)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The state stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((state AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This can read and modify the cursor key status. OS_Byte 4 can perform an identical write operation. See the description of that SWI in this chapter for details of the status.
ByteV
R0 = 238
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call controls the character which is inserted into the input buffer when you press one of the keypad keys. The inserted character is derived from the sum of a base value (set by this call) and an offset, which depends on the key pressed. The inner (lighter) keys have two different offsets. The offset used depends on the state of Num Lock.
By default, the base number is 48: ie they generate codes which are displacements from 48 (ASCII '0').
This table shows the effect of the default settings on the keypad:
| Key | Base Offset | Character Generated | Num Lock Offset | Character Generated |
|---|---|---|---|---|
| 0 | 0 | 0 | + 57 | Insert |
| 1 | + | 1 | + 1 | Copy |
| 2 | + | 2 | + 4 | Down |
| 3 | + | 3 | + 10 | Page Down |
| 4 | + | 4 | + 2 | Left |
| 5 | + | 5 | ignored | |
| 6 | + | 6 | + 3 | Right |
| 7 | + | 7 | -18 | Home |
| 8 | + | 8 | + 5 | Up |
| 9 | + | 9 | + 11 | Page Up |
| . | -2 | . | + 9 | Delete |
| / | -1 | / | unchanged | |
| * | -6 | * | unchanged | |
| # | -13 | # | unchanged | |
| - | -3 | - | unchanged | |
| + | -5 | + | unchanged | |
| Enter | -35 | Return | unchanged |
Unlike the function keys, you can set the numeric keypad base number to any value in the range 0 - 255. (If a generated code lies outside this range it is reduced MOD 256). If a character generated by the numeric keypad is in the range &80 to &8F, then it will act like a soft function key.
OS_Byte 254 controls how Shift and Ctrl act upon numeric keypad characters.
ByteV
R0 = 247
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call reads and changes the result of pressing Break. The value byte alters Break and modifiers of it as follows:
| Bits | Key Combination |
|---|---|
| 0,1 | Break |
| 2,3 | Shift Break |
| 4,5 | Ctrl Break |
| 6,7 | Ctrl Shift Break |
Each two bit number may take on one of these values:
| Value | Effect |
|---|---|
| 00 | Act as Reset |
| 01 | Act as escape key |
| 10 | No effect |
| 11 | Undefined |
The default is 2_00000001, so Break causes an escape condition, and Shift-Break, Ctrl-Break and Ctrl-Shift-Break all act as resets.
None
ByteV
R0 = 253
R1 = 0
R2 = 255
R0 preserved
R1 = break type
R2 = effect of Shift on keypad (see OS_Byte 254)
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call returns the type of the last reset performed in R1:
| Value | Reset type |
|---|---|
| 0 | Soft reset |
| 1 | Power-on reset |
| 2 | Hard reset |
None
ByteV
R0 = 254
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write
R0 preserved
R1 = value before being overwritten
R2 corrupted
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
The value stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((value AND R2) EOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.
This call allows you to enable or disable the effect of Shift and Ctrl on the numeric keypad or to read the current state. These keys may modify the code just before it is inserted into the input buffer.
If the value of R1 passed is zero, then Shift and Ctrl are enabled. Any non-zero value will disable them; this is the default.
If they are enabled then the following actions occur depending on the value generated by a key:
&80:None
ByteV
R0 = 0
R1 = pointer to parameter block
R0 preserved
R1 = preserved (and parameter block unaltered)
R2 = length of input line, not including the Return
the C flag is set if input is terminated by an escape condition
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
Not defined
This call is equivalent to OS_ReadLine, but has restrictions on the location of the character buffer used. It is provided for compatibility with older Acorn operating systems.
The parameter block pointed to has the following structure:
| Offset | Purpose | Equivalent in OS_ReadLine |
|---|---|---|
| 0 | LSB of buffer address | R0 |
| 1 | MSB of buffer address | |
| 2 | size of buffer | R1 |
| 3 | lowest ASCII code | R2 |
| 4 | highest ASCII code | R3 |
Because the parameter block only uses 2 bytes to specify the character buffer's address, it must lie in the bottom 64K of memory. Furthermore, the range &0000 to &7FFF is reserved for RISC OS, so in fact the buffer must lie in the range &8000 to &FFFF.
WordV
R0 = pointer to buffer to hold the line (bits 0-29), and flags (bits 30-31)
echo only those characters that enter the buffer echo characters by echoing the character in R4R0 corrupted
R1 = length of buffer read, not including Return.
R2, R3 corrupted
the C flag is set if input is terminated by an escape condition
Interrupts are enabled
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_ReadLine reads a line of text from the current input stream using OS_ReadC. Characters in the range specified by R2 and R3 are placed in a read buffer, the address of which is given in R0. These characters are also echoed to OS_WriteC; if bit 31 of R0 is clear on entry, characters outside the range are also echoed. Alternatively - by setting bit 30 of R0 - you can echo the character held in R4, rather than the actual character that was read. This is useful, for example, to read a password without echoing its actual characters to the screen.
Certain characters and conditions are specially treated:
If the number of characters input reaches the number passed in R1, further characters are ignored and cause Ctrl-G (ASCII 7) to be sent to OS_WriteC, which will normally cause a sound to be emitted. The deleting keys mentioned above will still function.
You must not call OS_ReadLine from an interrupt or event routine.
ReadLineV, WrchV
--
the C flag is set if an escape condition has occurred
Interrupt status is not altered
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
OS_ReadEscapeState sets or clears the carry flag depending on whether escape is set or not. Once an escape condition has been detected (either through this call or, for example, with OS_ReadC), it should be acknowledged using OS_Byte 126 or cleared using OS_Byte 124.
This call is useful if a program is executing in a loop which the user may want to escape from, but isn't performing any input operations which would let it know about the escape.
Note that OS_ReadEscapeState may be called from an interrupt routine. However, OS_Byte 126 may not be, so if an escape is detected under interrupts, the interrupt routine must set a flag which is checked by the foreground task, rather than attempt to acknowledge the escape itself.
None
Install a key handler or read the address of the current one
| R0 = | 0 to read address of current keyboard handler |
| 1 to read keyboard ID from keyboard | |
| >1 to set address of new keyboard handler |
R0 = address of current/old keyboard handler, or keyboard ID
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
OS_InstallKeyHandler installs a new keyboard handler to replace the default code. Alternatively you can read the address of the current handler, or read the keyboard ID. The returned keyboard ID may be:
| Value | Meaning |
|---|---|
| 1 | standard Archimedes keyboard |
| 2 | A4 internal keyboard, or PC external keyboard |
None
None
*Configure Caps
None
*Configure Caps sets the configured value for Caps Lock to ON, so that when you switch on or reset your machine, you will start typing in capital letters. This was the default value on RISC OS 2; NoCaps is the default value from RISC OS 3 onwards.
*Configure Caps
*Configure NoCaps, *Configure ShCaps
None
*Configure Delay n
n - delay (in centiseconds)
*Configure Delay sets the configured delay before keys start to auto-repeat. A value of zero disables auto-repeat. The default value is 32.
*Configure Repeat
None
None
*Configure NoCaps sets the configured value for Caps Lock to OFF, so that when you switch on or reset your machine, you will start typing in lower case. This is the default value from RISC OS 3 onwards; Caps was the default value on RISC OS 2.
*Configure NoCaps
*Configure Caps, *Configure ShCaps
None
Sets the configured interval between the generation of auto-repeat keys
*Configure Repeat n
n - interval (in centiseconds)
*Configure Repeat sets the configured interval between the generation of auto-repeat keys. A value of zero sets an infinite interval, so the character repeats just once, after the auto-repeat delay. To completely disable auto-repeat, set the delay to zero; *Configure Delay 0 will do this.
The default value is 8.
*Configure Repeat 3
*Configure Delay
None
Sets the configured value for Caps Lock to ON, Shift producing lower case letters
*Configure ShCaps
None
*Configure ShCaps sets the configured value for Caps Lock to ON, so that when you switch on or reset your machine, you will start typing in capital letters. Holding down the Shift key will produce lower case letters, which does not happen when Caps is the configured value. Caps is the default value from RISC OS 3 onwards; Caps was the default value on RISC OS 2.
*Configure ShCaps
*Configure NoCaps, *Configure Caps
None
*Key keynumber [string]
keynumber - a number from 0 to 15 string - any GSTrans-compatible string
*Key assigns a string to a function key. It provides a very simple way of setting up function keys so that repetitive or error-prone strings (such as complex commands) can be initiated with a single keystroke. You can use any string up to 255 characters long.
The string is transformed by GSTrans before being stored. This means that you can, for example, represent Return using '|M' (as in the example below). See the chapter entitled GS string operations for details.
The string is stored in the system variable Key$keynumber, for example Key$1 for function key 1. This enables a key's definition to be read before it is used, and manipulated like any other variable. Also, because a key string can be set as a macro, its value may be made to change each time it is used.
In addition to F1 to F12, these keys can act as function keys by default:
and these keys can be made to act as function keys by the command *FX4,2:
Function keys are generally unaffected by a soft break, but lost following a hard break.
*Key 8 *Audio On|M *Speaker On|m *Volume 127|m
*SetMacro Key$1 ||The time is <Sys$Time>|m
*Set, *SetMacro