Missing reference for keyboard keys

[ed2050]

Question

Where's the reference for keyboard keys? There should be a complete list of possible values for KeyEventArguments passed to ui.keyboard callback. These are not provided anywhere in the ui.keyboard doc page.

For instance:

• e.modifiers.shift is shown for shift key. What other modifiers are available? Different systems use different names: meta, option, window, etc. A complete list is needed.
• arrow keys are shown as e.key.arrow_left, etc. What other properties does e.key have for keystrokes?
• how do you detect unprintable keys like backspace, delete, home, end, etc? Probably e.key.something... but what?

If these values are taken from another reference (such as js key events), then the complete spec should be linked from the ui.keyboard docs page. Did I miss them somewhere else?

Thanks.

[falkoschindler]

Thanks for bringing this up, @ed2050. I just created PR #3010 to address this issue.

[ed2050]

Thanks, huge improvement!

1. One part of new text isn't clear. What is the value of .key.name for non-printing chars? Exhaustive values are only listed for properties, not for .name.

The new text says e.g. 'Enter' for key.name, while key properties uses lowercase .enter. Does this correlation hold for other keys? If evt.key.left_arrow is true, then evt.key.name is ...

• LeftArrow
• Left_Arrrow
• Leftarrow
• something else?

2. Same question for key.code. Only a few examples are given. How do we find .code values for other keys?

3. Also, the docs use checks like evt.key == 'f' not evt.key.name == 'f'. Presumably the implementation of == op uses key.name. Is that correct? If so , might be worth explicitly stating.

[ed2050]

Example

Here's an example of why having key.name values for all keys matters. Checking key.name is more flexible than checking properties. For instance, I can define a dict mapping keys to actions, and use that in keyboard listener to dispatch key events. Something like:

keymappings = {
        'a' : lambda : keepnames (allnames) ,
        'o' : lambda : keepnames (allnames [0]) ,
        'p' : lambda : prune () ,
        'z' : lambda : reload_page () ,
        'LeftArrow'  : load_prev ,
        'RightArrow' : load_next ,
}

def keylisten (evt) :
    func = keymappings.get (evt.key.name, none)
    if func :  func ()

ui.keyboard (on_key = keylisten)

This is a convenient and dynamic way to dispatch key actions without writing if key == 'foo' ; elif key == 'bar' ; elif ... tests. It breaks if certain keys like arrows don't have a unique key.name string and require checking key.left_arrow instead.

[falkoschindler]

Hi @ed2050,

The implementation of keyboard event arguments is pretty straightforward and can be found here:

nicegui/nicegui/events.py

Lines 137 to 353 in 5a25f18

	@dataclass(**KWONLY_SLOTS)
	class KeyboardAction:
	keydown: bool
	keyup: bool
	repeat: bool
	@dataclass(**KWONLY_SLOTS)
	class KeyboardModifiers:
	alt: bool
	ctrl: bool
	meta: bool
	shift: bool
	@dataclass(**KWONLY_SLOTS)
	class KeyboardKey:
	name: str
	code: str
	location: int
	def __eq__(self, other: object) -> bool:
	if isinstance(other, str):
	return other in {self.name, self.code}
	if isinstance(other, KeyboardKey):
	return self == other
	return False
	def __repr__(self):
	return str(self.name)
	@property
	def is_cursorkey(self) -> bool:
	"""Whether the key is a cursor key (arrow keys)."""
	return self.code.startswith('Arrow')
	@property
	def number(self) -> Optional[int]:
	"""Integer value of a number key."""
	return int(self.code.removeprefix('Digit')) if self.code.startswith('Digit') else None
	@property
	def backspace(self) -> bool:
	"""Whether the key is the backspace key."""
	return self.name == 'Backspace'
	@property
	def tab(self) -> bool:
	"""Whether the key is the tab key."""
	return self.name == 'Tab'
	@property
	def enter(self) -> bool:
	"""Whether the key is the enter key."""
	return self.name == 'Enter'
	@property
	def shift(self) -> bool:
	"""Whether the key is the shift key."""
	return self.name == 'Shift'
	@property
	def control(self) -> bool:
	"""Whether the key is the control key."""
	return self.name == 'Control'
	@property
	def alt(self) -> bool:
	"""Whether the key is the alt key."""
	return self.name == 'Alt'
	@property
	def pause(self) -> bool:
	"""Whether the key is the pause key."""
	return self.name == 'Pause'
	@property
	def caps_lock(self) -> bool:
	"""Whether the key is the caps lock key."""
	return self.name == 'CapsLock'
	@property
	def escape(self) -> bool:
	"""Whether the key is the escape key."""
	return self.name == 'Escape'
	@property
	def space(self) -> bool:
	"""Whether the key is the space key."""
	return self.name == 'Space'
	@property
	def page_up(self) -> bool:
	"""Whether the key is the page up key."""
	return self.name == 'PageUp'
	@property
	def page_down(self) -> bool:
	"""Whether the key is the page down key."""
	return self.name == 'PageDown'
	@property
	def end(self) -> bool:
	"""Whether the key is the end key."""
	return self.name == 'End'
	@property
	def home(self) -> bool:
	"""Whether the key is the home key."""
	return self.name == 'Home'
	@property
	def arrow_left(self) -> bool:
	"""Whether the key is the arrow left key."""
	return self.name == 'ArrowLeft'
	@property
	def arrow_up(self) -> bool:
	"""Whether the key is the arrow up key."""
	return self.name == 'ArrowUp'
	@property
	def arrow_right(self) -> bool:
	"""Whether the key is the arrow right key."""
	return self.name == 'ArrowRight'
	@property
	def arrow_down(self) -> bool:
	"""Whether the key is the arrow down key."""
	return self.name == 'ArrowDown'
	@property
	def print_screen(self) -> bool:
	"""Whether the key is the print screen key."""
	return self.name == 'PrintScreen'
	@property
	def insert(self) -> bool:
	"""Whether the key is the insert key."""
	return self.name == 'Insert'
	@property
	def delete(self) -> bool:
	"""Whether the key is the delete key."""
	return self.name == 'Delete'
	@property
	def meta(self) -> bool:
	"""Whether the key is the meta key."""
	return self.name == 'Meta'
	@property
	def f1(self) -> bool:
	"""Whether the key is the F1 key."""
	return self.name == 'F1'
	@property
	def f2(self) -> bool:
	"""Whether the key is the F2 key."""
	return self.name == 'F2'
	@property
	def f3(self) -> bool:
	"""Whether the key is the F3 key."""
	return self.name == 'F3'
	@property
	def f4(self) -> bool:
	"""Whether the key is the F4 key."""
	return self.name == 'F4'
	@property
	def f5(self) -> bool:
	"""Whether the key is the F5 key."""
	return self.name == 'F5'
	@property
	def f6(self) -> bool:
	"""Whether the key is the F6 key."""
	return self.name == 'F6'
	@property
	def f7(self) -> bool:
	"""Whether the key is the F7 key."""
	return self.name == 'F7'
	@property
	def f8(self) -> bool:
	"""Whether the key is the F8 key."""
	return self.name == 'F8'
	@property
	def f9(self) -> bool:
	"""Whether the key is the F9 key."""
	return self.name == 'F9'
	@property
	def f10(self) -> bool:
	"""Whether the key is the F10 key."""
	return self.name == 'F10'
	@property
	def f11(self) -> bool:
	"""Whether the key is the F11 key."""
	return self.name == 'F11'
	@property
	def f12(self) -> bool:
	"""Whether the key is the F12 key."""
	return self.name == 'F12'
	@dataclass(**KWONLY_SLOTS)
	class KeyEventArguments(UiEventArguments):
	action: KeyboardAction
	key: KeyboardKey
	modifiers: KeyboardModifiers

