Toshy

Description

Toshy is a config file for the xwaykeyz Python-based keymapper for Linux along with some commands and apps to more conveniently interact with and manage the keymapper. The purpose of Toshy is to match, as closely as possible, the behavior of keyboard shortcuts in macOS when working on similar applications in Linux.

References

toshy

Setup

Description

This details the installation steps for Toshy.

References

How to Install

Prerequisites

Important

This part of the guide assumes that you are using the KDE Plasma desktop environment.

For Toshy to work as intended post-install, your Plasma system must be using the native, default set of shortcuts and keybindings.

If you have modified the keybindings of certain applications or actions on your desktop, set them back to the default:
1. Launch the System Settings application.
2. Under the Input & Output section, select the Keyboard menu item.
3. In the Keyboard page, select the Shortcuts tab.
4. In the Shortcuts page, click the Defaults button found at the bottom left.
5. Click the Apply button.
For Toshy to install successfully, update (and reboot) your system beforehand.

Steps

Clone the Toshy Git repository to the home directory:

git clone https://github.com/RedBearAK/toshy.git ~/toshy

Enter the cloned toshy repository:
```
cd ~/toshy
```
Install Toshy:
```
./setup_toshy.py install
```
Reboot the system.

Configuration

Description

This details the process of configuring Toshy and includes some recommended configuration options for an improved experience.

References

Logitech MX Keys Mini F7 function changes when Toshy is enabled
Mod+clicking blocked by keymapper Suspend Timeout

Steps

Update the Toshy configuration supplied from the installation with the changes you wish to make:
```
nano ~/.config/toshy/toshy_config.py
```
[!TIP]
Should you need it, a backup of the default config file can be found at ~/.config/toshy/default-toshy-config/toshy_config.py
Save any changes made to the file.
Restart the Toshy services either graphically or through the terminal:
- Graphical method:
  - Click the Toshy Status Indicator icon in the System Tray.
  - Select the Re/Start Toshy Services menu item.
- Alternatively, restart each of the following services using the terminal:
  - toshy-config.service
  - toshy-session-monitor.service
  - toshy-kde-dbus.service

Modifier and Click Combination

If Modifier + Click (i.e. Cmd + Click) isn't working reliably, try and update the timeout length:

In the Toshy config file, search for the keymapper_api slice.

Based on the default timeouts value:

timeouts(
    multipurpose        = 1,        # default: 1 sec
    suspend             = 1,        # default: 1 sec, try 0.1 sec for touchpads/trackpads
)

Update the suspend value to a lower value such as 0.1 for touchpads/trackpads or 0:

suspend             = 0.1,        # default: 1 sec, try 0.1 sec for touchpads/trackpads

Task Switcher

Important

This part of the guide assumes that you are using the KDE Plasma desktop environment.

To mimic a more macOS-like experience while switching apps using the Task Switcher, add the following configuration:

In the Toshy config file, search for the user_apps slice.

Within the start and end of the user_apps slice, add the following:

if DESKTOP_ENV == 'kde':
    keymap("User overrides: KDE Task Switcher", {
        C("RC-Grave"):              C("Alt-Shift-Tab"),             # Switch apps in reverse order
    }, when = lambda ctx:
        cnfg.screen_has_focus and
        matchProps(not_clas=remoteStr)(ctx)
    )

In this example, these values are assumed:

Desktop environment: kde

