<document title="PC Keyboard2">
<define name="version" value="0.00">
<define name="date" value="1 January 1900" length=30 align="right">





<literal mode="Text">
=============================================================================
PC Keyboard 2 - PC Keyboard Emulation                            Version $$version$$

(C) Stephen Fryatt, 2003-2020                  $$date$$
=============================================================================

</literal>







<chapter title="Licence" file="Licence">

<cite>PC&nbsp;Keyboard</cite> is licensed under the EUPL, Version&nbsp;1.2 only (the &ldquo;Licence&rdquo;); you may not use this work except in compliance with the Licence.

You may obtain a copy of the Licence at <link ref="#url http://joinup.ec.europa.eu/software/page/eupl">http://joinup.ec.europa.eu/software/page/eupl</link>

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an &ldquo;<strong>as is</strong>&rdquo; basis, <strong>without warranties or conditions of any kind</strong>, either express or implied.

See the Licence for the specific language governing permissions and limitations under the Licence.

The source for <cite>PC&nbsp;Keyboard</cite> can be found alongside this binary download, at <link ref="#url http://www.stevefryatt.org.uk/software">http://www.stevefryatt.org.uk/software</link>

The necessary libraries and build tools can be found at <link ref="#url http://www.stevefryatt.org.uk/software/build">http://www.stevefryatt.org.uk/software/build</link>

</chapter>




<chapter title="Introduction" file="Introduction">

<cite>PC&nbsp;Keyboard</cite> is a module to change the use of the <key>delete</key>, <key>end</key> (<key>copy</key>) and <key>home</key> keys in applications under RISC&nbsp;OS.  Historically, the <key>delete</key> key on RISC&nbsp;OS has always duplicated <key>backspace</key>, which is different from the behaviour on other platforms.  On RISC&nbsp;OS&nbsp;5 this behaviour is changed to the &ldquo;PC&nbsp;style&rdquo; and the OS tries to enforce this, but not all applications follow suit.

The module can be used in three ways:

<list spacing=1>
<li>It can be used on RISC&nbsp;OS&nbsp;5 to convert applications fixed in &ldquo;Acorn style&rdquo; operation over to the &ldquo;PC&nbsp;style&rdquo; used by the OS.

<li>Alternatively, on RISC&nbsp;OS&nbsp;5, it can be used to convert the behaviour of writable icons, and any applications which detect the OS and insist on &ldquo;PC&nbsp;style&rdquo; operation, back to &ldquo;Acorn style&rdquo; usage.

<li>On all other versions of RISC&nbsp;OS, it can be used to convert the behaviour of applications and writable icons to &ldquo;PC&nbsp;style&rdquo; operation.
</list>

<cite>PC&nbsp;Keyboard&nbsp;1</cite> worked at a low level in RISC&nbsp;OS, changing the codes returned from the keyboard.  This ensured that the changes took effect in all parts of the OS, but it could also conflict with third-party keyboard extenders.

With the arrival of RISC&nbsp;OS&nbsp;5, where the Wimp and bundled applications already use the &ldquo;PC&nbsp;style&rdquo; actions by default, <cite>PC&nbsp;Keyboard&nbsp;2</cite> has been written to work on an application by application basis by applying Wimp filters.  This allows it to only work on those applications which need to be modified and, because it can work at a much higher level in the OS, many of the old conflicts have been resolved.

Where possible, I recommend updating applications to correct their use of <key>delete</key> instead of adding them to the list in <cite>PC&nbsp;Keyboard</cite>.  Many RISC&nbsp;OS applications (such as <cite>Zap</cite> and <cite>Pipedream</cite>) can have their key bindings changed by editing a file contained in the application; many others have a simple &ldquo;PC&nbsp;Delete&rdquo; option in their configuration.  If possible, this is a better solution than filtering them with this module.

</chapter>




<chapter title="Installation" file="Installation">

Installing <cite>PC&nbsp;Keyboard</cite> is a matter of running the <file>!PCKeys</file> application supplied in the archive.  As supplied, this is configured to convert RISC&nbsp;OS&nbsp;5 applications into &ldquo;PC&nbsp;style&rdquo; operation.

