# Difficulties in understanding sombolic key names
**URL:** https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710
**Category:** Help and Getting Started
**Created:** [October 6, 2022, 1:35pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710 "2022-10-06T13:35:34Z")
**Posts on this page:** 9
**Page:** 1
### Author:  [@hupfdule](https://community.keyboard.io/u/hupfdule)
#### Post date: [October 6, 2022, 1:35pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/1 "2022-10-06T13:35:34Z")
I am still learning how to use Kaleidoscope. Therefore my question may seem silly and obvious. Sorry for that.
In the existing Model100.ino some symbolic key names are used, like `Key_Equals`, `Key_Slash`, etc. More can be found in the files below `src/kaleidoscope/key_defs/`.
But I am not sure _how_ they should be used. I expected them to match the actual keycodes, so I can use them to specify the keycode that should be produced by a certain key. But I found, that they are totally dependend on the keyboard layout selected in the OS. For example if I define my custom keymap with a QWERTY keymap on the OS side in mind it works. But if the keyboard layout on the OS is e.g. QWERTZ, the resulting characters are mostly different.
This makes it rather hard to use them. What is the intended way to use such symbolic names if one intends to use the keymap with a host layout different than QWERTY?
Also, I noticed that a lot of symbolic key names are missing. Those are mostly the ones that are shifted variants in QWERTY. For example `Key_Colon` does not exist. It could be created by `LSHIFT(Key_Semicolon)` when using a QWERTY layout. But I noticed that e.g. `Key_Pipe` already is defined in `aliases.h`. Why have some symbolic names been predefined and others are not?
Also, as they depend on QWERTY being the OS keyboard layout, they mostly do not work with other layouts.
Sorry for the dumb questions, but I am not used to programming my keyboard and have a few difficulties understanding the concepts behind it.
---
### Author:  [@argonblue](https://community.keyboard.io/u/argonblue)
#### Post date: [October 6, 2022, 2:25pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/2 "2022-10-06T14:25:51Z")
> [@hupfdule](#):
>
> so I can use them to specify the keycode that should be produced by a certain key
As far as the OS is concerned, “keycode” usually means the number associated with a physical key location on a keyboard. What user-visible letter or symbol it produces is a matter of mapping done by the OS. The keycode sent by Kaleidoscope is the key usage number defined by the USB HID specification. The symbolic name of the key usage might not correspond to how the OS interprets the key, especially in a non-US locale.
In the HID specification, the names of the key usage numbers are based on their typical use on an ANSI (North American or US English) keyboard. The spec gives the example of the key labeled “Z” on a German keyboard (which is in the same location as “Y” on a North American keyboard) producing the key usage number for “Y”, which the OS interprets as “Z”. This is to help manufacturers produce keyboards sharing the same electronics, only vary the key caps on a per-locale basis.
As you noticed, there are some aliases defined in `key_defs/aliases.h`, such as:
```c
#define Key_LeftCurlyBracket LSHIFT(Key_LeftBracket)
```
but some other aliases are missing. I’m not sure of the rationale for the choice of which aliases were defined. It might be that those happen to be the symbols that are used in the default keymaps.
> [@hupfdule](#):
>
> This makes it rather hard to use them. What is the intended way to use such symbolic names if one intends to use the keymap with a host layout different than QWERTY?
Yes, this makes it harder to define a custom key map if your OS key layout isn’t QWERTY. It isn’t feasible to create and maintain header files with alternative symbolic name mappings for every possible OS keyboard layout. If you are editing a keymap in a custom sketch, you will probably have to look up the correct symbols to use, referring to a QWERTY keyboard layout.
In Chrysalis, this is easier. If you set the OS key layout in Preferences, the key picker and the keyboard preview will both show remapped key labels corresponding to how your OS would interpret the keys. The key usage numbers sent to the OS by your keyboard remain the same until you edit the layout.
Note that there’s currently a small bug: after you change your OS keymap in Preferences, you will have to go back to “Select another keyboard”, click “Disconnect”, and then reconnect, before the editor will show the updated key labels in the preview.
---
### Author:  [@hupfdule](https://community.keyboard.io/u/hupfdule)
#### Post date: [October 6, 2022, 6:19pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/3 "2022-10-06T18:19:04Z")
Thank you for your explanations!
Yes, it’s a rather complicated topic. That’s probably what confused me. I didn’t know that the HID specification already defines such key names.
So, as I intend to use a non-QWERTY host keymap, I will problably have to avoid or redefine those symbolic key names. Otherwise the keymaps will be a bit hard to read.
---
### Author:  [@argonblue](https://community.keyboard.io/u/argonblue)
#### Post date: [October 6, 2022, 7:24pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/4 "2022-10-06T19:24:09Z")
> [@hupfdule](#):
>
> So, as I intend to use a non-QWERTY host keymap, I will problably have to avoid or redefine those symbolic key names. Otherwise the keymaps will be a bit hard to read.
It’s probably easier to use Chrysalis to edit keymaps for a non-US OS key layout.
If you intend to define your own aliases for custom firmware sketches, I suggest using a different prefix, to avoid conflicts with the existing aliases. For example, for a German OS key layout, you might try using a `Key_DE_` prefix instead of `Key_`:
```auto
#define Key_DE_Y Key_Z
#define Key_DE_Z Key_Y
#define Key_DE_OUmlaut Key_Semicolon
```
You could write those `#defines` at the top of your sketch, or in a new local header file that you include.
---
### Author:  [@hupfdule](https://community.keyboard.io/u/hupfdule)
#### Post date: [October 6, 2022, 9:15pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/5 "2022-10-06T21:15:15Z")
OK, I mainly managed to map the keys correctly. But there is one key I can’t reference, because I don’t know which symbolic name is referring to it. It is the key between the left shift and the Z (on a european QWERTY keyboard). An image of it can be seen [here](https://www.w3.org/TR/uievents-code/#keyboard-102). In that link it is named as “IntlBackslash”. But what is the correct name in `keyboard.h` for it?
I need it, because in a german layout that is the position of the keys `<`, `>` and `|`.
Can someone help me here?
---
### Author:  [@argonblue](https://community.keyboard.io/u/argonblue)
#### Post date: [October 6, 2022, 9:17pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/6 "2022-10-06T21:17:19Z")
> [@hupfdule](#):
>
> It is the key between the left shift and the Z (on a european QWERTY keyboard). An image of it can be seen [here](https://www.w3.org/TR/uievents-code/#keyboard-102). In that link it is named as “IntlBackslash”. But what is the correct name in `keyboard.h` for it?
I think it is this one:
```auto
#define Key_NonUsBackslashAndPipe Key(HID_KEYBOARD_NON_US_BACKSLASH_AND_PIPE, KEY_FLAGS)
```
---
### Author:  [@hupfdule](https://community.keyboard.io/u/hupfdule)
#### Post date: [October 6, 2022, 9:21pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/7 "2022-10-06T21:21:40Z")
> [@argonblue](#):
>
> It’s probably easier to use Chrysalis to edit keymaps for a non-US OS key layout.
As I have to do some definitions in the .ino file anyways, I thought it would be easier to define everything in it and not split it between the .ino file and Chrysalis.
I would be happy to create my layout in Chrysalis first, and then transfer it to the .ino file, but I have no idea how to map the Chrysalis layout to the keymap definition in the .ino file.
That leaves me with the problem now, that I don’t know how to refer to the “IntlBackslash” key mentioned above.
> [@argonblue](#):
>
> If you intend to define your own aliases for custom firmware sketches, I suggest using a different prefix, to avoid conflicts with the existing aliases.
Yes, that was my first idea, too. At the moment I haven’t done so and therefore overrode some preexisting ones, but I will change it to use such a prefix. It will be much more readable then.
---
### Author:  [@hupfdule](https://community.keyboard.io/u/hupfdule)
#### Post date: [October 6, 2022, 9:25pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/8 "2022-10-06T21:25:55Z")
> [@argonblue](#):
>
> I think it is this one:
>
> ```auto
> #define Key_NonUsBackslashAndPipe Key(HID_KEYBOARD_NON_US_BACKSLASH_AND_PIPE, KEY_FLAGS)
>
> ```
You are right! That’s the one!
Many thanks. You really helped me here.
---
### Author:  [@argonblue](https://community.keyboard.io/u/argonblue)
#### Post date: [October 6, 2022, 9:55pm UTC](https://community.keyboard.io/t/difficulties-in-understanding-sombolic-key-names/5710/9 "2022-10-06T21:55:28Z")
> [@hupfdule](#):
>
> I would be happy to create my layout in Chrysalis first, and then transfer it to the .ino file, but I have no idea how to map the Chrysalis layout to the keymap definition in the .ino file.
There is an open feature request in Chrysalis to export the keymap as a `.ino` file fragment [Output keymaps as code for pasting into an ino · Issue #77 · keyboardio/Chrysalis · GitHub](https://github.com/keyboardio/Chrysalis/issues/77)
If you have a GitHub account, you might like to add your opinions and ideas to that. (If not, one of us could relay your comments, or maybe link to this forum thread.)