* Alternative settings for g910-gkeys

This document will explain how to setup g910-gkeys by limiting as much as possible the usage of a global config, the idea being to setup global mapping in a static manner, and let the user set the actions in his/her own environment.

** Preamble
~g910-gkeys~ allows different actions : ~typeout~, ~shortcut~ and ~run~. All of these actions will be performed on the process environment, that is ~root~. Also, these actions are *global*.
** g910-gkeys configuration file (/etc/g910-gkeys/config.json)
The configuration chosen will ba basic: assign each ~g-key~ to a key which does not exist on physical keyboard. Any key could be used, like specific localized keys which do not exist on your keyboard (example: Japanese keys for an English keyboard), or function keys above F12.

We will choose to map them to Function keys ~F13~ to ~F21~. It is possible that some of these F-keys are already used on your system (example: some media keys may be assigned to ~F20~). In this case, simply use another F-key.

The ~g910-gkeys~ will be (skipping ~F20~ on my system):

#+BEGIN_SRC json
{
    "__comment": "I was unable to use F20, even xev does not show the keycode. It just mutes/unmutes sound, same as the G910's <mute> button",
    "keyboard_mapping": "en",
    "g1": {
        "hotkey_type": "shortcut",
        "do": "F13"
    },
    "g2": {
        "hotkey_type": "shortcut",
        "do": "F14"
    },
    "g3": {
        "hotkey_type": "shortcut",
        "do": "F15"
    },
    "g4": {
        "hotkey_type": "shortcut",
	    "do": "F16"
    },
    "g5": {
        "hotkey_type": "shortcut",
        "do": "F17"
    },
    "g6": {
        "hotkey_type": "shortcut",
        "do": "F18"
    },
    "g7": {
        "hotkey_type": "shortcut",
        "do": "F19"
    },
    "g8": {
        "hotkey_type": "shortcut",
        "do": "F21"
    },
    "g9": {
        "hotkey_type": "shortcut",
        "do": "F22"
    }
}
#+END_SRC

** X11 keyboard mapping
By default, our F13-F22 may be mapped to some defaults (see /usr/share/X11/xkb/symbols/inet). For example, ~F13~ will return ~XF86Tools~. This is not what we want. Instead we want F13-F22 to return themselves. It could be possible to keep the default mappings, but it makes less sense.

You can check if this mapping is done on your system with:
#+BEGIN_SRC
$ xmodmap -pke | grep -E 'keycode (19[1-9]|200)'~
keycode 191 = XF86Tools NoSymbol XF86Tools
keycode 192 = XF86Launch5 NoSymbol XF86Launch5
keycode 193 = XF86Launch6 NoSymbol XF86Launch6
...
keycode 200 = XF86TouchpadOn NoSymbol XF86TouchpadOn
#+END_SRC

If the output looks like the above, you will need to use one of the two above methods :
*** Fix F-keys mapping with .Xmodmaprc
** User configuration
*Note*: Configuration below will make the ~G-keys~ active only when user is logged-on, as any other key.

We will assign the F-keys we defined in ~config.json~ to any program (this includes graphical programs), or to send a string to active window (using *xvkbd*[fn:1]).

*xvkbd* not only allows to send strings ("hello, World!"), but also modifiers (as ~Control-A~, ~Alt-B~, ~Control-Left~), mouse events (motion, buttons), etc... This is a subset of the *typeout* option of config.json. See ~xbkbd man page~ for more details.

Below are some examples (screenshots from ~Xubuntu 22.10~). We will define the following actions :
- ~G1~: Activate the *Emacs* main window (whose title is always "*GNU Emacs*").
- ~Shift-G1~: Launch *Gnome Terminal*.
- ~G2~ (including with modifiers): Send strings/commands results to active window.
- ~G4~: Send current date to active window.
- ~G5~: Assigned to ~Hyper~ modifier: ~G5 + a~ will be ~Hyper-a~, as ~Control + a~ is ~Control-a~.
- ~G6~: Will move the cursor to top-left corner.
All settings below (except for ~G5~) are configurable in ~Settings/keyboard~, ~Application Shortcuts~ tab, or, for pasting text, via ~autokey~ :
#+CAPTION: Xfce keyboard settings
[[./img/g910-keyboard-settings.png]]
#+CAPTION: Autokey screenshot
[[./img/autokey.png]]
*** G1: Activate the *Emacs* main window
In ~Application Shortcut~ section, click on ~Add~, then set command to ~wmctrl -F -a "GNU Emacs"~, click ~OK~, then press ~G1~ when asked.
*** Shift-G1: Launch *Gnome Terminal*
In ~Application Shortcut~ section, click on ~Add~, then set command to ~gnome-terminal~, click ~OK~, then press ~Shift-G1~ when asked.
*** G2: Send different strings to active window
We can send static/dynamic strings to active window, using ~autokey~ (on Ubuntu 22.10, autokey is provided by ~autokey-gtk~ or ~autokey-qt~ packages).

Note that you can use any combination of modifiers (for example Shift+Meta+G2).
Example 1:
Insert Japanese "山" with Shift-Control-G2 :

Example 2:
Insert current date to active window with G2 :


*** G5: Assign to /Hyper/ modifier
In ~$HOME/.Xmodmap~, (create if non existant) rmove any line regarding add the following lines~/Move mouse cursor to top-left corner
In ~Application Shortcut~ section, click on ~Add~, then set command to ~xvkbd -text '\x0\y0'~ (or ~xdotool mousemove 0 0~), click ~OK~, then press ~G6~ when asked.
*** G6: Move mouse cursor to top-left corner
In ~Application Shortcut~ section, click on ~Add~, then set command to ~xvkbd -text '\x0\y0'~ (or ~xdotool mousemove 0 0~), click ~OK~, then press ~G6~ when asked.

NOTE: wayland equivalent to : wtype