If you wish to run <cite>PC&nbsp;Keyboard</cite> on startup, you should add it to the &lsquo;Run list&rsquo; in <cite>Configure</cite>.  To do this, double-click on <file>!Boot</file>, open the <icon>Boot</icon> option and then open the <icon>Run</icon> window.  Drag <file>!PCKeys</file> into the scrolling list and click on the two <icon>Set</icon> buttons.

The default configuration is designed for use on RISC&nbsp;OS&nbsp;5, and it adds filters for <cite>Writer</cite> and <cite>FireWorkz</cite>. You should now find that the operation of <key>delete</key>, <key>end</key> and <key>home</key> has changed in these two bundled applications.

If you wish to use <cite>PC&nbsp;Keyboard</cite> with other applications, or in one of the other modes of operation (converting RISC&nbsp;OS&nbsp;5 back to &ldquo;Acorn style&rdquo; keys, or on another version of RISC&nbsp;OS), it will need to be configured differently.  This is described in the next section.

</chapter>





<chapter title="Configuration" file="Config">

The behaviour of <cite>PC&nbsp;Keyboard</cite> can be modified in various ways, either to switch it between the three operating modes outlined above, or to change the list of applications that are being intercepted.

All the configuration options are set using star-commands; the startup configuration is set in the file <file>!PCKeys.Configure</file>, which should be loaded into a text editor for modification.

The file is an obey file, which can be configured in a number of ways.


<subhead title="PC-style behaviour on RISC OS 5">

An example of a <file>Configure</file> file for achieving &ldquo;PC style&rdquo; keys on RISC&nbsp;OS&nbsp;5 is shown here:

<codeblock>
| >Configure
|
| Configuration file for PCKeys 2

| Set the options for the module.

PCKeysConfigure -adelete &18B -aend &1AC -ahome &1AD
PCKeysConfigure -nicons

| Select the applications to filter on

PCKeysAddApp Writer
PCKeysAddApp "Fireworkz&nbsp;32"
PCKeysAddApp OvationPro
PCKeysAddApp Zap
PCKeysAddApp "Impression Publisher"
</codeblock>

The lines starting with vertical bars are comments that are ignored.  The lines at the top starting with <code>PCKeysConfigure</code> set the functions to be carried out and the new assignments for the three keys. The keys are set using Wimp key codes; this is described in more detail later.

The lines starting <code>PCKeysAddApp</code> add applications to the list that <cite>PC&nbsp;Keyboard</cite> will operate on.  New applications can be added on subsequent lines, copying the same format.  The name should be entered as shown in the <icon>Application Tasks</icon> and <icon>Module Tasks</icon> sections of the <cite>Task Manager</cite> with respect to spacing and spelling (though the matching is done case-insensitively).

This may take some trial and error.  For example, <cite>FireWorkz</cite> uses a hard space (entered by <key>alt</key>-<key>space</key>) between <code>Fireworkz</code> and <code>32</code>.  Entering a normal space will not match the application name, but this is not obvious from looking at the <cite>Task Manager</cite> entry.

Once you have added your applications, save the file and re-load <file>!PCKeys</file>.  To check which applications are being watched for, press <key>ctrl</key>-<key>f12</key> and enter <command>*PCKeysListApps</command>.  This will show a list of all the applications that <cite>PC&nbsp;Keyboard</cite> knows about, as well as how many copies of them are currently running.

Applications can also be added from the command line, using the <command>*PCKeysAddApp</command> command in the same was as in the <file>Configure</file> file.  Because these are not remembered in the configuration file, they will be forgotten when <cite>PC&nbsp;Keyboard</cite> is next run.

<subhead title="Acorn-style behaviour on RISC OS 5">

To replace the &ldquo;PC&nbsp;style&rdquo; behaviour of RISC&nbsp;OS&nbsp;5 with that used on older Acorn machines, the following configuration file should be used instead:

<codeblock>
| >Configure
|
| Configuration file for PCKeys 2

| Set the options for the module.

PCKeysConfigure -adelete &08 -aend &7F -ahome &1E
PCKeysConfigure -idelete &08 -iend &7F -ihome &AC -ibacksp &08
PCKeysConfigure -icons

| Select the applications to filter on

PCKeysAddApp Edit
</codeblock>

A list of applications to filter is added at the end in the same way as before. In this case, applications should be added if they are hard-coded to use the new RISC&nbsp;OS&nbsp;5 keypresses and can not be configured out of this behaviour.


