---
name: "filter-key"
section: "7"
platform: "linux"
package: "libgii1"
version: "1:1.0.2-4.1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/filter-key"
---

# filter-key(7)

Generic key event translator

## NAME

**filter-key**, **filter-keytrans** - Generic key event translator

## SYNOPSIS

```
filter-key: [<file>]
filter-keytrans: [<file>]
```

## DESCRIPTION

This filter translates key events according to a set of translation rules. This can be used to remap a keyboard.

## OPTIONS

- *file*

  The name of the configuration file. If none given, the filter will first look for the file **filter/keytrans** in the user GGI directory (**$HOME/.ggi/** on UNIX), then in the base GGI directory if not found.

## CONFIGURATION

The mapping is specified through a simple text file, each line being a translation rule. A line starting with a `#` is a comment. Each line must contain 10 values in the following order:

- modifier\_mask

  Consider only the bits set here.

- modifier\_value

  The bits set above must match this value.

- button\_in, label\_in, symbol\_in

  If this is not `KEY_UNMAPPED==0xffff`, the button/label/symbol of the incoming key must match these fields.

- modifier\_changemask

  Change these bits from the original modifiers...

- modifier\_ormask

  ... set them to these - one shouldn't use that.

- button\_out, label\_out, symbol\_out

  The data that is then sent by the keymapper. Any fields set to `KEY_UNMAPPED==0xffff` will be copied from the incoming event.

## EXAMPLE

Mapping a symbol:

```
# Take any key that produces a symbol of 0x41 ('A') map it to ESC
#
# modmsk modval buttin lablin symin  modchg modor  butout labout symout
0x0000 0x0000 0xffff 0xffff 0x0041 0x0000 0x0000 0xffff 0xffff 0x001b
```