Differences between revisions 95 and 96
Revision 95 as of 2022-05-25 01:41:05
Size: 18761
Editor: OsamuAoki
Comment: describe difference xmodmap/input method
Revision 96 as of 2022-05-25 03:21:36
Size: 19338
Editor: OsamuAoki
Comment: input modules for GTK/QT
Deletions are marked like this. Additions are marked like this.
Line 257: Line 257:
   * '''{{{XMODIFIERS}}}''' typically set to ''@im=<input-method>'' to enable a particular input method for application using XIM.
   * Daemon for serving XIM is started.
   * '''{{{GTK_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular input method for application using GTK.
   * '''{{{QT_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular input method for application using QT.
   * '''{{{XMODIFIERS}}}''' typically set to ''@im=<input-method>'' to enable a particular input method for application using XIM.
       * Daemon for serving XIM is started by the hook script.
   * '''{{{GTK_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular input method for application using GTK2/GTK3.
       * Required input modules such as DebianPkg:ibus-gtk3 and DebianPkg:ibus-gtk need to be installed.
  
* '''{{{QT_IMMODULE}}}''' (or similar) typically set to ''<input-method>'' to enable a particular input method for application using QT4/QT5.
       * Required input modules such as DebianPkg:ibus-qt4 and DebianPkg:libqt5gui5 need to be installed.
Line 262: Line 264:
   * Setups of environment variables different from what the default ones provided by DebianPkg:im-config are not recommended nor supported. Those random tips seen on the web are usually meant to be workaround for temporary breakage only. If you see any one of '''{{{XMODIFIERS=@im=none}}}''', '''{{{GTK_IM_MODULE=xim}}}''' or '''{{{QT_IM_MODULE=xim}}}''' for your program's running environment, you are in trouble.
Line 283: Line 286:
Properly configured GTK and QT programs with DebianPkg:im-config don't use XIM mechanism and are immune to these annoying bugs of XIM. (If you see '''{{{GTK_IM_MODULE=xim}}}''' or '''{{{QT_IM_MODULE=xim}}}''', you are in trouble.) Properly configured GTK and QT programs with DebianPkg:im-config don't use XIM mechanism and are immune to these annoying bugs of XIM.

Translation(s): English - Français - Italiano - Português (Brasil) - Русский


Portal/IDB/icon-wiki-portal.png

Debian wiki keyboard portal. This portal covers all aspects of configuring keyboards on Debian.

See "The keyboard input" in debian-reference, too.

Basic keyboard configuration

To configure the keyboard, you have to install keyboard-configuration. The package console-setup is also needed.

The keyboard settings are stored in /etc/default/keyboard file provided by the keyboard-configuration package. Other packages use this to configure both the Linux kernel and the X Window system to realize consistent keyboard experiences under the Linux console and the X Window system.

You can change your keyboard settings using:

 # dpkg-reconfigure keyboard-configuration
 # service keyboard-setup restart
  1. Menu for Keyboard model (what the keyboard *is*) is presented. If not sure, choose:

    • "Generic 104-key PC" for US-type keyboard with "Windows-key"
    • "Generic 105-key PC" for ISO-type keyboard with "Windows-key" (and JIS-type keyboard with "Windows-key")
  2. Menu for Country of origin for the keyboard is presented. If not sure for this, choose:

    • "English (US)" for "QWERTY"-keyboard
    • "German" for "QWERTZ"-keyboard
    • "French" for "AZERTY"-keyboard
    • "Japanese" for "QWERTY"-keyboard with extra keys aimed for Japanese.
  3. Menu for Keyboard layout (what the keys should *do*) is presented. If not sure for this, choose:

    • "English (US)" for plain layout (English)
    • "English (intl., with ?AltGr dead keys)" to have access to accented characters etc.

    • "Default" for plain layout (German, French)
    • "Japanese" for plain layout (Japanese)
    • "Dvorak" etc. if you want.

To apply new settings, restarting the keyboard-setup service should suffice, otherwise you can try to restart kernel input system via udev:

 # udevadm trigger --subsystem-match=input --action=change

or reboot the whole OS.

Modern keyboard configuration (input method)

The simple keyboard input mechanism realized by the above configuration can't support some languages, such as Chinese and Japanese, properly.

The installation of the input method framework package such as ibus (or fcitx5) together with associated packages enables to support all languages.

When any of the input method framework packages are installed and activated, the X Window based keyboard configuration settings are ignored for programs based on GTK or QT library. This is because keyboard inputs are passed directly to the application software via GTK or QT library without going through X Input method (XIM).

For GNOME system (the default Debian Desktop environment), ibus package is automatically installed and activated. The keyboard input needs to be configured from its GUI Settings -> Keyboard for basic configurations. For more complicated configuration such as swapping CapsLock and Ctrl, you need to install gnome-tweak and use it.

For non-GNOME system, the stand alone GUI configuration command ibus-setup can set up the input methods for ibus. Under those desktop environments, menu entry of their keyboard configuration utility or pop-up menu entry offered by clicking the associated tray icon may start ibus-setup for you.

For KDE, configuration of ibus is System_settings -> Hardware -> Input_devices/keyboard. Tray icon is available as kimpanel in plasma-widgets-addons package.

See I18n/ibus and I18n/Fcitx5 for more.

Multi-language keyboard configuration strategy

People who wish to set up a single keyboard input environment for multiple (European) languages without the input method framework should consider following configuration strategy.

  • If the input method package is installed, deactivate it by executing im-config -n none.

  • Select the correct keyboard model. (US/ISO)
  • Select the desirable keyboard layout. E.g., English (US International ?AltGr Unicode combining,alternative)

  • (optional) Set up the keyboard behavior using xkbcomp call in ~/.xsession for X keyboard Extension (XKB).

People who wish to set up multiple dynamically-switchable keyboard input environments for multiple languages should consider following configuration strategy.

  • Install input method framework package such as ibus

  • (optional) Install pertinent input method engine package such as ibus-anthy

  • Activate desirable input engine/keyboard layout by adding it from menu such as Settings -> Keyboard -> Input Sources and configure them.

  • Switch among input methods with by pressing GUI-SPACE.

Please note that the input method framework such as ibus provides its internal functionality equivalent of X keyboard Extension (XKB) to enter many Unicode characters for European languages without additional engine packages and its configuration is available in GNOME Tweaks program under Keyboard & Mouse -> Additional Layout Options. See below for the non-GUI method to set these.

See "Input method and XIM" for cares required to use input method smoothly.

Keyboard configuration Tips

Manual configuration of keyboard

You can edit /etc/default/keyboard manually instead of running dpkg-reconfigure keyboard-configuration.

Here's an example:

# KEYBOARD CONFIGURATION FILE
# Consult the keyboard(5) and xkeyboard-config(7) manual page.

XKBMODEL="pc105"
XKBLAYOUT="us,de,fr,ua,ru"
XKBVARIANT=""
XKBOPTIONS="grp:alt_shift_toggle"
BACKSPACE="guess"
  • XKBMODEL is a keyboard model variable (look at a /usr/share/X11/xkb/rules/base.lst (plain text) or /usr/share/X11/xkb/rules/base.xml (XML) for a full list);

  • XKBLAYOUT variable contains a list of used layouts;
  • "grp:alt_shift_toggle" sets a layout switching key combination (<Alt>+<Shift>).

Under the X environment, this keyboard layout setting in /etc/default/keyboard can be overridden by executing something like "setxkbmap us,ru -option grp:ctrl_shift_toggle" in the X startup configuration file ~/.xsessionrc . Please note that this is effective only for the X environment and the modern GUI environment may not be running under X environment.

See also:

How to set keyboard layout in initramfs

The appropriate section of /etc/initramfs-tools/initramfs.conf needs to be changed to have a localized keyboard layout at boot time:

#
# KEYMAP: [ y | n ]
#
# Load a keymap during the initramfs stage.
#

KEYMAP=y

Apply changes:

 # update-initramfs -u

How to enable USB keyboard in initramfs

The initramfs-tools must include the usbhid module and its dependencies for USB keyboard support at boot time. Either the configuration file /etc/initramfs-tools/conf.d/driver-policy must include most modules, or they will have to be specified in another file:

#
# MODULES: [ most | netboot | dep | list ]
#
# most - Add most filesystem and all harddrive drivers.
#
# dep - Try and guess which modules to load.
#
# netboot - Add the base modules, network modules, but skip block devices.
#
# list - Only include modules from the 'additional modules' list
#

MODULES=most

If the configuration above was not set to include most modules, then the necessary modules have to be specified in the file /etc/initramfs-tools/modules:

# USB keyboard at boot
usbcore
uhci_hcd
ehci_hcd
usbhid

Apply changes:

 # update-initramfs -u

How to dynamically activate Linux console settings

In order to activate changed settings in /etc/default/keyboard without reboot, run setupcon(1).

How to dynamically activate X Window settings

If the input method framework is not active, you can switch the keyboard layout of X Window system from the terminal, e. g.:

 $ setxkbmap de
 $ setxkbmap fr
 $ setxkbmap us

Of special interest for keyboard hardware with us layout might be the altgr-intl variant (this provides a simple AltGr mapping for many umlauts and special symbols):

 $ setxkbmap -rules evdev -model evdev -layout us -variant altgr-intl

or

 $ setxkbmap -model pc105 -layout us -variant altgr-intl

To configure a simple key for toggling between multiple configured keyboard layouts, see Option XkbOptions in Section InputClass somewhere within the xorg config file collection (see [SOLVED] Setxkbmap .xinitrc).

How to dynamically manage input source settings from the command line

Input source settings can be dynamically managed using gsettings, dconf, or dconf-editor commands. Here, gsettings command is the platform independent wrapper of Linux specific dconf command and dconf-editor is a GUI program.

The current input source setting and the current XKB input source can be obtained from the command line. For example:

 $ gsettings get org.gnome.desktop.input-sources sources
[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]
 $ gsettings get org.gnome.desktop.input-sources xkb-options
['lv3:ralt_switch', 'compose:rwin']

or

 $ dconf read /org/gnome/desktop/input-sources/sources
[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]
 $ dconf read /org/gnome/desktop/input-sources/xkb-options
['lv3:ralt_switch', 'compose:rwin']

These can be updated to a certain values. For example:

 $ gsettings set org.gnome.desktop.input-sources sources "[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]"
 $ gsettings set org.gnome.desktop.input-sources xkb-options "['lv3:ralt_switch', 'compose:rwin']"

or

 $ dconf write /org/gnome/desktop/input-sources/sources "[('xkb', 'us'), ('ibus', 'anthy'), ('ibus', 'mozc-jp')]"
 $ dconf write /org/gnome/desktop/input-sources/xkb-options "['lv3:ralt_switch', 'compose:rwin']"

These can be reset by using gsettings reset ... or dconf reset ....

How to create a custom keyboard shortcut to select a particular input source

For GNOME, you can create a custom keyboard shortcut to select a particular input source deterministically by assigning command to Settings -> Keyboard -> Keyboard Shortcuts (instead of using Super-SPACE toggle). E.g. As explained elsewhare, the following command will select the first input source:

gdbus call --session --dest org.gnome.Shell --object-path /org/gnome/Shell --method org.gnome.Shell.Eval  "imports.ui.status.keyboard.getInputSourceManager().inputSources[1].activate()"

Keyboard configuration for backspace/delete and terminal type

The good review of the complicated situation over the keyboard configuration for backspace/delete and terminal type is available in /usr/share/doc/xterm/README.Debian.

Debian default keymap for xterm is DEC VT 220 like terminal behavior which is consistent with the Linux virtual console. This frees CTRL-H from backspace action and allows us to use CTRL-H for other purposes in programs such as Vim.

How to use kitty terminal with input method

GPU based terminal emulator kitty doesn't use X, GTK, nor QT library but uses Wayland library. In order to activate input method to enter some characters for Chinese or Japanese, you need to follow /usr/share/doc/kitty/README.Debian.

Overview of keyboard input

Historic situation over the keyboard input

Before the introduction of Wayland, situation over the keyboard input can be summarized as follows:

  • GUI environment was provided only by the X system.
  • For Linux virtual console, its keyboard input is handled by Linux kernel. See keymap(5).

  • For X environment without input method, its keyboard input is handled by X server by calling low level call to Linux kernel and using its own keymap. See X(7) and xmodmap(1).

  • For X environment with input method, its keyboard input is handled by input method. See I18n/ibus and I18n/Fcitx5.

    • Hook script by im-config set up environment variables and daemon as a part of X start-up.

      • XMODIFIERS typically set to @im=<input-method> to enable a particular input method for application using XIM.

        • Daemon for serving XIM is started by the hook script.
      • GTK_IMMODULE (or similar) typically set to <input-method> to enable a particular input method for application using GTK2/GTK3.

      • QT_IMMODULE (or similar) typically set to <input-method> to enable a particular input method for application using QT4/QT5.

    • This allows us to type not only many accented characters but also Chinese and Japanese characters.
    • Setups of environment variables different from what the default ones provided by im-config are not recommended nor supported. Those random tips seen on the web are usually meant to be workaround for temporary breakage only. If you see any one of XMODIFIERS=@im=none, GTK_IM_MODULE=xim or QT_IM_MODULE=xim for your program's running environment, you are in trouble.

Current situation over the keyboard input (as of 2022)

The introduction of Wayland changed situation over the keyboard input and required im-config to be updated.

To be written: XXX_FIXME_XXX

Troubleshooting

Input method and XIM

Input method framework: Activated case

When input method framework such as ibus is installed and activated, pure X application programs (XIM clients which get keyboard inputs from XIM mechanism) such as xterm and rxvt-unicode don't talk to the X server directly. The input method framework such as ibus handles actual keyboard inputs and pass processed data to XIM clients, instead. (I.e., xkbcomp call in ~/.xsession is ignored)

Unfortunately, the combination of ibus and XIM clients is buggy for some non-ASCII character inputs.

There have been frequent and persistent bugs around this combination as discussed in Red Hat Bugzilla – Bug 2013610.

The practical workaround is either "Don't to use XIM mechanism with the input method" or "Avoid entering non-ASCII characters".

Properly configured GTK and QT programs with im-config don't use XIM mechanism and are immune to these annoying bugs of XIM.

For terminal emulators, please use any modern ones which can get keyboard inputs via GTK or QT:

For emacs, please consider to use emacs-nox in modern terminal emulators or emacs-gtk. (I.e., please avoid emacs-lucid if ibus is activated. emacs-gtk bugs seem to be resolved.)

For programs such as gitk, please consider to avoid typing non-ASCII characters as the workaround.

Input method framework: Disabled case

If you don't need modern functionality of the input method framework such as ibus, you can make XIM clients talk directly to the X server configured with X keyboard Extension (XKB) by disabling ibus as:,

 $ im-config -n none

This workaround may not work on some desktop environments if they override im-config. Notably, GNOME may fall into this type.

Japanese 106/109 keyboard

TODO: Update this section for bookworm in testing (2022).

It's odd not to see "Generic 106-key PC" for "JIS-type keyboard without "Windows-key" and "Generic 109-key PC" for "JIS-type keyboard with "Windows-key" in Keyboard model of  dpkg-reconfigure keyboard-configuration dialog.

Some old page (2013-05-12) suggests to edit /etc/default/keyboard stanzas to:

XKBMODEL="jp106"
XKBLAYOUT="jp"

Some newer page (2019-07-12) suggests to use setlocale command.

Very old GNOME (currently not an issue @2022)

The keyboard layout was changed on Settings -> Region & Languages -> Input Sources. For releases older than Stretch (initially released @2018), these layouts include minority languages and dialects, as well as very specific configurations, and were hidden by default in the GUI for Stretch (during its testng?).

One can set it via CLI using dconf/gsettings by adding keys to /org/gnome/desktop/input-sources/sources.

The only way to make them visible is to enable the corresponding setting in gconf:

 $ gsettings set org.gnome.desktop.input-sources show-all-sources true

For more information on this issue see https://bugzilla.gnome.org/show_bug.cgi?id=682240.


CategoryPortal | CategoryHardware