How can I type accented characters with my UHK?

We get this question from time to time, and the answer is not as obvious as one might think. I'm about to explain it in-depth, but first, I'll give you a short answer in case you're in a hurry. Please consider the relevant tooltip of Agent:

Hopefully, this explains what to do. You're welcome to suggest better phrasing in the comments, but this is the short and sweet version. And now on to the more detailed explanation.

Characters vs Scancodes

The most important thing to understand is that USB keyboards (the UHK included) do not send characters to your computer. No, Sir. They send scancodes. When you press a key, a scancode of 1 to 255 gets sent to the computer. It's not a character but a number!

Now think about this: There are 255 different scancodes that must be mapped to more than 100,000 characters that are used on planet Earth! How so? This is how:

Your operating system translates scancodes to characters based on your actual operating system keyboard layout.

Let me give you an example to make you realize the crucial role of your OS layout. Let's say that an American, a German, and a Russian user purchase USB keyboards of the same physical layout. Now let's take the semicolon key according to the American layout. On all three keyboards, when pressing this key, the scancode 51 gets sent to the computer, yet, the character ";", "ö", and "ж" appear on the screen of the American, German, and Russian users, respectively, merely because they use different OS keymaps.

When it comes to mapping scancodes to characters, the situation is actually slightly more nuanced because modifiers also affect the mapped characters. For example, on the US layout, Shift + 4 produces "$", and on the Hungarian layout, AltGr + U produces "€", but this doesn't alter the nature of the beast.

Alt codes

There's a mechanism called "Alt codes", which allows users to produce various accented characters in a way that is (mostly) independent of the current OS keymap.

• On Linux, press Shift+Ctrl+U, which prefixes your cursor with an "u", indicating that a Unicode number is now expected. At this point, enter "2764" followed by Enter, and ❤ will magically get inserted. Linux Alt codes are the most powerful and standard, given that they're backed by Unicode numbers.
• On Windows, first, you have to have Num Lock enabled. Then, hold an Alt key and press a Windows-specific numeric code, and finally release the Alt key, at which point the relevant character will be included. 375 different characters can be included this way, but there is a way to unlock additional Alt codes to be able to access otherwise non-typeable Unicode characters
• On Macintosh, there's also a similar mechanism that is better called Accent Codes. Let's say you want to put an accent to the "o" letter. You press Option+E, then press "o," which results in "ó". The set of characters that can be produced this way is similarly limited as on Windows, although in true Mac fashion, the implementation is much more intuitive.

Alt codes provide a way to output various characters in a way that is mostly independent of the current OS keymap, but they're OS-specific, and they don't work in every environment. For example, let's say that your hard drive is encrypted, and you have to type a password before the OS boots up. Depending on your OS, Alt codes may not be available at this point. On Linux, they also can't be used in terminals outside of the X server, so you can't rely on them in every environment.

Alt codes on the UHK

Given that Alt codes are sequences of keystrokes, they're ideally suited to be assigned to keys using UHK macros. For example, you can bind the Alt code of "é" to Mod+e. UHK macros are very handy since they're saved to the on-board memory of your UHK and always available without running special software once you set them up via Agent. I'm about to elaborate on implementing Alt codes on your UHK.

The macro editor of Agent is very intuitive to use, and based on the above, one should be able to create macros that implement Alt codes. There are some gotchas, though.

First up, Alt codes are OS-specific which will pose a problem if you use multiple OSes. If so, you'll have to create all your Alt code macros for every OS you use, and then create OS-specific keymaps in Agent and bind the macros of the respective OSes. This is clearly laborious, but there's no way around it. We won't implement USB fingerprinting in the UHK firmware to detect OSes because it's fundamentally unreliable.

The second gotcha is that you won't be able to compose Alt codes with modifiers. Imagine holding Shift, then typing Alt code key sequences, then releasing Shift. Modifiers clearly mess with Alt codes.

Third, some Alt codes are dependent on the state of your OS. You have to have NumLock enabled for Windows Alt codes, and Mac accent codes are dependent on the OS keymap in use.

Accented characters in Agent

Some of you were wondering why Agent doesn't offer or display accented characters. This is one of those features that seem like a no-brainer from a user perspective, but in practice, it's not only incredibly hard to implement but cannot be implemented properly. Let me tell you why.

In order for Agent to expose accented characters, it must be aware of the current OS keymap. Being a cross-platform application, it'd have to query the actual keymap on Linux, Mac, and Windows. A quick search reveals ways to query this information (often rather obscure ways) via OS-specific APIs, but I have found no way to query the actual mappings between scancodes and characters, which is critical.

Without the exact per-key mappings, Agent would have to have a database of every single OS-specific layout, such as "French (Bepo, ergonomic, Dvorak way, Latin-9 only)" or "Russian (Ukraine, standard RSTU)". We could extract such a database from the relevant Linux packages, but these layout names are not standardized, so they're inconsistent across OSes, and the mappings surely differ in some ways.

The bottom line is that it'd take huge resources to implement the above, and we'd end up with a half-assed implementation, given that a perfect implementation is practically infeasible. Even if we were able to implement this perfectly, I don't think it would be a good idea. I can foresee users complaining that they set up the é key in Agent, then plugged their UHK into another machine (featuring a different OS keymap), and the é key suddenly became a semicolon. Users should actually understand how things work when it comes to this topic.

Scancodes vs Characters in the UHK

When remapping UHK keys, you should keep in mind that:

• Agent accepts characters:
  • In regular actions, Agent implicitly translates characters to scancodes according to the en-US mapping (and also back whenever it needs to show the corresponding label).  (So the saved configuration contains scancodes.)
  • In macros (the Text and Command action), Agent just leaves characters for the firmware to interpret. (So the saved configuration contains characters.)
• Internally, the UHK works with the macro Text and Command actions as with regular text (i.e., characters).
• However, the UHK always produces scancodes.
  • For regular actions, the configuration already contains scancodes, so the UHK just sends them to the computer.
  • If the UHK produces scancodes based on macro text (i.e., based on characters), the UHK translates them back to scancodes according to en-US mapping.
• The OS transforms scancodes (received from the UHK) back to characters according to its current language keymap.

That's it, folks! If you're still reading, then you're truly one of the brave few. Any questions, feel free to shoot them in the comments.

Custom scancodes

You can specify custom scancodes on the UHK. See how.