RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Character Input


Introduction

The Character Input system can get characters from the computer's input devices. They can be any one of the following:

  • the keyboard
  • the serial port
  • a file on any filing system

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.

Overview

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.

Streams

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.

OS_ReadC

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.

Buffers

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.

Keyboard

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.

Keyboard handlers

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.

Basic operation

At a basic level, the keyboard works like this:

  1. One or more keys are pressed, which cause an interrupt.
  2. The keyboard driver gets a raw key number from the keyboard.
  3. The raw key number is passed to the keyboard handler, where it is converted into a form more like the program expects. This can be:
    • an ASCII character.
    • a non-ASCII character, such as a function key or arrow.
    • a special key, such as Escape or Break that must be acted on immediately.
  4. Apart from some special keys, this character is then stored in the keyboard buffer.

When a program wants a character from the input stream (in this example, the keyboard):

  • When called by a program, the stream system gets the first character from the keyboard buffer (or waits if there is none there).
  • Return the character to the program or perform the appropriate action if it is a function key, arrow, etc.
Advanced features

Also, there are a number of extra operations that the keyboard driver can perform:

  • The interpretation of function keys, arrow keys and the numeric keypad can all be changed to various modes.
  • The chapter entitled auto-repeat of keys can be adjusted, both the initial delay and the rate of repeat.
  • The keyboard can be scanned directly, rather than going through any buffering.
  • The keyboard handler can even be completely replaced with a custom handler.

About 30 SWIs and six * Commands exist purely for keyboard control. The chapter entitled Technical Details covers how they work together.

Reset, Break and Escape

These three terms can become very confused, especially so when talking about the keyboard versus a program's view of the keyboard driver.

Reset

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:

  • Holding down the Ctrl key causes a 'hard reset'. This is more severe than a soft reset (but still doesn't reset your machine as thoroughly as switching it off, then on again).
  • Holding down the Shift key reverses the action of the configured boot option. If there is a boot file set to run, it is not run. If there is a boot file not set to run, it is run.
  • Holding down *(on numeric keypad)-Resetcauses the Command Line to be entered, rather than the configured language (such as the Desktop or BASIC).

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

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:

  • Pressing Shift-Break causes a soft restart of RISC OS, reversing the normal auto-boot behaviour.
  • Pressing Ctrl-Break causes a hard restart of RISC OS, which is more severe in its effects.

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

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.)

Serial port

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.

*Exec

*Exec is the opposite of spooling, which is used in character output. *Exec makes a file the current input stream. Keyboard and serial input is ignored.

A SWI is provided to allow the Exec file to be changed or stopped under program control.

Technical Details

Events

There are a number of events associated with the character input system. In particular:

  • input buffer has become full
  • character placed in input buffer
  • a key has been pressed/released
  • serial error has occurred
  • escape condition detected

See the chapter entitled Events for more details of these events.

Streams

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

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.

Keyboard

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.

Keyboard buffer

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.

Disabling buffering

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.

Keyboard status

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 keys

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.

Key handler

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.

Custom key handler

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.

Read with time limit

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.

Tab key

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.

Auto-repeat

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.

Arrow and Copy keys

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.

Numeric keypad

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.

Interpreting characters &80 - &FF

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:

  • interpreted as function keys
  • preceded by a NULL (ASCII 0)
  • offset by any number from 3 - &FF
  • discarded
Function keys

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.

Setting and clearing

To set a function key, a number of commands can be called:

  • *Key n string
  • *Set Key$n string
  • *SetMacro Key$n expression. This is passed through OS_GSTrans when it is copied to the function key buffer. This is interesting because it means that the string generated by a function key can change every time it is used.

To reset one or more function keys, there is also a variety of commands that can be used:

  • *Key n - will reset function key n
  • *Unset Key$n - will also reset function key n
  • *Unset Key$* - will reset all function keys
  • OS_Byte 18 - will also reset all function keys

Reset, Break and Escape

Reset

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

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.

Escape

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

Causing escape

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.

Disabling escape

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.

After an escape

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.

Serial device

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).

*Exec

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.

Internal key numbers