<subhead title="PC-style behaviour on RISC OS 3, 4 or 6">

Finally, to achieve &ldquo;PC&nbsp;style&rdquo; <key>delete</key> on RISC&nbsp;OS&nbsp;3, 4 or 6, the following configuration file should be used:

<codeblock>
| >Configure
|
| Configuration file for PCKeys 2

| Set the options for the module.

PCKeysConfigure -adelete &18B -aend &1AC -ahome &1AD
PCKeysConfigure -idelete &8B -iend &AD -ihome &AC -ibacksp &7F
PCKeysConfigure -icons

| Select the applications to filter on

PCKeysAddApp Edit
</codeblock>

A list of applications to filter is added at the end in the same way as before. This needs to include all applications that take input directly (ie. not using writable icons) and can not be configured to use &ldquo;PC&nbsp;style&rdquo; delete directly.

</chapter>





<chapter title="Star Commands" file="Commands">

The following star commands are supported by <cite>PC&nbsp;Keyboard</cite>.

<comdef target="*PCKeysAddApp" params="[-task] &lt;task name&gt;">

The command <command>PCKeysAddApp</command> is used to add an application to the list of ones to be filtered.  The task name is the one shown in the Task Manager: if a name has a space, enclose it in double-quotes.

When this command is issued, the application name is remembered and if the task is running a filter is applied immediately.  Once a task is on the list, a filter will be added when it is loaded and removed when it is quit.

The <command>-task</command> tag is optional, and can be used to prefix the task name.

</comdef>



<comdef target="*PCKeysRemoveApp" params="[-task] &lt;task name&gt;">

The command <command>PCKeysRemoveApp</command> removes an application from the list to be filtered.  The task name is the one shown in the list from <command>*PCKeysListApps</command> and in the <cite>Task Manager</cite>.

When this command is issued, any active filters are removed and the application name is removed from the list stored by <cite>PC&nbsp;Keyboard</cite>.

</comdef>



<comdef target="*PCKeysListApps" params="">

<command>PCKeysListApps</command> lists the applications currently known to <cite>PC&nbsp;Keyboard</cite>.  The output shows the name of the application, along with the number of filters currently applied.  One filter is applied for each copy of the application running.

</comdef>


<comdef target="*PCKeysConfigure" params="[options]">

The <command>PCKeysConfigure</command> command is used to change the operation of the <cite>PC&nbsp;Keyboard</cite> module.  It takes a number of parameters which determine which options are to be changed.  If no parameters are supplied, the current status is displayed.

The first group of parameters defines the key modifications used when filtering applications:

<definition target="-adelete &lt;key code&gt;">
The <command>-adelete &lt;key code&gt;</command> option sets the key to which the <key>delete</key> key is mapped for applications.  By default this is &amp;18B, which is <key>end</key>.
</definition>

<definition target="-aend &lt;key code&gt;">
The <command>-aend &lt;key code&gt;</command> option sets the key to which the <key>end</key> key is mapped for applications.  By default this is &amp;1AD, which is <key>ctrl</key>-<key>right</key>.  The alternative <command>-acopy &lt;key code&gt;</command> can also be used.
</definition>

<definition target="-ahome &lt;key code&gt;">
The <command>-ahome &lt;key code&gt;</command> option sets the key to which the <key>home</key> key is mapped for applications.  By default this is &amp;1AC, which is <key>ctrl</key>-<key>left</key>.
</definition>

Where key codes are used, these are the ones returned by the Wimp from <code>Wimp_Poll</code>.  These are listed in the <cite>Programmers&rsquo; Reference Manuals</cite> and the StrongHelp manuals.  Some useful ones are:

<list>
<li>&amp;18B &ndash; <key>Copy</key>
<li>&amp;18C &ndash; <key>Left</key>
<li>&amp;18D &ndash; <key>Right</key>
<li>&amp;18E &ndash; <key>Down</key>
<li>&amp;18F &ndash; <key>Up</key>
</list>

In each case, change the central &ldquo;8&rdquo; to &ldquo;9&rdquo; for a shifted key, &ldquo;A&rdquo; for a Ctrl key and &ldquo;B&rdquo; for a Ctrl-Shift key.  <key>page up</key> and <key>page down</key> are tied in to <key>up</key> and <key>down</key> to ensure the correct default behaviour, so it is not possible to access these keys independently.

