struct Espresso::Keyboard

Overview

Information about the keyboard that is associated with a window. Each Window has its own keyboard instance with properties specific to that window. To retrieve a keyboard instance, use Window#keyboard.

GLFW divides keyboard input into two categories; key events and character events. Key events relate to actual physical keyboard keys, whereas character events relate to the Unicode code points generated by pressing some of them.

Keys and characters do not map 1:1. A single key press may produce several characters, and a single character may require several keys to produce. This may not be the case on your machine, but your users are likely not all using the same keyboard layout, input method or even operating system as you.

Included Modules

Defined in:

espresso/keyboard.cr

Class Method Summary

Instance Method Summary

Class Method Detail

def self.key_name?(key : Key) #

Retrieves the name of the specified printable key, encoded as UTF-8. This is typically the character that key would produce without any modifier keys, intended for displaying key bindings to the user. For dead keys, it is typically the diacritic it would add to a character.

Do not use this method for text input. You will break text input for many languages even if it happens to work for yours.

The printable keys are:

Names for printable keys depend on keyboard layout, while names for non-printable keys are the same across layouts but depend on the application language and should be localized along with other user interface text.

Returns a string if a name is available for the specified key, nil otherwise.


[View source]
def self.key_name?(scancode) #

Retrieves the name of the specified printable key, encoded as UTF-8. This is typically the character that key would produce without any modifier keys, intended for displaying key bindings to the user. For dead keys, it is typically the diacritic it would add to a character.

Do not use this method for text input. You will break text input for many languages even if it happens to work for yours.

Names for printable keys depend on keyboard layout, while names for non-printable keys are the same across layouts but depend on the application language and should be localized along with other user interface text.

Returns a string if a name is available for the specified scancode, nil otherwise.


[View source]
def self.scancode(key) #

Retrieves the platform-specific scancode of the specified key.

If the key is Key::Unknown or does not exist on the keyboard this method will raise NilAssertionError.


[View source]
def self.scancode?(key) #

Retrieves the platform-specific scancode of the specified key.

If the key is Key::Unknown or does not exist on the keyboard this method will return nil.


[View source]

Instance Method Detail

def key(key) #

Retrieves the last state reported for the specified key to the associated window. The returned state is one of KeyState::Pressed or KeyState::Released. The higher-level action KeyState::Repeated is only reported to the #on_key event.

If the #sticky? input mode is enabled, this method returns KeyState::Pressed the first time you call it for a key that was pressed, even if that key has already been released.

The key method deal with physical keys, with key tokens (see: Key) named after their use on the standard US keyboard layout. If you want to input text, use the Unicode character callback instead (see #on_char).

The modifier key bit masks are not key tokens and cannot be used with this method.

Do not use this method to implement text input.


[View source]
def key?(key) #

Determines whether the last state reported for the specified key is pressed.

If the #sticky? input mode is enabled, this method returns true the first time you call it for a key that was pressed, even if that key has already been released.


[View source]
def lock_key_modifiers=(flag) #

Enables or disables lock key modifier flags. If enabled, callbacks that receive modifier bits will also have the ModifierKey::CapsLock flag set when the event was generated with Caps Lock on, and the ModifierKey::NumLock flag when Num Lock was on.


[View source]
def lock_key_modifiers? #

Indicates whether lock key modifier flags are enabled. If enabled, callbacks that receive modifier bits will also have the ModifierKey::CapsLock flag set when the event was generated with Caps Lock on, and the ModifierKey::NumLock flag when Num Lock was on.


[View source]
def on_char(&block : KeyboardCharEvent -> ) #

Registers a listener to respond when a character is entered. The block of code passed to this method will be invoked when the event occurs. A KeyboardCharEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_char_listener with the proc returned by this method.

The character callback is intended for Unicode text input. As it deals with characters, it is keyboard layout dependent, whereas the #on_key event is not. Characters do not map 1:1 to physical keys, as a key may produce zero, one or more characters. If you want to know whether a specific physical key was pressed or released, see the #on_key event instead.

The character callback behaves as system text input normally does and will not be called if modifier keys are held down that would prevent normal text input on that platform, for example a Super (Command) key on macOS or Alt key on Windows.


[View source]
def on_char_mods(&block : KeyboardCharModsEvent -> ) #

Registers a listener to respond when a character is entered. The block of code passed to this method will be invoked when the event occurs. A KeyboardCharEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_char_listener with the proc returned by this method.

This event is intended for implementing custom Unicode character input. For regular Unicode text input, use #on_char instead. Like #on_char, this event deals with characters and is keyboard layout dependent. Characters do not map 1:1 to physical keys, as a key may produce zero, one or more characters. If you want to know whether a specific physical key was pressed or released, use #on_key instead.

Deprecated: Scheduled for removal in GLFW 4.0.


[View source]
def on_key(&block : KeyboardKeyEvent -> ) #

Registers a listener to respond when a key is pressed, released, or repeated. The block of code passed to this method will be invoked when the event occurs. A KeyboardKeyEvent instance will be passed to the block as an argument, which contains all relevant information about the event. To remove the listener, call #remove_key_listener with the proc returned by this method.

This event deals with physical keys, with layout independent key tokens named after their values in the standard US keyboard layout. If you want to input text, use #on_char instead.

When a window loses input focus, it will generate synthetic key release events for all pressed keys. You can tell these events from user-generated events by the fact that the synthetic ones are generated after the focus loss event has been processed, i.e. after the Window#on_focus listeners has been called.


[View source]
def remove_char_listener(proc : KeyboardCharEvent -> ) : Nil #

Removes a previously registered listener that responded to the #on_char callback. The proc argument should be the return value of the #on_char method.


[View source]
def remove_char_mods_listener(proc : KeyboardCharModsEvent -> ) : Nil #

Removes a previously registered listener that responded to the #on_char_mods callback. The proc argument should be the return value of the #on_char_mods method.


[View source]
def remove_key_listener(proc : KeyboardKeyEvent -> ) : Nil #

Removes a previously registered listener that responded to the #on_key callback. The proc argument should be the return value of the #on_key method.


[View source]
def sticky=(flag) #

Enables or disables sticky keys. This is not the infamous Windows sticky keys. If sticky keys are enabled, a key press will ensure that #key returns KeyState::Pressed the next time it is called even if the key had been released before the call. This is useful when you are only interested in whether keys have been pressed but not when or in which order.

Whenever you poll state (via #key), you risk missing the state change you are looking for. If a pressed key is released again before you poll its state, you will have missed the key press. The recommended solution for this is to use #on_key, but there is also the sticky key input mode.

Possible errors that could be raised are: NotInitializedError and PlatformError.

See also: #sticky?


[View source]
def sticky? #

Indicates whether stick keys is enabled. This is not the infamous Windows sticky keys. If sticky keys are enabled, a key press will ensure that #key returns KeyState::Pressed the next time it is called even if the key had been released before the call. This is useful when you are only interested in whether keys have been pressed but not when or in which order.

See also: #sticky=


[View source]
def to_unsafe : LibGLFW::Window #

Retrieves the underlying window pointer.


[View source]