International IME Design Specification

Drawing number:	2205,201/DS
Issue:	2
AMR:	5108
Status:	Released
Author:	Kevin Bracey
Date:	22nd September 2005

Contents

1. Introduction
2. Programmer's Interface
3. Japanese IME Notes
4. Product Organisation
5. References
6. Glossary

1. Introduction

1.1 Overview

The interface describes only the IME back-end. For general use with all applications, a front-end will be required to make it easier for applications to use it, and to handle tasks that are IME-unaware.

1.2 Outstanding issues

2. Programmer's Interface

2.1 Introduction

IMEs will be controlled via the InternationalIME module, which functions as an SWI dispatcher. Applications use its IME_ SWIs, and it passes the calls on to the currently selected IME.

There is no registration of IMEs - the territory for a given country is expected to know about which IME to use, and the InternationalIME module uses this information to dispatch the SWIs.

Each IME should have its own SWI chunk, providing the same set of 32 SWIs. The last 32 SWIs in the chunk are free for IME-specific use.

2.2 Territory Manager SWIs

Territory_IME
(SWI &43062)

On entry

On exit

Use

2.3 InternationalIME SWIs

IME_SelectIME
(SWI &524E0)

On entry

On exit

Use

2.4 Wimp messages

Message_IMEChanged (&524C0)

Message_DeviceClaim (11)

On receiving this, the current claimant should call IME_Cancel to ensure that the IME knows that that session is finished. It is not normally acceptable to respond with Message_DeviceInUse, as this will render the user unable to use the IME in the other application.

2.5 IME module SWIs

IME_ProcessInput
SWI (&524C0)

On entry

bit 0 set => input value is a UCS character code; else it's a UTF-8 byte or Wimp function key code (see below)
bit 1 set => input value is a candidate list selection; else it's a key
bit 2 set => unable to handle any output/display at this point
R1 = input byte (dependent on flags)

On exit

bit 0 set => key claimed; else process this key/byte normally
bit 1 reserved
bit 2 set => IME session active - display string to be shown (R2-4 valid)
bit 3 set => Output produced by this keypress (R1 valid)
bit 4 set => IME candidate list to be shown
bit 8 set => display string has changed
bit 9 set => attribute array has changed
bit 10 set => caret position has changed
bit 11 set => candidate list has changed

Interrupts

Processor Mode

Re-entrancy

Use

Any IME aware application will need to be character-set aware. It should assume that text files, Wimp display fields, keyboard input, etc, are in the current alphabet (as read by OS_Byte 70). Applications that use the IME will have to convert text to and from UCS/UTF-8 to pass to the IME, if the current alphabet isn't UTF-8. This might be the case, for example, on a UK machine using Latin1, but with a user typing Japanese into a Unicode-capable browser.

If the system alphabet is UTF-8, you may receive multiple Key_Pressed events per keypress. For example a pound sign will arrive as &C2 &A3. F1 would arrive as &181. You may pass these codes directly to IME_ProcessInput. Alternatively, you may wish to compose them back into UCS codes. Pound would then be &000000A3. Codes &100-&1FF representing function keys should be turned into codes &80000000-&800000FF, outside of the UCS range. Thus F1 would be &80000081.

With each keypress, the IME may request that you do any or all of the following four things in order, by altering the R0 bits on exit:

1. Insert a string at your current cursor position.
2. Process the keypress normally (eg act on a function key, or insert the letter at the cursor position).
3. Display a composition string at your current cursor position, inserting the caret at a fixed point inside this string.
4. Show a candidate list.

If you are unable to handle output (if the caret is invisible, say), you should make this call with bit 2 of R0 - this will stop the IME producing any output. You must still pass keypresses into the IME so it can pick up on hotkeys.

Here are some specific examples. Let's say that your text editing area contains:

Hello |mum

Key	New display	R0	R1	R2	R3	R4
k	Hello k|mum	0111	0	"k"	1	1
a	Hello か|mum	0111	0	"か"	1	1
n	Hello かn|mum	0111	0	"かn"	1,1	2
j	Hello かんj|mum	0111	0	"かんj"	1,1,1	3
i	Hello かんじ|mum	0111	0	"かんじ"	1,1,1	3
変換	Hello 漢字mum	0111	0	"漢字"	3,3	-1
Enter	Hello 漢字|mum	1011	"漢字"	0	0	0

Sometimes a call may result both in output, together with a new display string. For example, in a Korean IME:

Key	New display	R0	R1	R2	R3	R4
ㄱ	ㄱ	0111	0	"ㄱ"	3	-1
ㅏ	가	0111	0	"가"	3	-1
ㄴ	간	0111	0	"간"	3	-1
ㅏ	가나	1111	"가"	"나"	3	-1

The styles of the display string are specified by the array pointed to by R3. This contains one byte per character (so a six-byte display string consisting of 2 Japanese characters would only have a 2-byte attribute array). Currently defined styles are:

0 = normal
1 = dotted/grey underline
2 = solid underline
3 = highlighted

The caret may or may not need to be shown in the middle of the display string; this is determined by the value of R4 on exit.

If bit 4 of R0 is set, the IME is requesting that you show a candidate list. Details of what should be shown in the list should be obtained using IME_GetCandidateListInfo.

Bits 8-11 of R0 can be used to optimise redraws.

IME_Cancel
SWI (&524C1)

On entry

On exit

Interrupts

Processor Mode

Re-entrancy

Use

You don't need to worry about caret movement via the cursor keys, as this will be spotted and dealt with appropriately via the IME. For example the IME might claim left and right cursor keys to move within the display string, but on receipt of a down cursor key output the current display string then tell the application to process that cursor key normally.

Depending on the reason for this call, you may or may not want to accept an output string. A Korean IME, for example, after the "가나" output shown above, would attempt to output the final "나" at this stage. You might accept that if the caret was just about to move because of a mouse click or a Message_DeviceClaim, but not if the window was closing.

IME_GetCandidateListInfo
SWI (&524C2)

On entry

On exit

Interrupts

Processor Mode

Re-entrancy

Use

When a candidate list is up, the main window should keep the input focus and pass keys through to the IME as usual. The IME will inform the application of any changes to the candidate list. IMEs are designed such that the same keys make sense whether or not the list is being displayed. A fourth press of 変換 would change the candidate again, for example, and move the list highlight down to the fourth item.

A candidate list normally appears as a vertical list, near the caret position. It is designed for keyboard control only - switching between the keyboard and mouse is not convenient.

It should be R3 entries high, with the entries visibly numbered 1-R3. Entries 1-R4 should be filled in with the return from IME_GetCandidateListInfo. Entry R6 should be highlighted.

Related SWIs

IME_GetCandidateListEntry
SWI (&524C3)

On entry

On exit

Interrupts

Processor Mode

Re-entrancy

Use

Related SWIs

IME_Configure
SWI (&524C4)

On entry

On exit

Interrupts

Processor Mode

Re-entrancy

Use

IME_Configure 0
SWI (&524C4)

On entry

On exit

Interrupts

Processor Mode

Re-entrancy

Use

IME_Configure 1
SWI (&524C4)

On entry

On exit

Interrupts

Processor Mode

Re-entrancy

Use

The IME flag bits are as follows:

0	IME enabled. If disabled, all calls to IME_ProcessInput will say to process the key normally (except that the IME may claim the keypress that turns the IME back on).
1	Kana mode (roman keypresses composed into Kana). May be meaningless on non-Japanese IMEs.
2	0=Hiragana, 1=Katakana. Should be 0 if bit 1 is clear. Again, probably Japanese specific.
3	0=Halfwidth, 1=Fullwidth. Some territories have the concept of "fullwidth" characters.

Related SWIs

3. Japanese IME notes

The IME engine works internally in Shift-JIS encoding. As a result, the RISC OS port will be required to translate output text to UTF-8. It further expects keypresses to be from the single-byte Shift-JIS ranges (the JIS X 0201 Roman and Katakana ranges), and has ideas about which kana keys are on which Latin keys. This must be worked around, as the keyboard driver will be passing up Unicode codes.

This translation imposes some limits on our implementation, With the IME disabled, the user will be able to press the £ on the Kana layer, and it will appear. Unfortunately, the IME will not understand this as a possible keypress, so it will be forced to ignore it or pass it through (I suggest that it be passed through if no composition is in progress, and ignore it otherwise). This is unfortunate, but Japanese users will not be expecting that key to work anyway, for exactly that reason...

The IME must interact with the keyboard driver to ensure that, say, Kana Lock is turned off when the IME is placed into Roman mode.

4. Product Organisation

The IME despatch mechanism will be provided by a new InternationalIME module.

The Japanese territory module will specify JapanIME as its default IME.

The IME dictionary, stored outside the main 8M of ROM, will be registered in ResourceFS by the ExtraResources module.

5. References

6. Glossary

7. History