The next group of parameters defines the key modifications used when typing into writable icons:

<definition target="-idelete &lt;key code&gt;">
The <command>-idelete &lt;key code&gt;</command> option sets the key to which the <key>delete</key> key is mapped in writable icons.  By default this is &amp;8B, which is <key>end</key>.
</definition>

<definition target="-ibacksp &lt;key code&gt;">
The <command>-ibacksp &lt;key code&gt;</command> option sets the key to which the <key>backspace</key> key is mapped in writable icons.  By default this is &amp;7F, which is <key>delete</key>.
</definition>

<definition target="-iend &lt;key code&gt;">
The <command>-iend &lt;key code&gt;</command> option sets the key to which the <key>end</key> key is mapped in writable icons.  By default this is &amp;AD, which is <key>ctrl</key>-<key>right</key>.  The alternative <command>-icopy &lt;key code&gt;</command> can also be used.
</definition>

<definition target="-ihome &lt;key code&gt;">
The <command>-ihome &lt;key code&gt;</command> option sets the key to which the <key>home</key> key is mapped in writable icons.  By default this is &amp;AC, which is <key>ctrl</key>-<key>left</key>.
</definition>

Where key codes are used, these are the ones inserted into the keyboard buffer by RISC&nbsp;OS.  Some useful ones are:

<list>
<li>&amp;8B &ndash; <key>Copy</key>
<li>&amp;AC &ndash; <key>Left</key>
<li>&amp;AD &ndash; <key>Right</key>
</list>

Finally, the last two parameters turn the writable icon key modification on or off:

<definition target="-icons">
The <command>-icons</command> option enables key swapping in writable icons.
</definition>

<definition target="-nicons">
The <command>-nicons</command> option disables key swapping in writable icons.
</definition>

</comdef>



</chapter>



<chapter title="Known issues" file="Issues">

There are currently no known issues with <cite>PC&nbsp;Keyboard</cite>. If you find a bug, or have any comments, my email address is at the end of the file.

</chapter>




<chapter title="Version history" file="History">

The following is a list of all the versions of <cite>PC&nbsp;Keyboard</cite>.


<subhead title="2.00 (23 May 2003)">

Public Alpha release.

<list>
<li>First public release of new module, for use on Iyonix.
</list>

<subhead title="2.01 (7 Jun 2003)">

Public Beta Release.

<list>
<li>Added <command>*PCKeysRemoveApp</command> command.
<li>Added <command>*PCKeysConfigure</command> command.
<li>Support for changing <key>end</key> and <key>home</key> keys added.
<li>Command parameter parsing done via OS_ReadArgs so that it can handle quoted strings and multiple options.
<li>Task and filter tracking improved so that multiple instances of the same application can be supported.
</list>

<subhead title="2.09 (9 Jan 2005)">

Public Alpha release.

<list>
<li>Added facilities for changing keypresses in writable icons.
<li>Changed <command>*PCKeysConfigure</command> arguments to allow for different settings in writable icons.
</list>

<subhead title="2.10 (5 Aug 2007)">

<list>
<li>Improved documentation and initial configuration.
<li>Finally removed &ldquo;alpha&rdquo; tag following two years of no bug reports.
</list>

<subhead title="2.11 (2 Feb 2014)">

<list>
<li>Converted source code into Asasm format and restructured build tools.
<li>Improved SWI error handling.
<li>Correctly handle user-made <command>*Desktop_PCKeys</command> calls.
<li>Checked code for ARMv7 compatibility.
</list>

<subhead title="2.12 (30 Aug 2020)">

<list>
<li>Licence updated to EUPL&nbsp;v1.2.
<li>Use Wimp_PollIdle on a 10cs interval to monitor caret position, to reduce load on system (ticket&nbsp;#540).
<li>Disable Null Events when modification of icon keypresses is configured off, to reduce the system load.
</list>

</chapter>




<literal mode="Text">

Updates and Contacting Me
-------------------------

  If you have any comments about PC Keyboard, or would like to report any
  bugs that you find, you can email me at the address below.

  Updates to PC Keyboard and more programs for RISC OS computers can be
  found on my website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
</literal>
