-
-
Notifications
You must be signed in to change notification settings - Fork 24
FAQ (Frequently Asked Questions)
This Wiki page will list some common questions, issues and fixes/tweaks that may be necessary for different distros, desktops or devices (and are not yet handled by the Toshy installer or config file).
◊
How do I know Toshy is working correctly?
(or, It sort of works but sort of doesn't, what's going on?)
There are two levels to what the Toshy config does (just like Kinto, from which the base config file was taken). Level one is the shifting of some of the modifier keys. In most cases, even on an unsupported Wayland environment, the shifting of the modifier keys will work and some basic "global" shortcuts like cut/copy/paste (X/C/V) will appear to work, and you'll be able to open new tabs and close them in a browser with the expected Cmd key shortcuts. This can create a false impression that the whole thing is "working" when it actually isn't.
The second level of remapping is the application group/class-specific modmaps and keymaps (such as "in terminals"), and then the true app-specific keymaps for individual applications (such as "in Firefox"). These will either be working or not working.
One of the best simple tests, if you have Firefox installed, is if using the Cmd+comma shortcut (which opens preferences in many macOS applications) opens a new tab in Firefox, then rapidly types the string about:preferences, and opens the Firefox preferences. If this works, or even if it just gets through typing the "about:preferences" in the address bar, it's a clear indication that the app-specific keymaps are working. Because this is only supposed to happen when a Firefox web browser window class is detected.
Tip
If you wind up with a string like about;preferences (note the semicolon instead of colon) and it does a google search each time instead of opening the Firefox preferences, you're having a problem with modifier timing in the output of macros from the keymapper. You'll need to look for the FAQ entry on changing the delays in the throttle_delays API in the beginning of the config file, and set longer delays to make that go away. Wayland environments and virtual machines will generally require longer delays to avoid this issue. I set some default delay values to try to keep this from happening, so if it still happens to you with those default values in place, submit an issue.
If you think app-specific remaps are working in general, but for some reason they aren't working in a specific app, the app's "class" may be different than expected by the config file. Try to identify it, and let us know what the "class" and "name" attributes are.
UPDATE:
There are now a couple of "diagnostic" functions in the config file that should reveal the window attributes (and the keyboard device name and several other things) more easily in both X11/Xorg and Wayland environments, when you use one of these shortcuts:
Safe to do in any application window:
Shift+Opt+Cmd+I,I (double-tap the "I" key while holding the mods)
Alternative for apps that might use Shift+Opt+Cmd+I:
Shift+Opt+Cmd+H,H (double-tap the "H" key while holding the mods)
This should display a pop-up dialog box with useful info like the application class, window name/title, the name of the keyboard device, the keyboard type, environment info, and whether the focused app window is in any of the major app groups in the config file.
ONLY DO THE SHORTCUT BELOW IN A TEXT AREA OR TEXT EDITOR APPLICATION:
Shift+Opt+Cmd+T,T (double-tap the "T" key while holding the mods)
This shortcut will initiate a "macro" that will type out the same kind of information found in the pop-up dialog option, but also does a quick Unicode character test that should come out looking like this, on a single line:
Unicode and Shift Test: 🌹—€—‡—ÿ—‡ 12345 !@#$% |\ !!!!!!
Here's an example of the whole macro that will be typed out:
Class: 'org.gnome.TextEditor'
Title: 'Appl Class org gnome TextEditor (Draft) - Text Editor'
Keybd: 'AT Translated Set 2 keyboard'
Keyboard type: 'Windows'
Next test should come out on ONE LINE!
Unicode and Shift Test: 🌹—€—‡—ÿ—‡ 12345 !@#$% |\ !!!!!!
And here is what the output of the macro will look like if the Unicode entry shortcut (Shift+Ctrl+U) is not working, due to the system not using ibus (or possibly fcitx) as your input manager, or not being in a GTK-based app window:
Class: 'org.kde.kwrite'
Title: 'KWrite'
Keybd: 'AT Translated Set 2 keyboard'
Keyboard type: 'Windows'
Next test should come out on ONE LINE!
Unicode and Shift Test: 1f339
2014
20ac
2014
2021
2014
ff
2014
2021
12345 !@#$% |\ !!!!!!
Previous advice below the line still works too:
In X11/Xorg environments, run this in a terminal, then click with the "cross" mouse cursor on the window you're trying to identify:
xprop WM_CLASS _NET_WM_NAMEIn a Wayland environment where you know the app-specific remapping is otherwise working, run the Toshy manual config verbose debugging command, and then use a shortcut that will be remapped (like Shift+Cmd+Left_Brace from the "General GUI" keymap), while the keyboard focus is on the window that is not being recognized:
toshy-debugOr you can use this older, longer alias to do the same thing:
toshy-config-verbose-startYou should see some kind of output like this, which will display the class and name according to the Wayland window context provider, and which keymap has been triggered:
(DD) WM_CLASS: 'Xfce4-terminal' | WM_NAME: 'Terminal - testuser@mx: ~'
(DD) DEVICE: 'AT Translated Set 2 keyboard' | CAPS_LOCK: 'False' | NUM_LOCK: 'False'
(DD) ACTIVE KEYMAPS:
'User hardware keys', 'Wordwise - not vscode', 'GenTerms overrides: Xfce4',
'General Terminals', 'GenGUI overrides: not Chromebook', 'GenGUI overrides:
… Xfce4', 'General GUI'
(DD) COMBO: RCtrl-MINUS => Ctrl-MINUS in KMAP: 'General Terminals'In this example the Xfce4-terminal application is being correctly recognized as a terminal (in KMAP: 'General Terminals'), and the equivalent of Cmd+Minus is remapped onto Ctrl+Minus.
If this terminal was not being recognized as a terminal, it would probably show in KMAP: 'General GUI' instead.
To get back to using the background Toshy services if you've run any of the "manual" commands, just use the (Re)Start Toshy Services option from the Toshy tray icon menu, or in the Toshy Preferences GUI app, or just run this command in the terminal to restart the systemd user services:
toshy-services-restart◊
IMPORTANT UPDATE FOR THIS FAQ ENTRY:
The current keymapper fork (xwaykeyz) has been modified in v1.1.0 or later to pass-through "repeated" keystrokes without attempting to do any transforming or evaluation of modmap/keymap conditional expressions. This drastically reduces CPU usage while holding down any key such as Space, Delete/Backspace or any normal non-modifier key, to allow it to repeat an action in an app window. (Holding down modifier keys even before this change never seemed to cause much of an issue.)
This modification should generally keep the keymapper from falling behind or "buffering" keystrokes when a key is repeating. So modifying the keyboard repeat rate to compensate, as outlined in the older portion of this FAQ entry below, should be far less relevant.
To get this modification of the keymapper it is necessary to reinstall Toshy, either from an existing zip/folder that you've downloaded recently, or from a newly downloaded zip. The Toshy installer will clone a new copy of the keymapper from its GitHub repo. Your chosen preference settings and customizations of the config file should be retained after the reinstallation of Toshy, as long as you kept your edits of the config file inside the marked "slices".
This passing through of "repeated" keystrokes has not been observed to cause any issue with remapping shortcut combos correctly, even if/when a whole combo is held down (only the last key encountered actually "repeats" in such cases anyway). There is a theoretical drawback of doing this where a single remapped key would suddenly return to its original state if it was held, but that would not be a recommended usage of the keymapper anyway (trying to remap a non-modifier key in a situation where you would be holding the remapped key down to repeat it). The keymapper is not fast enough to handle that kind of thing easily, especially with a complex config file with lots of conditional expressions, such as the config file used by Toshy. Combos like Cmd+Tab or Cmd+Grave don't seem to be allowed to repeat, so I've seen little practical issue with this solution to the buffering and CPU usage problem.
[UPDATE: Actually it messes with shortcuts like the emacs movement shortcuts. If you want them be able to repeat, see note below on disabling the ignoring of repeating keys.]
To check that you have the version of the keymapper that is doing this bypassing of repeated keystrokes, you can open the services log from the tray icon menu item, or with toshy-services-log in a terminal, and use the tray icon menu or toshy-services-restart in another terminal tab, and you should see a line showing the xwaykeyz version as the services restart. Or, use btop in the terminal and filter (with the F key) for toshy, then hold down a key in some kind of text app while watching the CPU usage of the xwaykeyz process. There may be a short spike initially, but during the holding of the repeating key the CPU usage of the keymapper should be close to zero.
If you do run into an issue with this modification of the keymapper, there is a way to disable the bypass using a new API call from the config file. You may even find the API call in your config file (in the keymapper_api slice, if you first installed Toshy recently), or you may not (if you installed Toshy before any of this was implemented in the keymapper).
###########################################################
# If you need to use something like the wordwise 'emacs'
# style shortcuts, and want them to be repeatable, use
# the API call below to stop the keymapper from ignoring
# "repeat" key events. This will use a bit more CPU while
# holding any key down, especially while holding a key combo
# that is getting remapped onto something else in the config.
###########################################################
# ignore_repeating_keys(False)Just uncomment that last line to pass False to the API and stop the keymapper from ignoring the repeats. Unless you are doing something like gaming where you need to hold keys down while the game also stresses the CPU, you won't normally notice any real performance difference when going back to remapping repeats. But the keymapper will use a measurable amount of additional CPU while repeating a remapped combo.
OLDER INFO FOR THIS FAQ ENTRY:
If you have an issue with keys that seem to continue repeating for too long after you release the key, the issue is probably that your keyboard repeat rate is set too high. This can cause repeating keystrokes to "buffer" somehow and lead to deleting way too many characters or similar issues. Slowing down the repeat rate should keep this from happening. How you do this kind of depends on the distro and desktop environment.
Some DEs have a nice control panel interface for setting the repeat rate, in a way that will work with both X11/Xorg and Wayland. Many how-tos online mention using xset, but I believe this only works in X11/Xorg environments. On my Fedora system, the kbdrate command seems to work, even in Wayland. If you're using GNOME, there is a control panel for this at Universal Access > Typing that will let you disable repeating keys or set the repeat rate (and delay).
A good repeat rate that should keep the input system from overwhelming the keymapper with repeating keystrokes is around 10 to 20 characters per second (cps).
◊
If you're having any issues with a laptop apparently not disabling the trackpad while typing, but only while using Toshy, that may be happening because the system is not recognizing the virtual keyboard the keymapper creates as an internal keyboard device. You can try the solution in the Wiki article at the link below, provided by a Toshy user who figured out how to mark the virtual keyboard as an internal device with libinput, which should fix the problem.
https://github.com/RedBearAK/toshy/wiki/How-to-enable-palm-rejection-on-virtual-keyboard
◊
UPDATE: This shouldn't be a problem in the future
Through extraordinary effort, some updates have been merged that try very hard to retain customizations you may have made to the Toshy config file, and preferences that have been saved to an sqlite3 database file in your config folder. If you installed Toshy before today (June 5th, 2023), you will need to do one more reinstall from a freshly downloaded zip or clone of the repo. After that reinstall, your config file will contain the markers necessary for the Toshy installer to grab any changes you've made within those special marked sections of the file, and merge them into any new version of the config file as it continues to evolve. This will probably not always work over time, depending on what you did, and what changes need to be made to the default config file. If it doesn't work, you'll just have to merge your customizations the old way, by hand. Hopefully that won't happen often. The same full backups of the entire config folder will happen, just like before. I'll leave the rest of this FAQ entry here for a while. It still has relevant info about the backups.
If you edit outside the "slice marks" that enable the merging process to work, your changes would still be overwritten every time you run the installer. If you think the config file needs a new location for an editable section, submit an issue about it.
Right now, the sections marked for attempted retention through upgrades/reinstalls are:
-
keymapper_api- Allows customized API function settings for the keymapper:
- Diagnostic dump key (use any unused single key)
- Emergency eject key (use any unused single key)
- Multipurpose timeout
- Suspend timeout
- Throttle delays (to fix macros/Unicode/combos)
- Add a new modifier here if needed (with
add_modifier())
- Allows customized API function settings for the keymapper:
-
env_overrides- Allows persistently overriding environment info detections
- If you have to do this, the
envmodule should be updated
-
kbtype_override- Allows fixing a keyboard device type, if misidentified
- (Submit an issue if you have this problem!)
-
user_custom_lists- Good place to add custom or manipulate existing lists
-
user_custom_functions- Add new functions here to keep them near other functions
-
exclude_kpad_devs- Allows excluding some devices from the keypad modmaps
-
user_custom_modmaps- Add your own custom modmaps here
-
user_apps- Good place for user hardware keys, or special apps
- Also a good spot to override remaps you have issues with
- For more info about that, see Wiki page at the link below:
https://github.com/RedBearAK/toshy/wiki/How-to-(persistently)-change-the-Cmd-Space-remap
Original, now slightly obsolete text of this FAQ entry continues below:
Short version: Don't worry, it's in a backup folder, and you can easily merge your changes back into the new config.
Long version: Because the config file is continually evolving, and the config file itself is really a "program" written in Python that is literally executed as Python code by the keymapper (xwaykeyz) at runtime, it's a bit difficult to retain the changes you've made and be sure that the new version of the config file will load without some sort of error.
So the best solution I've come up with so far is to have the installer make a backup of your whole ~/.config/toshy folder to a timestamped folder in ~/.config/toshy_config_backups.
Note
If you run the Toshy installer multiple times you may find that the most recent dated "backup" is just a backup of a fresh Toshy config folder, as it will make a new backup whenever a toshy folder is found in ~/.config. In this case, the folder with your custom changes may be in an older timestamped backup folder. But this would only be something important if for some reason the merge of your custom changes failed.
The backup folders are typically less than 1 MB in size, as the Python virtual environment folder inside (~65 MB in size) is not copied. So they should never take up too much space even if you run the installer multiple times on the same system.
Using some software like Visual Studio Code, it is possible to compare the old and new config files in a "diff" sort of view and quickly see the differences. This can make it very easy to merge your custom changes back into the new config file with a few clicks. Then all you need to do is save the new config and restart the Toshy services or config script.
If you keep your modifications within the keymapper API functions slice at the very beginning of the config file, or the "User Apps" marked section around the middle of the config file (or some other marked slice), it should be pretty easy to merge your customizations back whenever you update Toshy or install on a new machine. The "User Apps" section is designed to be a good place in the config to put some customizations like making the brightness and volume keys on a laptop function row work correctly for your specific machine.
I will be trying to work on doing a more automatic copying/merging of existing user settings into a new config file.
There is an include() function in xwaykeyz/keyszer that theoretically would allow separate files to be part of the config, but due to the dynamic nature of the config file, and how it gets loaded by the keymapper, I had a lot of issues trying to use that method to solve this problem.
◊
Sometimes, mostly with keyboards that are not made by Apple but are made for use primarily with Macs, the keyboard will get misidentified as the incorrect type, so the virtualized Option/Alt and Command modifiers will seem to be in the "wrong" place. Follow the procedures below to fix that. There's a temporary fix (in the tray icon menu) and then a permanent fix (in the config file). Should only take a couple of minutes to deal with the issue.
For a switchable "universal" keyboard with both Mac and Windows modes, see the next FAQ entry for my recommendation on that.
Note
If you have this problem, please submit an issue report about it. In some cases the device name can be added to the default Toshy config so that it will work correctly for all future installs.
The Toshy tray icon menu should have a submenu labeled "Keyboard Type", where you can choose to change the setting from the default "Auto-Adapt" option to one of the available static keyboard types, overriding the automatic detection of keyboard type. This will apply to all devices and completely disable Toshy's ability to adapt to different keyboard types on-the-fly. This override is only meant as a temporary convenience for getting the keyboard modifiers to work correctly while you perform the main custom override (see below) for the specific device that is being misidentified.
Use the verbose manual config debugging command below, and look for lines with KBTYPE: to see your keyboard device name, as seen by the keymapper and the function that tries to identify the keyboard type. You can also find it in the list output from the terminal command toshy-devices.
toshy-debug
Older installs of Toshy may not have that command, but will have the equivalent alias:
toshy-config-verbose-start
You can then take the device name and add it to this Python "dictionary" structure. You will find this within a set of special markers in the config file that will ensure the change will get retained when re-installing or upgrading Toshy:
keyboards_UserCustom_dct = {
# Add your keyboard device here if its type is misidentified by isKBtype() function
# Valid types to map device to: Apple, Windows, IBM, Chromebook
# Example:
'My Keyboard Device Name': 'Apple',
}This will cause that specific keyboard device to be treated as the type you placed after the colon.
◊
I'm going to recommend that such keyboards be placed in the "Windows" mode. Most such keyboards won't be automatically identified as an "Apple" keyboard by Toshy (mostly because the device name won't contain "Apple") so things will probably work best if you just leave it in "Windows" mode and let Toshy deal with remapping the modifiers.
If that doesn't work out well, you'll need to add it to the custom dictionary described in the FAQ entry above to force the device to be identified as an "Apple" keyboard type, and try to use it in the Mac-compatibility mode.
◊
If you don't have ~/.local/bin/ in your PATH, or you answered n when prompted during install to add it to the PATH, you will have to add it to the PATH yourself, or re-run the Toshy installer, or just run this command:
~/.config/toshy/scripts/toshy-bincommands-setup.shAlternately, if you're trying to see the commands immediately after running the installer, you may need to run one of the following commands:
hash -ror...
source ~/.profileor...
. ~/.profile(The dot and space at the beginning is the equivalent of the source command.)
The installer no longer relies on shell RC files to add ~/.local/bin/ to the user's PATH.
◊
The keymapper is pretty good, but there can be an issue with [modifier key] + [tap or click], depending on the type of pointing device you're using, and whether the keymapper automatically "grabs" it at startup.
The keymapper uses a technique that "suspends" modifier key presses briefly (default is 1 second) to try and keep certain applications from seeing the original (pre-modmapped) physical modifier key press event, and performing some unwanted action. Notable apps that have issues with doing the wrong thing just from seeing a modifier key press are Visual Studio Code (and its more Open Source variants VSCodium and Code - OSS) and the Firefox web browser. They will frequently focus or open items on the menu bar then they see the Option/Alt key in any way.
If the modifier key press is combined with a non-modifier key, the suspend timeout is immediately broken, and the app will see the combo. The suspend timeout is only in effect as long as the modifier is by itself, as happens in a Mod+click situation.
If the suspend timeout scheme is not working for you, you may need to reduce the timeout length to zero or 0.1 seconds in order for Mod+click operations (Shift+Cmd+click, Cmd+click, Shift+click, Alt+click, anything like that) to work as you would expect.
Your config file is located here:
~/.config/toshy/toshy_config.pyTip
The tilde "~" in a path like this is always short for "/home/yourusername". Note that .config is a so-called "hidden" folder that will not show up in your file manager unless you enable the setting (usually found in the right-click menu) to show hidden files that start with a "dot" character. If Toshy is working and enabled, the shortcut physically equivalent to Shift+Cmd+Dot should reveal or hide those hidden files in most Linux file managers. Most such hidden files and directories will appear in the root of your home folder. The Toshy tray icon menu provides a menu item that should normally be a quick way to open the Toshy config folder where the config file resides, so you shouldn't need to worry about any of this if the tray icon is working.
Note
Pay no attention to the similarly named files in the default-toshy-config sub-folder, unless you have a severely broken config and can't figure out how to fix it, in which case copy the toshy_config.py file from that sub-folder and replace the one in the main folder. The "barebones" version of the file is only if you used --barebones-config during the install.
To change the suspend timeout, look for this API function near the top of your config file:
timeouts(
multipurpose = 1, # default: 1 sec
suspend = 1, # default: 1 sec, try 0.1 sec for touchpads
)Save the change to the config file and then restart Toshy from the tray icon, or with toshy-services-restart in a terminal.
If you do need to disable or reduce the suspend timer because of the touchpad issue, it will become more important to implement the fixes in the next FAQ entry for VSCode and Firefox, to keep them from focusing the menu bar every time you hit Option/Alt.
◊
For Firefox, the fix is relatively simple: Get to the advanced config settings by entering about:config into the URL/address bar. Accept the warning, and search for:
ui.key.menuAccessKeyFocusesDouble-click the item to change it from "true" to "false", and the Option/Alt key will stop focusing the menu bar.
Tip
The Zotero research app is based on Firefox and has a "Config Editor" button in its Advanced settings (scroll down to see it). This opens up a Firefox window, and the same fix from above with menuAccessKeyFocuses will prevent the Alt key from leaving the focus on the menu when it is released.
For VSCode/VSCodium/Code-OSS, use Cmd+Shift+P to open the command palette, enter open user settings json to open the settings JSON file where you need to place these lines:
"window.titleBarStyle": "custom",
"window.enableMenuBarMnemonics": false,
"window.customMenuBarAltFocus": false,If there is nothing else in your user settings JSON file, it would need to have enclosing curly braces, like this:
{
"window.titleBarStyle": "custom",
"window.enableMenuBarMnemonics": false,
"window.customMenuBarAltFocus": false
}And the last line in every section of a JSON formatted file can't have a comma at the end, or there will be an error.
You may be prompted to restart the app after saving this particular set of lines, and it will change how the VSCode window looks, with a combined menu/titlebar. The Option/Alt key will no longer focus the menu bar.
Tip
The Linux version of Slack is also an Eletron app like VSCode, but since there is no way to edit the advanced features or shortcuts like we can in VSCode variants, a different kind of solution needed to be invented to fix menu focus stealing.
◊
To fix how some shortcuts work in the embedded terminal pane inside Visual Studio Code and variants like VSCodium and "Code - OSS", see this Wiki page:
https://github.com/RedBearAK/toshy/wiki/Embedded-terminal-in-VSCode-and-variants
◊
Sometimes, especially in virtual machines (but also on some bare metal installs) there is a problem in Linux with the "timing" of modifier key presses, leading to failures of some shortcut combos.
The Option-key special characters in particular rely on a shortcut combo (Shift+Ctrl+U), and if that doesn't work the special character can't be created. And the mimicry of the highlighting of "dead keys" characters will probably also fail, since it does stuff like Shift+Left.
This will also usually affect "macros" where you attempt to get the keymapper to type out multiple characters or strings or perform multiple shortcut combos when you use a shortcut. They may fail somewhere in the middle, or a shifted character will come out as a non-shifted character.
A solution (well, a "mitigation") for this has been implemented in the keymapper, and the API function is already in the Toshy config file. Injecting a short delay before and after the "normal" key press (to make sure that the modifier press and release are seen as happening with the correct timing) will usually solve the issue.
Look for this code early in the Toshy config file:
throttle_delays(
key_pre_delay_ms = 12, # default: 0 ms, range: 0-150 ms, suggested: 1-50 ms
key_post_delay_ms = 18, # default: 0 ms, range: 0-150 ms, suggested: 1-100 ms
)For a bare metal install, a few milliseconds is usually sufficient to make infrequent glitches go away. Sometimes even as little as 1 ms, but often 2-4 ms for both delays is a good value to start with. For operating inside a virtual machine it may be necessary to use much higher values like 50 ms (pre) and 70 ms (post) to get completely reliable behavior. With the right value the reliablity can be so close to 100% that it becomes impractical to find the failure in testing.
Update for Wayland+GNOME:
Note
I've decided to have values of 12/18 in the config by default, since even on bare metal installs there are often strange problems if there isn't a small delay. This is especially true on some Wayland environments, where the keymapper must rely on talking to a shell extension to get the window info. I don't think this is quite as fast as using Xlib in X11/Xorg sessions, so many shortcuts are quite flaky without a bit of throttle delay.
Caution
A lengthy delay will of course cause macros to come out quite a bit more slowly as the delay gets longer. So really long macros will be potentially impractical inside a virtual machine, for instance. This is why the values are clamped to a maximum of 150 ms each. The keyboard will be unresponsive while a long macro is coming out. Currently there is no way to interrupt the macro in progress. Not a big deal when the delay is 1 ms per character, but a problem if the total delay between characters is 150 ms or more.
◊
See above for the fix using throttle_delays().
◊
KDE Plasma desktops don't generally use ibus (like GNOME desktops usually do by default), or fcitx as an input manager. So you may find that the Option-key special character Unicode shortcut of Shift+Ctrl+U will not do anything, and the Unicode address of the special character will appear on screen instead of the desired character. This is unfortunately apparently not a shortcut that is built into the Linux kernel input system in general.
The fix for this, if you want to use those characters in KDE apps, is to install ibus and use im-chooser (or some other method like the Virtual Keyboard control panel in KDE Settings) to choose ibus as the input manager. You may also be able to use fcitx as I have seen some references to it supporting the Shift+Ctrl+U shortcut, but I haven't tested it.
Otherwise, without a compatible input manager that responds to the Shift+Ctrl+U shortcut to enable Unicode character entry, the special characters will only work correctly in GTK-based applications, which seem to have the ibus response to that shortcut built into the GTK framework.
◊
For some reason, even when I am in GNOME, the Unicode character entry shortcut of Shift+Ctrl+U does not work in Sublime Text 3, so none of the Option-key special characters will work in that app. No idea why. Someone said that they couldn't replicate the problem in a build of Sublime Text 4, and that's all I know about it. No known workaround. (Other than moving to ST4.)
◊
As of right now the keymapper has a key definition file (a mapping of key symbols to key codes) that is only designed for standard US/English keyboard layouts/languages. And, the keymapper has no knowledge of the current keyboard layout/language, which is remarkably difficult to obtain even on X11/Xorg, and Wayland is worse. Due to these limitations there will be shortcut combos that will act like you are using a US QWERTY keyboard layout, even though you are using, for instance, French AZERTY or something else. If you attempt to use Cmd+A on such a layout, the result will be Cmd+Q as the keymapper still thinks the A key is a Q. So instead of "Select All" you'd perform "Close Window".
There is a solution to this, which is to find and modify the key.py file in the xwaykeyz package folder (which in the case of Toshy will now be somewhere in ~/.config/toshy/.venv/). But that would need to be done for every possible keyboard layout that is different from a US QWERTY layout.
Some international users choose to use a US layout simply because it is a bit easier to use for coding, so they will not run into this problem.
I'm still looking for a more general/flexible solution to this issue.
Also, closely related, the Option-key special character schemes that have been implemented are based only on two US keyboard layouts in macOS, the standard US layout and the "ABC Extended" layout (which is still a US layout, but with enhancements to the available special characters and diacritic "dead keys"). So the special character arrangement will have differences from what an international user of macOS might be used to. This, also, is not going to be a simple problem to solve completely.
◊
These are all different names for the same key code. The Linux kernal appears to primarily refer to the key as Meta, while some Linux desktops (notably GNOME) like to refer to the same key as the Super key. Meanwhile, it is the same key as the Windows key on PC keyboards (which may have an image of "Tux" the Linux penguin on custom Linux keyboards/laptops). And, to top everything off, the Apple keyboard Command key uses the same key code.
So, as far as the keymapper is concerned, using any of "Win", "Super", "Meta", or "Cmd" in the config file will result in the same key code. I will typically try to refer to it as "Meta" to match the Linux kernel documentation, but it depends on the circumstances. When referring to how it is used in GNOME I'll say "Super", for instance.
◊
Xubuntu (using Xfce desktop environment) appears to run a background app at startup called xcape that binds the Super/Meta/Win/Cmd key (all different names for the same key) to activate the Whisker Menu by itself. To deactivate this, open the "Session and Startup" control panel app, go to the "Application Autostart" tab, and uncheck the "Bind Super Key" item. That will stop the xcape command from running at startup. Until you log out or restart, there will still be the background xcape process binding the key, but that can be stopped with:
killall xcape◊
In Lubuntu, right-click on the hummingbird(?) menu icon on the toolbar at the bottom of the screen, and select Configure "Application Menu" to change the keybinding from Super_L (left Meta key) to Alt+F1. If Toshy is enabled, using either the physical equivalent of Cmd+Space or Option+F1 should work. if Toshy is disabled, just use the physical Alt+F1 keys. NB: The shortcut apparently needs to be set very quickly after clicking the button to change the shortcut. If it doesn't work the first time, just try again, until it says Alt+F1.
As an alternative, this shortcut can also be set through the GUI "Shortcuts Keys" control panel app. Search in the app for the "Show/hide main menu" shortcut. The UI in the app for setting shortcuts seems to have a longer delay (10 seconds), so it may be easier to set the shortcut.
◊
On Linux Mint (Cinnamon and MATE variants) they use a custom menu widget/applet that is set up to activate with the Meta/Super/Win/Cmd key. The shortcut for this is not exposed in the usual keyboard shortcuts control panels. Right-click on the menu applet icon and go to "Configure" or "Preferences" (make sure you're not opening the preferences for the entire panel, just the menu applet).
You will see a couple of things that vaguely look like buttons. You can click on the first one and set the shortcut to something like Ctrl+Esc. Click on the other button and hit Backspace and it will show "unassigned". This will disable the activation of the menu with the Meta/Super/Win/Cmd key.
Alternately, instead of disabling the secondary shortcut, you could set the secondary shortcut to Alt+Space (use the keys corresponding to the physical position of Option+Space on an Apple keyboard if Toshy is enabled), but you will have to track down the same shortcut in the regular keyboard shortcuts control panel (something like "Window menu"?) and disable it. If you do this, it will be possible to open the application menu with the same physical keys whether Toshy is enabled or disabled.
You may need to temporarily DISABLE Toshy (from the tray icon menu, or the GUI preferences app) if it is active, in order to successfully set the main shortcut to Ctrl+Esc. Then re-enable Toshy. Or, press the equivalent on your keyboard of Cmd+Space when setting the shortcut, and what should appear as the new shortcut is Ctrl+Esc.
If Cinnamon is detected by the Toshy config, Cmd+Space will already be getting remapped onto Ctrl+Esc, so you should now be able to open the application menu with Cmd+Space, if you assigned the suggested shortcut to it.
In MATE, the remap is set to Alt+Space, which is a shortcut that doesn't seem to intefere with any existing shortcut. To set this as the shortcut for the menu applet in MATE, Toshy must be disabled while setting the shortcut, then re-enabled afterward.
In the Xfce variant of Mint, they use the Whisker Menu applet, and the shortcut (Super_L) is exposed in Keyboard >> Application Shortcuts. The Toshy config remap for Xfce is set to Super+Space, to avoid conflicts with other Xfce functions. So if you set the shortcut for the Whisker Menu to Super+Space, it should start working when you use Cmd+Space. It shouldn't be necessary to disable Toshy, but the physical keys to set the shortcut to Super+Space with Toshy enabled will be physical Ctrl+Space.
◊
By default GNOME desktops seem to want to use the Meta/Super/Win/Cmd key to open the "overview". This is not a shortcut that is exposed in the usual Settings >> Keyboard control panel. The Toshy installer will disable the keybinding if GNOME is detected, since it's weird/unexpected in macOS for a modifier key to perform an action by itself.
Here are the commands to disable and re-enable the overlay-key keybinding:
Disable:
gsettings set org.gnome.mutter overlay-key ''Enable/Re-enable (lack of argument resets to Super key):
gsettings reset org.gnome.mutter overlay-key◊
GNOME desktops have the ability to either do task-switching like Windows (switch between all open windows individually) or like macOS (switch between "applications" as groups of windows). Except where an extension is interfering with this ability, like the COSMIC desktop extension on Pop!_OS. Depending on the Linux distro, Alt+Tab may be assigned to "Switch windows" or to "Switch applications".
If you want to task-switch more like macOS, set the "Switch applications" shortcut in the GNOME Keyboard settings control panel to be the one assigned Alt+Tab, and set the "Switch windows of an application" to be Alt+Grave (the "`" backtick/Grave character, above the Tab key).
Note that this will also change the appearance and function of the task-switcher dialog that appears when you use the corresponding shortcut. The "Switch applications" shortcut is like the macOS task-switcher, it shows one large application icon for each group of windows belonging to the same "application". The "Switch windows" shortcut will show a task-switcher dialog that has a preview icon for every window open on the current workspace, similar to Windows and Linux desktop environments like KDE Plasma. The "large icons" task-switcher tends to have far fewer items and be easier to navigate visually. Just like on macOS, the equivalent of Cmd+Grave can be used to switch windows of the same application.
Which task-switching style works for you is down to personal preference, and how well you like the macOS style of task-switching with Cmd+Tab.
◊
The situation differs now, between Plasma 5, Plasma 6 (up to 6.1), and then Plasma 6.1 and later. As part of the Plasma 6.1 update, the ModifierOnlyShortcuts were finally merged into the rest of the shortcuts settings, and are now visible just like any other shortcut in the kglobalshortcutsrc file and can be seen and changed in the Shortcuts settings panel in System Settings.
So if you are in Plasma 6.1 (or later), you can manually enable or disable the "Meta" modifier-only shortcut, which is one of two default shortcuts attached to the "Activate Application Launcher" shortcut. Which you can search for using anything in the name, or by looking in the "System Services" group under "plasmashell". The app launcher shortcut should be right at the top, with default shortcuts of Meta and Alt+F1. Uncheck the box next to Meta and click "Apply". That should immediately disable the modifier-only shortcut, and stop it from interfering with some of Toshy's remapped shortcuts involving the Meta key.
I will update the Toshy installer to try to once again handle this automatically during install. The update will just disable the Meta key assignment, while leaving it there to be selected and re-enabled manually if the user wishes to.
If you are in Plasma 5, the older info below the line after this paragraph should still be relevant. If you are in limbo in Plasma 6.0.0 up to just before 6.1, substitute kwriteconfig6 in place of kwriteconfig5, and the instructions should otherwise be the same. But the fix below is now ignored in Plasma 6.1 and newer releases.
(DEPRECATED IN PLASMA 6.1 OR LATER)
KDE Plasma desktops tend to have the Meta/Super/Win/Cmd key bound to open the application launcher. Like the other desktop environments that bind the Meta key to do something by itself, this appears to be an alien concept as far as the regular keyboard shortcut control panel is concerned. You won't find it there.
To disable this secret Meta-only binding, use these commands (on KDE Plasma 5):
kwriteconfig5 --file kwinrc --group ModifierOnlyShortcuts --key Meta ''
qdbus org.kde.KWin /KWin reconfigureTo restore the Meta-only key binding, use these commands:
kwriteconfig5 --file kwinrc --group ModifierOnlyShortcuts --key Meta --delete
qdbus org.kde.KWin /KWin reconfigureMore info about this:
https://userbase.kde.org/Plasma/Tips#Windows.2FMeta_Key
◊
Something strange is happening in Manjaro KDE and Arcolinux KDE desktops with the shortcut to open the application menu/launcher applet. In the primary shortcut settings control panel, there is a shortcut of Alt+F1 set, which should work with the Toshy config. But the Alt+F1 shortcut doesn't even work with Toshy disabled. If you right-click on the menu icon you can open the applet settings dialog and set the Alt+F1 shortcut in its preferences (choose to reassign it) and then hit Apply, and it will start working with Cmd+Space when Toshy is enabled. And also it will now work even when Toshy is disabled. There are other identically named shortcut settings in the main KDE control panel for shortcuts, but they seem to want to open krunner, the search/launcher bar that pops out from the top of the screen.
◊
UPDATE:
The info in this FAQ entry is obsolete as of March 21, 2024. A new tray icon menu item will take care of enabling/disabling the tray icon autostart setting. Any Toshy install performed from an older state of the repo will not have this feature, but you can download a new zip and reinstall to get it. After the tray icon autostart is disabled, the Toshy installer will no longer (re)start the tray icon at the end of the install. The tray icon app can still be started manually from your app menu or launcher.
The Toshy tray icon indicator app loads at login through a .desktop file placed in the standard XDG autostart folder location: ~/.config/autostart/. The Toshy setup script places a symlink to ~/.local/share/applications/Toshy_Tray.desktop in that folder, and most Linux desktop environments will automatically run anything in that folder when you log in. (The original Toshy_Tray.desktop in ~/.local/share/applications/ is what makes the "Toshy Tray Icon" app show up in your app menu or app launcher. You don't want to remove that unless you no longer want to see the app in your app menu at all.)
To stop the tray icon indicator from appearing every time you log in, just find a way to remove the Toshy_Tray.desktop file from ~/.config/autostart/. You can do it in the terminal:
rm ~/.config/autostart/Toshy_Tray.desktopOr you can use the GUI startup settings panel your Linux desktop environment might provide. Just remove the item that says something like "Toshy Tray".
I don't recommend not having the tray icon available. Not all functions are replicated in the GUI "Toshy Preferences" app window, which doesn't have the keyboard type temporary override, the item to quickly open the config folder, and can't stop or (re)start the manual config option. When something is going wrong with the keymapper that somehow affects overall keyboard usage, the tray icon can be very helpful.
But if you are not having any problems with Toshy and don't have a habit of changing your config file, or you use the toshy-debug command in a terminal for testing config changes before restarting the background services, it should be fine to disable the tray icon.
◊
UPDATE:
The info in this FAQ entry is obsolete as of March 21, 2024. A new tray icon menu item will take care of enabling/disabling the tray icon autostart setting. Any Toshy install performed from an older state of the repo will not have this feature, but you can download a new zip and reinstall to get it. After the tray icon autostart is disabled, the Toshy installer will no longer (re)start the tray icon at the end of the install. The tray icon app can still be started manually from your app menu or launcher.
If you disabled autostarting the Toshy tray icon indicator app at login with the instructions above and want to get it back, this should work:
ln -s ~/.local/share/applications/Toshy_Tray.desktop ~/.config/autostart/Toshy_Tray.desktopThis will load the tray icon automatically whenever you log in to your desktop, just like what happens after you run the Toshy setup script. The tray icon app can be manually started from your app menu or app launcher (without needing to log out) using the "Toshy Tray Icon" app you should find in a "Utilities" or "Accessories" sub-menu (depends on the type of app menu your desktop environment is using). Or just search in the app launcher for "tray" and it will often be the only thing that appears.
◊
This is a problem on openSUSE Leap 15.x, possibly on other distros where a regular user doesn't automatically have access to the output from journalctl without using sudo. Toshy doesn't need to show any "system" output, because all of the Toshy services are "user" services. But the user on some distros like Leap will still need to be added to the systemd-journal group in order to see any output when trying to use the toshy-services-log command in the terminal, or when trying to use the tray icon menu item "Show Services Log" (which just runs that command in a new terminal window).
Personally I think this is a configuration error in Leap, but I'm not a distro maintainer, so maybe there is a good reason for users to be... restricted from seeing output from their own user service units... ? No, doesn't really make much sense.
To fix this, use the following command (change "testuser" to your actual user name) to add your user to the systemd-journal group, and then log out, wait 10 seconds (to allow user services like Toshy to be completely stopped), and log back in.
sudo usermod -aG systemd-journal testuserUsing usermod -aG here will prevent the command from removing all other groups from the user. Very important!
This is not a problem on most tested distros, and it's a pretty easy fix and not essential for the functioning of the project, so I may not add this solution to the Toshy installer script unless the same problem pops up on some other distros.
The message about not being in the systemd-journal group also appears on Tumbleweed, but is only superficial in that case since the user is not actually restricted from seeing the output from Toshy's "user" services. The same command can be run to get rid of the superficial message.
UPDATE: I've run into the same kind of thing on CentOS Stream 8, so it probably also happens on RHEL and its clones.
◊
If you open the config folder from the tray icon menu item "Open Config Folder" and it opens in a window of a file manager that isn't the main file manager for the desktop environment you are logged into, you can fix it with xdg-mime. The tray icon menu item uses xdg-open to open the folder, so it will use the app set as the "default" for the file type inode/directory. Here's how to check the current default for that mimetype:
xdg-mime query default inode/directoryThen if you want to change the default file manager used by xdg-open you can do something like this:
xdg-mime default org.gnome.Nautilus.desktop inode/directoryIf you don't know the exact desktop file just start typing what you think the name is and hit Tab. If you're lucky the Tab completion in the terminal will reveal similar app names.
This problem should only crop up on a system where multiple file managers or multiple entire desktop environments (like GNOME and KDE Plasma) have been installed at the same time. Switching the default for xdg-open may not completely solve the problem in the case of multiple DEs, it might just use the incorrect file manager on the other DE.
◊
Some examples involving Nautilus (default for GNOME) and Dolphin (default for KDE Plasma) are in this new Wiki article:
https://github.com/RedBearAK/toshy/wiki/How-to-make-file-managers-open-new-windows-in-home
◊
If you have a question that isn't answered here, submit an issue. I'll add more items to the FAQ as they become "commonly asked". Or in some cases I'll add a new Wiki page.
§