It is derived from JavaScript's keyboard events which are documented here:
https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent

Maybe you can take a look and let us know what specific information should be added to the documentation? As usual, we like to keep it short, but avoiding confusion by giving a few more hints can't hurt. Thanks! 🙂

[ed2050]

Sure no problem. I suspected they came from JS. In that case, no need to list them all in your docs, a link will suffice. Not the page you linked but the page of key values.

Line 40 of nicegui/elements/keyboard.py could be changed to this:

• name: the name of the key (e.g. 'a', 'Enter'). An exhaustive list of possible key names can be found at https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values.

There are many more keys on the reference page than nicegui implements. Keys like Function (Fn), media keys (Play, Pause, Stop), controls (Power, Brightness, Mute, Volume), etc. If you don't plan to support those keys, add a note which keys nicegui does support, like "101-key ANSI" or whatever (I don't know the technical names).

[falkoschindler]

Ok, I added a link to that page in 53af516. But I struggle to find a description for the set of keys covered with properties (backspace, tab, enter, ...). Sure, the list is not complete, but I find it hard to draw a line. Many of them mentioned in the JavaScript documentation have footnotes and limitations, and would obscure the autocompletion for "useful" ones. And even if a key doesn't have its own Python property, the event still works and you can simply check the key name or code via string comparison.

[ed2050]

@falkoschindler sure that's fine. I was under the impression that only keys covered in nicegui docs (shift, enter, f1, etc) were available in nicegui. Seems I was mistaken. If keys any key received in the browser will be forwarded to nicegui as a key event, then no need to describe which are supported.

Thanks for addressing these doc improvements. It may seem like a small thing, but it's very helpful. Especially for people unfamiliar with the JS world. 👍

[ed2050]

It would also be nice to have a shortcut to detect if any modifier keys were pressed. Detecting no mod keys is a common pattern. So instead of tedious code like this :

if key == 'a' and not (key.modifiers.alt or key.modifiers.ctrl or key.modifiers.meta or key.modifiers.shift) :
    do something ...

We could have code like this :

if key == 'a' and not any (key.modifiers) :
   do something ....

This would just require that key.modifiers be iterable over its __dict___.values. An even simpler approach could be :

if key == 'a' and not key.modifiers :
    do something

which would require key.modifiers to convert to boolean. (And either works with my example key dispatcher above. key == 'a' is just for simplicity here.)

It's true that users could write their own function hasmods (keyevent) to test whether a key has any modifiers set. However this is such a common use case that it should be considered for inclusion in nicegui.

Thanks.

[falkoschindler]

Ok, in 7715530 I added __iter__ and __len__ to KeyboardModifiers so that you can write

ui.keyboard(lambda e: print(any(e.modifiers), len(e.modifiers), 'MOD' if e.modifiers else ''))

False 0 
True 1 MOD
True 2 MOD
True 3 MOD
True 4 MOD