[!TIP]
The if condition can be removed if you wish for the configuration to apply to all desktop environments.
Key (combination) to switch apps in reverse order: RC-Grave (Cmd + `)

Update these values accordingly.

Emoji Picker

If your keyboard has a dedicated F-Key (i.e. F7) that launches your system's emoji picker (i.e. KDE Emoji Selector) in stock mode (without Toshy running) and it's not working while using Toshy, add the following configuration:

Stop all Toshy services graphically or through the terminal, if they are running.
Run the evtest utility to identify what key is mapped to the particular F-Key:
```
evtest
```
When prompted with a list of available devices, identify the particular keyboard device you are using:
```
/dev/input/event3:      Logitech USB Receiver
```
In the above example, the device name is Logitech USB Receiver and the device event number is 3.

Enter the device event number:
```
3
```
When evtest is ready for testing, monitor the output and press only the F-Key that normally launches the emoji picker (i.e. F7) ONCE.

Take note of the key (combination) being sent from that one specific press.

Example evtest output:

Event: time 1723174507.132175, type 4 (EV_MSC), code 4 (MSC_SCAN), value 700e3
Event: time 1723174507.132175, type 1 (EV_KEY), code 125 (KEY_LEFTMETA), value 1
Event: time 1723174507.132175, -------------- SYN_REPORT ------------
Event: time 1723174507.139168, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70037
Event: time 1723174507.139168, type 1 (EV_KEY), code 52 (KEY_DOT), value 1
Event: time 1723174507.139168, -------------- SYN_REPORT ------------
Event: time 1723174507.237171, type 4 (EV_MSC), code 4 (MSC_SCAN), value 70037
Event: time 1723174507.237171, type 1 (EV_KEY), code 52 (KEY_DOT), value 0
Event: time 1723174507.237171, -------------- SYN_REPORT ------------
Event: time 1723174507.244169, type 4 (EV_MSC), code 4 (MSC_SCAN), value 700e3
Event: time 1723174507.244169, type 1 (EV_KEY), code 125 (KEY_LEFTMETA), value 0
Event: time 1723174507.244169, -------------- SYN_REPORT ------------

In this sample, the key combination responsible for launching the emoji picker is Super + ..

Restart all Toshy services graphically or through the terminal and run the evtest utility again.
When prompted with a list of available devices, locate the virtual keyboard device Toshy uses:
```
/dev/input/event20:     XWayKeyz (virtual) Keyboard
```
In the above example, the device name is XWayKeyz (virtual) Keyboard and the device event number is 20.

Enter the device event number:
```
20
```
When evtest is ready for testing, monitor the output and press only the same F-Key we had tested earlier ONCE.

Take note of the key (combination) being sent from that one specific press.

Example evtest output:

Event: time 1723174975.203438, type 1 (EV_KEY), code 56 (KEY_LEFTALT), value 1
Event: time 1723174975.203438, -------------- SYN_REPORT ------------
Event: time 1723174975.203451, type 1 (EV_KEY), code 52 (KEY_DOT), value 1
Event: time 1723174975.203451, -------------- SYN_REPORT ------------
^[.Event: time 1723174975.285092, type 1 (EV_KEY), code 52 (KEY_DOT), value 0
Event: time 1723174975.285092, -------------- SYN_REPORT ------------
Event: time 1723174975.292853, type 1 (EV_KEY), code 56 (KEY_LEFTALT), value 0
Event: time 1723174975.292853, -------------- SYN_REPORT ------------

In this sample, the key combination being sent by the F-Key while Toshy is running is Alt + ..

With the information gathered, we are now ready to update our Toshy config to help regain the F-Key's functionality.

In the Toshy config file, search for the user_apps slice.
Within the start and end of the user_apps slice, add the following:
```
if DESKTOP_ENV == 'kde':
    keymap("User overrides: Emoji Picker", {
        C("Alt-dot"):               C("Super-dot"),                 # Open emoji picker in Plasma
    }, when = matchProps(not_clas=remoteStr, devn="^Logitech USB Receiver$")
    )
```
In this example, these values are assumed:
- Desktop environment: kde
  
  [!TIP]
  The if condition can be removed if you wish for the configuration to apply to all desktop environments.
- Key (combination) being sent by the F-Key in Toshy mode: Alt-dot (Alt + .)
- Key (combination) being sent by the F-Key in stock mode: Super-dot (Super + .)
- Keyboard device name: Logitech USB Receiver
  
  [!TIP]
  The devn argument can be removed if you wish for the configuration to apply to all keyboard devices.
  
  [!TIP]
  If you would like this configuration to apply to multiple specific device names, update the devn argument like so: devn="^One Device Name$|^Alternate Device Name$".
Update these values according to your actual setup.

KDE Spectacle

Important

This part of the guide assumes that you are using the KDE Plasma desktop environment or the Spectacle screenshot utility.

To mimic a more macOS-like experience using the Spectacle screenshot utility, add the following configuration:

In the Toshy config file, search for the user_apps slice.

Within the start and end of the user_apps slice, add the following:

if DESKTOP_ENV == 'kde':
    keymap("User overrides: KDE Spectacle", {
        C("RC-Shift-Key_3"):        C("Shift-Print"),               # Take a screenshot immediately (kde)
        C("RC-Shift-Key_4"):        C("Super-Shift-Print"),         # Take a screenshot interactively (kde)
        C("RC-Shift-Key_5"):        C("Super-Print"),               # Take a screenshot of a window (kde)
    }, when = lambda ctx:
        cnfg.screen_has_focus and
        matchProps(not_clas=remoteStr)(ctx)
    )

In this example, these values are assumed:

Desktop environment: kde

[!TIP]
The if condition can be removed if you wish for the configuration to apply to all desktop environments.
Key (combination) to take a screenshot immediately: RC-Shift-Key_3 (Shift + Cmd + 3)
Key (combination) to take a screenshot interactively: RC-Shift-Key_4 (Shift + Cmd + 4)
Key (combination) to take a screenshot of a window: RC-Shift-Key_5 (Shift + Cmd + 5)

Update these values accordingly.

Spectacle Window Manager

Important

This part of the guide assumes that you are using the KDE Plasma desktop environment.

To mimic the desktop experience of using the popular third-party window management utility on macOS, Spectacle (or Rectangle), add the following configuration:

In the Toshy config file, search for the user_apps slice.

Within the start and end of the user_apps slice, add the following:

if DESKTOP_ENV == 'kde':
    keymap("User overrides: KDE Spectacle WM", {
        C("RC-Alt-Down"):           C("Super-Down"),                # Quick tile window to the bottom (kde)
        # C("RC-Ctrl-Shift-Left"):    C(""),                          # Quick tile window to the bottom left (kde)
        # C("RC-Ctrl-Shift-Right"):   C(""),                          # Quick tile window to the bottom right (kde)
        C("RC-Alt-Left"):           C("Super-Left"),                # Quick tile window to the left (kde)
        C("RC-Alt-Right"):          C("Super-Right"),               # Quick tile window to the right (kde)
        C("RC-Alt-Up"):             C("Super-Up"),                  # Quick tile window to the top (kde)
        # C("RC-Ctrl-Left"):          C(""),                          # Quick tile window to the top left (kde)
        # C("RC-Ctrl-Right"):         C(""),                          # Quick tile window to the top right (kde)
        # C("RC-Alt-C"):              C(""),                          # Move window to the center (kde)
        C("RC-Alt-F"):              C("Super-Page_Up"),             # Maximize window (kde)
    }, when = lambda ctx:
        cnfg.screen_has_focus and
        matchProps(not_clas=remoteStr)(ctx)
    )

In this example, these values are assumed:

Desktop environment: kde

[!TIP]
The if condition can be removed if you wish for the configuration to apply to all desktop environments.
Key (combination) to quick tile a window to the bottom: RC-Alt-Down (Cmd + Alt + Down)
Key (combination) to quick tile a window to the left: RC-Alt-Left (Cmd + Alt + Left)
Key (combination) to quick tile a window to the right: RC-Alt-Right (Cmd + Alt + Right)
Key (combination) to quick tile a window to the top: RC-Alt-Up (Cmd + Alt + Up)
Key (combination) to maximize a window: RC-Alt-F (Cmd + Alt + F)

Update these values accordingly.

Additional Workarounds

Description

This details some additional workarounds needed to fix certain unwanted side effects of using Toshy.

References

VSCode(s) and Firefox menu stealing focus when hitting Option/Alt

Firefox Menu Stealing Focus

By default, hitting the Alt or Opt key will cause Firefox to steal focus. This can be fixed with a simple configuration on Firefox:

Configure the ui.key.menuAccessKeyFocuses setting and toggle its value to false.

Thunderbird Menu Stealing Focus

By default, hitting the Alt or Opt key will cause Thunderbird to steal focus. This can be fixed with a simple configuration on Thunderbird:

Configure the ui.key.menuAccessKeyFocuses setting and toggle its value to false.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

toshy.md

toshy.md

Toshy

Description

Directory

References

Setup

Description

References

Prerequisites

Steps

Configuration

Description

References

Steps

Modifier and Click Combination

Task Switcher

Emoji Picker

KDE Spectacle

Spectacle Window Manager

Additional Workarounds

Description

References

Firefox Menu Stealing Focus

Thunderbird Menu Stealing Focus

Files

toshy.md

Latest commit

History

toshy.md

File metadata and controls

Toshy

Description

Directory

References

Setup

Description

References

Prerequisites

Steps

Configuration

Description

References

Steps

Modifier and Click Combination

Task Switcher

Emoji Picker

KDE Spectacle

Spectacle Window Manager

Additional Workarounds

Description

References

Firefox Menu Stealing Focus

Thunderbird Menu Stealing Focus