The diagrams below show the BBC/Master compatible internal key numbers generated by different keyboards.

General points

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

Standard Archimedes keyboard

The standard Archimedes keyboard generates these internal key numbers:


Internal key numbers for standard Archimedes keyboard

Keyboard used in portable machines

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.

Service Calls


Service_KeyHandler
(Service Call &44)

Keyboard handler

On entry

R1 = &44 (reason code)
R2 = keyboard ID

On exit

R1 preserved to pass on (don't claim)
R2 preserved

Use

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.

SWI Calls


OS_ReadC
(SWI &04)

Read a character from the input stream

On entry

--

On exit

if C flag = 0 then R0 = ASCII code
if C flag = 1 then R0 = error type: &1B in R0 means an escape

Interrupts

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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.

Related SWIs

OS_Byte 2, OS_ReadLine

Related vectors

RdchV


OS_Byte 2
(SWI &06)

Specify input stream

On entry

R0 = 2
R1 = stream selection (0, 1 or 2)

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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:

  • 0 for keyboard input with serial input buffer disabled
  • 1 for serial input
  • 2 for keyboard input with serial input buffer enabled

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:

  • 0 when input was from the keyboard
  • 1 when input was from the serial port

The state of this variable can be read by OS_Byte 177.

Related SWIs

OS_Byte 177

Related vectors

ByteV


OS_Byte 4
(SWI &06)

Write cursor key status

On entry

R0 = 4
R1 = new state

On exit

R0 preserved
R1 = state before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call alters the effect of the four arrow keys and the Copy key. The value of R1 determines their state:

0 Enables cursor editing. This is the default state.
1 Disables cursor editing. When pressed, the keys return the following ASCII values:
Key Value
Copy 135
Left arrow 136
Right arrow 137
Down arrow 138
Up arrow 139
2 Cursor keys act as function keys. The function key numbers assigned are:
Key Function key number
Copy 11
Left arrow 12
Right arrow 13
Down arrow 14
Up arrow 15

OS_Byte 237 may be used to write and read this state.

Related SWIs

OS_Byte 237

Related vectors

ByteV


OS_Byte 11
(SWI &06)

Write keyboard auto-repeat delay

On entry

R0 = 11
R1 = delay period in centiseconds

On exit

R0 preserved
R1 = previous delay period
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 12, OS_Byte 196, OS_Byte 197

Related vectors

ByteV


OS_Byte 12
(SWI &06)

Write keyboard auto-repeat rate

On entry

R0 = 12
R1 = repeat rate in centiseconds (unless R1 = 0)

On exit

R0 preserved
R1 = previous repeat rate
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 11, OS_Byte 196, OS_Byte 197

Related vectors

ByteV


OS_Byte 18
(SWI &06)

Reset function key definitions

On entry

R0 = 18

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

None

Related vectors

ByteV


OS_Byte 118
(SWI &06)

Reflect keyboard status in LEDs

On entry

R0 = 118

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 202

Related vectors

ByteV


OS_Byte 121
(SWI &06)

Keyboard scan

On entry

R0 = 121
R1 = key(s) to be detected

On exit

R0 preserved
R1 = if/which key has been detected
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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).

Single key

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.

Key range

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.

Related SWIs

OS_Byte 122, OS_Byte 129

Related vectors

ByteV


OS_Byte 122
(SWI &06)

Keyboard scan (other than Shift, Ctrl, Alt and mouse keys)

On entry

R0 = 122

On exit

R0 preserved
R1 = internal key number of key, or &FF if none
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 121, OS_Byte 129

Related vectors

ByteV


OS_Byte 124
(SWI &06)

Clear escape condition

On entry

R0 = 124

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call clears any escape condition by calling the escape handler with R11 = 0, and then returns.

Related SWIs

OS_Byte 125, OS_Byte 126

Related vectors

ByteV


OS_Byte 125
(SWI &06)

Set escape condition

On entry

R0 = 125

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call is used to set the escape flag and call the escape handler. An escape event is not generated.

Related SWIs

OS_Byte 124, OS_Byte 126

Related vectors

ByteV


OS_Byte 126
(SWI &06)

