MoreKeys module API v0.04
=========================

The MoreKeys module intercepts keys pressed while Ctrl and Alt are held down.
These keys are written to a block of memory reserved in the RMA, for a front-end
program to intercept and act upon.

The MoreKeys module is intended for use only with the !MoreKeys application;
however the API has been described in case you wish to write your own front-end
(you might not like how mine works, for instance).


The SWI chunk used is &59180. It has been officially allocated (2012/03/15).


The module provides no help, no star commands, and has no configuration.

Six SWIs are available, which are documented here:


&59180  MoreKeys_DataPointer

Entry: -

Exit : R0 = Pointer to data block in RMA.
       R1 = Module version number * 100 (i.e. "123" is v1.23).
       R2 = Reserved, will be zero.
       
This returns the address of the data block in RMA. As the first word of the data
block is the keycode, and is zero UNLESS a key has been pressed, this address may
be provided to the WindowManager as a pollword.
Also supplies the version of the module in R1 to save messing around with OS_Module
calls. The value in R2 is for a future enhancement.



&59181  MoreKeys_ReadData

Entry: -

Exit : R0 = Key code (internal code, *NOT* ASCII code, refer to PRM 1-156).
       R1 = Non-zero if Shift was pressed.
       R2 = Value of monotonic timer when key pressed.

While an application could fiddle around in the RMA, perhaps a future revision of
RISC OS will tighten up what an application is permitted to access? Thus, this is
a legal API call to return the salient information.



&59182  MoreKeys_ClearData

Entry: -

Exit : R0 will have been zeroed.

Clears the data block in RMA. This should be done once the keypress has been
serviced, one way or another. Logic for this SWI is the same as above; to have a
user mode application writing into system space in the RMA is heinous (that's
apparently said like "hee-nee-us" by stupid people, who evidently cannot read).     



&59183  MoreKeys_Disable

Entry: -

Exit : -

Disables MoreKeys processing of keyboard data. Does not unlink vector claims,
but will mean MoreKeys does not interfere.



&59184  MoreKeys_Enable

Entry: -

Exit : -

Enables MoreKeys processing of keyboard data.



[ ONLY IN DEBUG BUILDS:

&5918x  MoreKeys_DumpStatus

Entry: -

Exit : R0-R2 corrupted.

Writes out MoreKeys status (direct kernel character output). Must be used outside
of the Desktop environment. If you have the test program "TestMorKys", you'll see
what this SWI does.

This SWI is provided for debugging/development purposes. You should not use it
yourself, nor rely upon it existing in future versions. If you call this SWI,
always call it by name and never by SWI number as a future version may have here
a SWI that does something else...

]



The memory block in RMA is as follows:

  +0   Internal key code (not ASCII code)
  +4   One if Shift pressed, else zero.
  +8   Value of monotonic timer when key pressed.
  ; the following are for internal purposes, not you ;-)
  +12  1 if MoreKeys processing is DISABLED (else 0).
  +16  1 if Ctrl pressed, else 0.
  +20  1 if Alt pressed, else 0.
  +24  Workspace for debug SWI (12 bytes). [just pretend this doesn't exist...]

The Shift/Ctrl/Alt keypress markers are updated in realtime. The key code and
timer value are only updated when a Ctrl-Alt-keypress occurs.

If key processing has been disabled, none of this is relevant.



API documentation by Rick Murray
Copyright © 2012-2013 Rick Murray

http://www.heyrick.co.uk/software/morekeys/