Skip to content

Commit

Permalink
Merge pull request #16 from grafov/sway-support
Browse files Browse the repository at this point in the history 
Rewrite docs
  • Loading branch information
@grafov
grafov authored Mar 25, 2023
2 parents 60e4a77 + 1aa23dd commit a96482a
Showing 1 changed file with 84 additions and 79 deletions.
163 changes: 84 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,105 +1,110 @@
What is it and why?
===================

This utility allows you switch keyboard groups in X Window in the most
ergonomic way (in my view :).
I think keys for switching keyboard layouts should be:

1. Dedicated.
2. Non modal.

If you are often switch keyboard layouts (it real use case
for those who speaking not only English) then dedicated keys are more easy
for typing than key combos. Old Soviet computers for example had
dedicated key RUS/LAT for switch between Latin and Cyrillic. Sadly
in modern English-oriented keyboards there are no dedicated keys
for switch layouts.

So if you need two layouts you need two keys each of them will select
only one layout. For example if you want to type Cyrillic you press switch
key dedicated for this layout. Other dedicated key switches keyboard to Latin.
You may press switcher keys many times but each key will still select its own
layout. Such non modal way minimizes number of mistakes and allow you to work
without visual indication of current layout.

After experiments with different control keys I found that most
comfortable for my fingers will use LShift/RShift. LShift dedicated
for first layout and RShift for second when they pressed as standalone
keys. But when you press Shift with other keys then it applied as
modifier key.

I not found out of the box solution how to setup X to use Shifts as
standalone keys. Also I used two keyboards in same time (notebok internal and USB plugged)
and was need to switch layouts on both of them. So I wrote this utility.

So `shift-shift` has features:

* LShift pressed standalone locks X to group1 layout
* RShift pressed standalone locks X to group2 layout
* Layout switched on all keyboards simultaneously

You need customize layout groups in your X to

Language layout switcher for Xorg and Wayland (Sway support) with
modifiers (Shift, Control and so on) as switcher keys.

This way allows to use the same key as a modifier and as a layout switcher without conflicts.

The utility implements two ideas:

1. You could use a key as a modifier when you HOLD it and as a key switcher when you TAP it.
2. Cyclic switching by a single key is a bad idea, better to use DEDICATED keys for each language group.

It maybe not true if you use a bunch of languages of same time but it
is true for the most use cases with 2-3 langs.

If you are often switch keyboard layouts (it real use case
for those who speaking not only English) then dedicated keys are more easy
for typing than key combos. Old Soviet computers for example had
dedicated key RUS/LAT for switch between Latin and Cyrillic.

cconfig or with `setxkbmap`.

About code
==========
Sadly in modern English-oriented keyboards there are no dedicated keys
for switching layouts. Modifier keys usually used only by holding with
other key. So it looks like a good compromise: you are still able to
use them for their original purposes but when you tapping them they
work as language layout switchers.

I used Go language as it allow to me write programs quickly. And it allow
easy to combine it with C code. Though whole program may be rewritten to C
but I lazy to do it as it already works as I need.
By default Left Shift swithches to group 1 and Right Shift to
group 2. You may change this behavior with command line options.
Up to 4 xkb groups supported.

I not well know programming for X so used simple and crude ways to do things.
Program use udev library and requires root privileges for reading `/dev/input/event*`.
If you know right way how to do it without root then let me advice please.
Also you could try to treat any devices as keyboards with `-match`
option. It allows to switch group simultaneously on an arbitrary
number of connected keyboards.

Install
=======

Binding of `evdev` for Go used so before build you need:

go get github.com/gvalkov/golang-evdev/evdev

Then as usual:
This is a Go program. You should need Go environment to build it from sources.

go build
go get github.com/grafov/shift-shift@latest

Of course you need Go environment installed for build.
And as program uses Xlib through cgo interface then you need `xlib-devel`
installed.
`xlib-devel` libs should be installed. Check your distro.

Usage
=====

$ sudo shift-shift -h
Usage of shift-shift:
-list=false: list all devices listened by evdev
-match="keyboard": string used to match keyboard device
-print=false: print pressed keys
-quiet=false: be silent

On start program find devices where name contains "keyboard" string. It assume there
are keyboard devices. You may customize this by set your own string with `-match` arg.
Got list of all input devices with `list` arg.

**Note:** you need root for operations with `/dev/input/*` so run it with `sudo` or similar tool.

For autostart run it somewhere after X started with your account. I use `~/.bash_profile` for
this.

sudo pidof shift-shift >/dev/null || sudo shift-shift -quiet >/dev/null &
```
$ shift-shift -h
Usage of shift-shift:
-1 string
key used for switching to 1st xkb group (default "LEFTSHIFT")
-2 string
key used for switching to 2nd xkb group (default "RIGHTSHIFT")
-3 string
key used for switching to 3rd xkb group
-4 string
key used for switching to 4th xkb group
-double-keystroke
require pressing the same key twice to switch the layout
-double-keystroke-timeout int
second keystroke timeout in milliseconds (default 500)
-list
list all devices that found by evdev (not only keyboards)
-list-sway
list all devices recognized by Sway (not only keyboards)
-match string
regexp used to match keyboard device (default "keyboard")
-print
print pressed keys for debug (verbose output)
-quiet
be silent
-scan-once
scan for keyboards only at startup (less power consumption)
-switcher string
select method of switching (possible values are "auto", "xkb", "sway") (default "auto")
```

On start the program tries to find devices where name contains "keyboard" string. The substring could be customized with `-match` option. [The syntax](https://pkg.go.dev/regexp/syntax) of regular expressions could be used. For example:
```
$ shift-shift -match "(?i)ergodox|ergohaven"
```

Check the list of evdev detected devices with:

```
$ shift-shift -list
```

**Wayland/Sway note.** In the same time `-match` option applied to the
list of Sway input devices. You could check them with:

```
$ shift-shift -list-sway
```

**Note:** you need setup proper access for reading `/dev/input/*`
devices. As a fallback try to run with `sudo` or similar tool.

Thanks
======

Thanks to people who contributed bugfixes and improvements for `shift-shift`.

Thanks to people who contributed bugreports and improvements for
`shift-shift`, especially to
[@kovetsiy](https://github.com/kovetskiy),
[@ArtemT](https://github.com/ArtemT),
[@seletskiy](https://github.com/seletskiy).

todo add ref to
https://github.com/nmukhachev/sway-xkb-switcher
Idea of Sway integration was inspired by Python code of
https://github.com/nmukhachev/sway-xkb-switcher project.

0 comments on commit a96482a

Please sign in to comment.