Acknowledge escape condition

On entry

R0 = 126

On exit

R0 preserved
R1 = 255 if escape condition has been cleared, or 0 if none to clear
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 124, OS_Byte 125, OS_Byte 230

Related vectors

ByteV


OS_Byte 129
(SWI &06)

Read keyboard for information

On entry

R0 = 129

To read a key within a time limit:

R1 = time limit low byte
R2 = time limit high byte (in range &00 - &7F)

To read the OS version identifier:

R1 = 0
R2 = &FF

To scan the keyboard for a range of keys:

R1 = lowest internal key number EOR &7F (ie a value of &01 - &7F)
R2 = &FF

To scan the keyboard for a particular key:

R1 = internal key number EOR &FF (ie a value of &80 - &FF)
R2 = &FF

On exit

R0 preserved

If reading a key within a time limit:

R1 = ASCII code if character read, else undefined
R2 = &00 if character read, &1B if an escape condition exists, or &FF if timeout

If reading the OS version identifier:

R1 = &A0 for Arthur 1.20, &A1 for RISC OS 2.00, &A2 for RISC OS 2.01, &A3 for RISC OS 3 (version 3.00), or &A4 for RISC OS 3 (versions 3.10 and 3.11)
R2 = &00

If scanning the keyboard for a range of keys:

R1 = internal key number, or &FF if none pressed
R2 is corrupted

If scanning the keyboard for a particular key:

R1 = &FF if the required key was pressed, 0 otherwise
R2 = &FF if the required key was pressed, 0 otherwise

Interrupts

Interrupt status:

  • Enabled when reading a key within a time limit
  • Not altered for remaining three operations

Fast interrupts are enabled for all operations

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This OS_Byte is four separate operations in one:

  • read an ASCII key value read from the keyboard with a timeout
  • read the OS version identifier
  • scan the keyboard for a range of keys
  • scan the keyboard for a particular key.
Read key with time limit

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:

R1+(R2×256) centiseconds

The upper limit is 32767 centiseconds. To indicate the time of (n) centiseconds, then:

R1 = n MOD &100
R2 = n DIV &100

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.

Read the OS version identifier

If R2=&FF and R1=0, then the OS version identifier is read.

Scan for a range of characters

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.

Scan for a particular key

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.

Related SWIs

OS_Byte 121, OS_Byte 122

Related vectors

ByteV


OS_Byte 177
(SWI &06)

Read input stream selection

On entry

R0 = 177
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = value of stream selection
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This returns the number of the buffer from which character input gets characters:

  • 0 when input was from the keyboard
  • 1 when input was from the serial port

You must not alter this number with this call by using other values in R1 and R2.

Related SWIs

OS_Byte 2

Related vectors

ByteV


OS_Byte 196
(SWI &06)

Read/write keyboard auto-repeat delay

On entry

R0 = 196
R1 = 0 to read, or new delay to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 = keyboard auto-repeat rate (see OS_Byte 197)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 11, OS_Byte 12, OS_Byte 197

Related vectors

ByteV


OS_Byte 197
(SWI &06)

Read/write keyboard auto-repeat rate

On entry

R0 = 197
R1 = 0 to read, or new rate to write
R2 = 255 to read, or 1 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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).

Related SWIs

OS_Byte 11, OS_Byte 12, OS_Byte 196

Related vectors

ByteV


OS_Byte 198
(SWI &06)

Read/write *Exec file handle

On entry

R0 = 198
R1 = 0 to read, or new handle to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

None

Related vectors

ByteV


OS_Byte 200
(SWI &06)

Read/write Break and Escape effect

On entry

R0 = 200
R1 = 0 to read, or new state to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = state before being overwritten
R2 = keyboard disable flag (see OS_Byte 201)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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:

Bit Value Effect
0 0 Normal escape action
1 Escape disabled unless caused by OS_Byte 125
1 0 Normal reset action
1 Power on reset (only if bits 2 - 7 of R1 are zero)
    This means a value of 2_0000001x causes a memory clear.
Related SWIs

None

Related vectors

ByteV


OS_Byte 201
(SWI &06)

