Introduction to KeyHelper

From OESF

See also

• Zaurus Keyboard Keys

---

Contents 1 Introduction 2 Modifiers 3 Mapping Keys 4 Key Repeat 5 KeyHelper Extensions 6 Tips 6.1 Launch1 Keys 6.2 Launching applications 6.3 By Application 7 External USB Keyboard 7.1 Switching Layouts 7.2 Layouts

Introduction

Many of you are probably aware of the keymapping abilities of KeyHelper, but you may not be aware of some of the other features including:

• Changing key repeat rates
• Task Switching
• Task Selection from list
• Application launching
  • from hot key
  • from menu

Most of the examples below were taken from this very helpful tutorial on KeyHelper (Japanese) and from the KeyHelper Home Page. Any mistakes in this document are mine and probably due to my poor Japanese and typing skills.

Note that if you're running Cacko Qtopia ROM version 1.21 and above, KeyHelper functionality is merged with Cyrillic keyboard layout applet. No separate KeyHelper package installation is requried.

The following example is a simple keyhelper.xml files which sets the Kana key (1st Japanese key) to Ctrl, turns on toggle for Shift, maps Fn+O and Fn+P as { and } and defines Home as the task switch key.

<?xml version="1.0"?>
<keyhelper>
<modifiers>
<define key="F26" type="Control">
<release key="F31"/>
</define>
<define key="F12" type="User1">
</define>
<define key="Shift" type="Shift" toggle="True"/>
</modifiers>
<mappings>
<define code="2015">
<map_modifier Shift="On"/>
<map key="Less"/>
</define>
<define code="2016">
<map_modifier Shift="On"/>
<map key="Greater"/>
</define>
</mappings>
<repeater>
<repeat delay="300" period="30"/>
</repeater>
<extensions>
<define key="F12" kind="switch">
<modifier Shift="On"/>
</define>
<define key="All" kind="launch">
<modifier User1="On"/>
</define>
</extensions>
</keyhelper>

By copying and pasting this into a file named keyhelper.xml and copying it into /home/zaurus/Settings and running khctl reload from the console you will have a Ctrl key, Shift will be a toggle, Fn+O/P will give {/} and Shift+Home will switch between running apps.

The keyhelper.xml file has 4 sections

1. <modifiers> - changes/assigns keys such as Shift, Ctrl, Alt as well as the ornamental keys Home, Address etc.
2. <mappings> - changes mapping of normal keys or key combos
3. <repeater> - sets the key repeat rate
4. <extensions> - changes what keys are used for special keyhelper functions - task switcher, task selector and launcher.

I'll explain these section in more detail as well as give examples below.

Modifiers

Some examples will help to explain the format of this section.

<define key="F26" type="Control" mapping="True">

<release key="F31"/>

</define>

<define key="F26" type="Control" mapping="True"> Sets [[Kana] key (first Japanese key) to be the control key, key= can also be replaced by code= if you prefer to set a key combination to be a modifier key. type= is one of the "Ornamental" keys ([[Address],[[Home],[[Calendar],[[Mail],[[Menu]) or the standard modifier keys ([[Shift],[[Ctrl],[[Alt]). Setting mapping="True" and not supplying a mapping in the <mapping> section makes this key lose its normal function. In the above example the [[Kana] key will no longer switch between hiragana and katakana - it will only act as [Ctrl].

<define key="Shift" type="Shift" toggle="True"/>

This short example higlights the toggle="True" feature which turns on the toggle feature for modifier keys.

Mapping Keys

Mapping keys is a relatively simple matter of working out the key/code you want to change and the key/code you want it to be. Here are 2 examples

<define code="2015">

<map_modifier Shift="On"/>

<map key="Less"/>

</define>

This is a simple example to start <define code="2015"> is the key code we want to change (in this case [[Fn]+O), we could also use <define key="P"> if we wanted to change the function of the P key. <map key="Less"/>' identifies what we want the changed key/code to be. It can also be modified with [[Alt],[[Ctrl],[[Shift] etc with the <map_modifier Shift="On"/> line. In this example we have changed [[Fn]+O to [[Shift]+[[Less] ({ key).

<define key="F26">

<modifier Shift="On"/>

<map key="Alt"/>

<map_modifier Shift="Off"/>

</define>

The second example maps the [[Alt] key to [[Shift]+[[Ctrl] - remember that the first Japanese key = [[Ctrl]. <define key="F26"> is the first Japanese key, <modifier Shift="On"/> means that we only map the key when pressed with [[Shift], as in the previous example <map key="Alt"/> sets the key we want, and the <map_modifier Shift="Off"/> cancels the [[Shift] button.

Key Repeat

<repeater>

<repeat delay="300" period="30" mode="1"/>

</repeater>

This is a nice simple example that turns on key repeat, with a delay of 300 milliseconds and a repeat rate of 30 milliseconds.

KeyHelper Extensions

KeyHelper offers a number of extended features that are quite useful. The example below shows how to set up task switching and task selection.

<define key="F12" kind="switch">

<modifier Shift="On"/>

</define>

<define key="F11" kind="select">

<modifier Shift="On"/>

</define>

With this example [[Shift]+[[Home] can be used to switch between running applications, while [[Shift]+[[Menu] will bring up a list of active applications allowing you to select which one to switch to.

More to come on using KeyHelper as a program launcher and other goodies once I understand and work out what I'm doing - StuBear

Tips

Launch1 Keys

If you define a launch1 key in your keyhelper.xml, you will be able to "launch" a macro by pressing a key with no modifier (i.e. just the key and not launch+key).

Example:

keyhelper.xml:

   <extensions>
       <define key="All" kind="launch1" />
   </extensions>

keyhelper.conf (page down for netfront3 in landscape view):

   [Launch1_netfront3]
   Space = @qcop	QPE/InputHelper 'mouse(QString)' "click 620 384"

Launching applications

There are at least two ways to launch an applications: via the launcher or via qcop (which let's you pass an argument to the application). See this example:

   [Launch]
   N = Applications/netfront3
   T = @qcop	QPE/System 'execute(QString)' qkonsole

Press down the launch key (as defined in your keyhelper.xml) + n or t to run these applications.

By Application

• Keyhelper Netfront3
• Keyhelper Filelaunch
• Keyhelper QKonsole

External USB Keyboard

Switching Layouts

In my setup, two keyhelper.xml files are stored in ~/Settings: keyhelper_zaurus.xml (which is linked to keyhelper.xml) and keyhelper_use.xml. I (tml) use the following opie-sh script to switch between these two files:

   #!/bin/bash
   
   function doit {
       echo Switching to: $1
       cd /home/zaurus/Settings
       khctl load keyhelper_$1.xml
   }
   
   opie-sh -m -w -M "Switch Keyhelper Layout" -0 Cancel -1 Zaurus -2 USB
   RV=$?
   case $RV in
   1)
       doit zaurus;:
   2)
       doit usb;:
   *)
       echo Nope ... $RV
   esac

Layouts

Here is the xml file for an external USB keyboard:

Keyhelper German Keyboard Layout 

I use a small benq keyboard; the <>| key isn't recognized by keyhelper, which is why it is mapped to the ´` key (´` is mapped to control-´`); launch is mapped to the print key