Read/write keyboard disable flag

On entry

R0 = 201
R1 = 0 to read, or new flag to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = flag before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

None

Related vectors

ByteV


OS_Byte 202
(SWI &06)

Read/write keyboard status byte

On entry

R0 = 202
R1 = 0 to read, or new status to write (with bit 0 clear)
R2 = 255 to read, or 1 to write

On exit

R0 preserved
R1 = status before being overwritten
R2 = serial input buffer space (see OS_Byte 203)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 118

Related vectors

ByteV


OS_Byte 216
(SWI &06)

Read/write length of function key string

On entry

R0 = 216
R1 = 0 to read, or new length to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = length before being overwritten
R2 = paged mode line count (see OS_Byte 217)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_ReadC

Related vectors

ByteV


OS_Byte 219
(SWI &06)

Read/write Tab key value

On entry

R0 = 219
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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:

  • Shift exclusive ORs the value with &10
  • Ctrl exclusive ORs the value with &20

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.

Related SWIs

OS_ReadC

Related vectors

ByteV


OS_Byte 220
(SWI &06)

Read/write escape character

On entry

R0 = 220
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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
Related SWIs

OS_ReadC

Related vectors

ByteV


OS_Bytes 221 - 228
(SWI &06)

Read/write interpretation of buffer codes

On entry

R0 = 221 - 228
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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
Print &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] &8E &9E &AE &BE
[UP] &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:

  • use these calls to generate them with keys
  • re-base the numeric keypad with OS_Byte 238
  • insert into the buffer with OS_Byte 138
  • insert into the buffer with OS_Byte 153
  • receive via the serial input port

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
Related SWIs

OS_Byte 4, OS_Byte 138, OS_Byte 153, OS_Byte 238

Related vectors

ByteV


OS_Byte 229
(SWI &06)

Read/write Escape key status

On entry

R0 = 229
R1 = 0 to read, or new status to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = status before being overwritten
R2 = escape effects (see OS_Byte 230)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 153, OS_Byte 200, OS_Byte 220

Related vectors

ByteV


OS_Byte 230
(SWI &06)

Read/write escape effects

On entry

R0 = 230
R1 = 0 to read, or new status to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = status before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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:

  • Flushes all active buffers
  • Closes any currently open *Exec file
  • Clears the VDU queue
  • Clears the VDU line count used in paged mode
  • Terminates the sound being produced.

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.

Related SWIs

None

Related vectors

ByteV


OS_Byte 237
(SWI &06)

Read/write cursor key status

On entry

R0 = 237
R1 = 0 to read, or new state to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 = numeric keypad interpretation (see OS_Byte 238)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 4

Related vectors

ByteV


OS_Byte 238
(SWI &06)

Read/write numeric keypad interpretation

On entry

R0 = 238
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_Byte 254

Related vectors

ByteV


OS_Byte 247
(SWI &06)

Read/write Break key actions

On entry

R0 = 247
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

None

Related vectors

ByteV


OS_Byte 253
(SWI &06)

Read last reset type

On entry

R0 = 253
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = break type
R2 = effect of Shift on keypad (see OS_Byte 254)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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
Related SWIs

None

Related vectors

ByteV


OS_Byte 254
(SWI &06)

Read/write effect of Shift and Ctrl on numeric keypad

On entry

R0 = 254
R1 = 0 to read, or new value to write
R2 = 255 to read, or 0 to write

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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:

  • if the value >= &80:
    Shift exclusive ORs the value with &10
    Ctrl exclusive ORs the value with &20
  • if the value < &80:
    Shift and Ctrl still have no effect
Related SWIs

None

Related vectors

ByteV


OS_Word 0
(SWI &07)

Read a line from input stream to memory

On entry

R0 = 0
R1 = pointer to parameter block

On exit

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

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

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.

Related SWIs

OS_ReadLine

Related vectors

WordV


OS_ReadLine
(SWI &0E)

Read a line from the input stream

On entry

R0 = pointer to buffer to hold the line (bits 0-29), and flags (bits 30-31)

bit 31 set => echo only those characters that enter the buffer
bit 30 set => echo characters by echoing the character in R4
R1 = size of buffer
R2 = lowest ASCII value to pass
R3 = highest ASCII value to pass
R4 = character to echo if bit 30 of R0 is set

On exit

R0 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

Interrupts are enabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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:

  • A carriage return (ASCII 13) or a linefeed terminates input. A carriage return is placed in the read buffer, but the length returned in R1 will not include it. A carriage return and a linefeed are echoed to OS_WriteC.
  • An escape condition also terminates input. This can represent the escape key being pressed, but it can also be caused by other means, such as an OS_Byte 125.
  • A delete (ASCII 127) or a backspace (ASCII 8) character act in the same way. If there are no characters in the read buffer they have no effect. Otherwise they each remove the character last written into the buffer, and echo a delete character to OS_WriteC.
  • Ctrl-U (ASCII 21) acts similarly to delete. Again, if there are no characters in the read buffer it has no effect. Otherwise it removes all the characters in the buffer, and echoes that many delete characters to OS_WriteC, effectively erasing the line.

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.

Related SWIs

OS_WriteC, OS_ReadC, OS_Word 0

Related vectors

ReadLineV, WrchV


OS_ReadEscapeState
(SWI &2C)

Check whether an escape condition has occurred

On entry

--

On exit

the C flag is set if an escape condition has occurred

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

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.

Related SWIs

OS_Byte 124, OS_Byte 126

Related vectors

None


OS_InstallKeyHandler
(SWI &3E)

Install a key handler or read the address of the current one

On entry
R0 = 0 to read address of current keyboard handler
1 to read keyboard ID from keyboard
>1 to set address of new keyboard handler
On exit

R0 = address of current/old keyboard handler, or keyboard ID

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

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
Related SWIs

None

Related vectors

None

*Commands


*Configure Caps

Sets the configured value for Caps Lock to ON

Syntax

*Configure Caps

Parameters

None

Use

*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.

Example

*Configure Caps

Related commands

*Configure NoCaps, *Configure ShCaps

Related SWIs

OS_Byte 202

Related vectors

None


*Configure Delay

Sets the configured delay before keys start to auto-repeat

Syntax

*Configure Delay n

Parameters

n - delay (in centiseconds)

Use

*Configure Delay sets the configured delay before keys start to auto-repeat. A value of zero disables auto-repeat. The default value is 32.

Example
*Configure Delay 20
Related commands

*Configure Repeat

Related SWIs

OS_Byte 11

Related vectors

None


*Configure NoCaps

Sets the configured value for Caps Lock to OFF

Syntax
*Configure NoCaps

Parameters

None

Use

*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.

Example

*Configure NoCaps

Related commands

*Configure Caps, *Configure ShCaps

Related SWIs

OS_Byte 202

Related vectors

None


*Configure Repeat

Sets the configured interval between the generation of auto-repeat keys

Syntax

*Configure Repeat n

Parameters

n - interval (in centiseconds)

Use

*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.

Example

*Configure Repeat 3

Related commands

*Configure Delay

Related SWIs

OS_Byte 12

Related vectors

None


*Configure ShCaps

Sets the configured value for Caps Lock to ON, Shift producing lower case letters

Syntax

*Configure ShCaps

Parameters

None

Use

*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.

Example

*Configure ShCaps

Related commands

*Configure NoCaps, *Configure Caps

Related SWIs

OS_Byte 202

Related vectors

None


*Key

Assigns a string to a function key

Syntax

*Key keynumber [string]

Parameters

keynumber - a number from 0 to 15 string - any GSTrans-compatible string

Use

*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:

  • Print as F0
  • Insert as F13

and these keys can be made to act as function keys by the command *FX4,2:

  • Copy as F11
  • left arrow as F12
  • right arrow as F13
  • down arrow as F14
  • up arrow as F15

Function keys are generally unaffected by a soft break, but lost following a hard break.

Example

*Key 8 *Audio On|M *Speaker On|m *Volume 127|m

*SetMacro Key$1 ||The time is <Sys$Time>|m

Related commands

*Set, *SetMacro

Related SWIs

OS_SetVarVal

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015