#include <KeyEvent.hpp>

Inheritance diagram for gamp::wt::event::KeyEvent:

Collaboration diagram for gamp::wt::event::KeyEvent:

Public Member Functions
	KeyEvent (uint16_t type, const jau::fraction_timespec &when, const WindowRef &source, InputModifier globalMods, VKeyCode keySym, InputModifier keySymMods, uint16_t keyChar) noexcept

constexpr bool	isActionKey () const noexcept
	Returns `true` if `key symbol` represents a non-printable and non-`modifier` action key, otherwise `false`.

constexpr bool	isModifierKey () const noexcept
	Returns `true` if `key symbol` represents a modifier key, otherwise `false`.

constexpr bool	isPrintableKey () const noexcept
	Returns `true` if `key symbol` and `key char` represents a printable character, i.e.

constexpr bool	isTyped () const noexcept
	Returns true if event matches original key typed semantics, i.e.:

constexpr uint16_t	keyChar () const noexcept
	Returns the UTF-16 character reflecting the `key symbol` incl.

constexpr VKeyCode	keySym () const noexcept
	Returns the virtual key symbol reflecting the current keyboard layout.

std::string	toString () const noexcept

Public Member Functions inherited from gamp::wt::event::InputEvent
	InputEvent (uint16_t type, const jau::fraction_timespec &when, const WindowRef &source, InputModifier mods) noexcept

constexpr int	buttonDownCount () const noexcept
	Returns the number of pressed buttons by counting the set bits:

std::vector< InputButton >	buttonsDown () const
	See also `MouseEvent`'s section about Multiple-Pointer Events.

constexpr bool	has_any (InputModifier bits) const noexcept
	Use with groups of bits / mask, e.g.

constexpr bool	is_set (InputModifier bits) const noexcept
	Use with single bits, e.g.

constexpr bool	isAltDown () const noexcept
	Returns true if modifier() contains InputModifier::alt.

constexpr bool	isAnyButtonDown () const noexcept
	Returns true if at least one button is pressed, otherwise false:

constexpr bool	isAutorepeat () const noexcept
	Returns true if modifier() contains InputModifier::autorepeat.

constexpr bool	isButtonDown (InputButton button) const noexcept
	See also `MouseEvent`'s section about Multiple-Pointer Events.

constexpr bool	isConfined () const noexcept
	Returns true if modifier() contains InputModifier::confined.

constexpr bool	isControlDown () const noexcept
	Returns true if modifier() contains InputModifier::ctrl.

constexpr bool	isInvisible () const noexcept
	Returns true if modifier() contains InputModifier::invisible.

constexpr bool	isMetaDown () const noexcept
	Returns true if modifier() contains InputModifier::meta.

constexpr bool	isShiftDown () const noexcept
	Returns true if modifier() contains InputModifier::shift.

constexpr InputModifier	modifier () const noexcept

std::string	toString () const noexcept

Public Member Functions inherited from gamp::wt::event::WTEvent
	WTEvent (uint16_t type, const jau::fraction_timespec &when, const WindowRef &source) noexcept

constexpr bool	consumed () const noexcept
	Consumed events will stop traversing through listener.

constexpr void	setConsumed (bool v) noexcept
	Consumed events will stop traversing through listener.

constexpr const WindowWeakPtr &	source () const noexcept

std::string	toString () const noexcept

constexpr uint16_t	type () const noexcept

constexpr const jau::fraction_timespec &	when () const noexcept

Additional Inherited Members
Static Public Member Functions inherited from gamp::wt::event::InputEvent
static constexpr InputModifier	buttonMask (InputButton button) noexcept
	Returns the corresponding button mask for the given button.

Detailed Description

KeyEvent Delivery

Key events are delivered in the following order:

#	Event Type	Constraints	Notes
1	`EVENT_KEY_PRESSED`	excluding `auto-repeat`-`modifier` keys
2	`EVENT_KEY_RELEASED`	excluding `auto-repeat`-`modifier` keys

In case the native platform does not deliver keyboard events in the above order or skip events, the NEWT driver will reorder and inject synthetic events if required.

Besides regular modifiers like InputModifier::shift etc., the InputModifier::autorepeat bit is added if repetition is detected, following above constraints.

Auto-Repeat shall behave as follow:

 P = pressed, R = released
 0 = normal, 1 = auto-repeat

 P(0), [ R(1), P(1), R(1), ..], R(0)

The idea is if you mask out auto-repeat in your event listener you just get one long pressed P/R tuple for printable and Action keys.

Action keys will produce pressed and released events including auto-repeat.

Printable keys will produce pressed and released events.

Modifier keys will produce pressed and released events excluding auto-repeat. They will also influence subsequent event's modifier bits while pressed.

Unicode Mapping

Key-chars, as well as printable key-codes and key-symbols use the UTF-16 unicode space w/o collision.

Non-printable key-codes and key-symbols, i.e. modifier- and action-keys, are mapped to unicode's control and private range and do not collide w/ printable unicode values with the following exception.

Unicode Collision

The following Key-codes and key-symbols collide w/ unicode space:

unicode range	virtual key code	unicode character
[0x61 .. 0x78]	[`VK_F1`..`VK_F24`]	['a'..'x']

Collision was chosen for Key-code and key-symbol mapping to allow a minimal code range, i.e. [0..255]. The reduced code range in turn allows the implementation to utilize fast and small lookup tables, e.g. to implement a key-press state tracker.

http://www.utf8-chartable.de/unicode-utf8-table.pl
http://www.unicode.org/Public/5.1.0/ucd/PropList.txt
https://en.wikipedia.org/wiki/Mapping_of_Unicode_characters
https://en.wikipedia.org/wiki/Unicode_control_characters
https://en.wikipedia.org/wiki/Private_Use_%28Unicode%29#Private_Use_Areas

Examples: GearsES2.cpp, and RedSquareES2.cpp.

Definition at line 755 of file KeyEvent.hpp.

Constructor & Destructor Documentation

◆ KeyEvent()

gamp::wt::event::KeyEvent::KeyEvent	(	uint16_t	type,
		const jau::fraction_timespec &	when,
		const WindowRef &	source,
		InputModifier	globalMods,
		VKeyCode	keySym,
		InputModifier	keySymMods,
		uint16_t	keyChar )

inlinenoexcept

Definition at line 772 of file KeyEvent.hpp.

Member Function Documentation

◆ keySym()

VKeyCode gamp::wt::event::KeyEvent::keySym ( ) const

inlineconstexprnoexcept

Returns the virtual key symbol reflecting the current keyboard layout.

For printable keys, the key symbol is the unmodified representation of the UTF-16 key char.
E.g. symbol [VK_A, 'A'] for char 'a'.

See also: isPrintableKey(); #getKeyChar(); #getKeyCode()

Examples: GearsES2.cpp, GraphShapes01.cpp, Primitives02.cpp, and RedSquareES2.cpp.

Definition at line 798 of file KeyEvent.hpp.

Here is the caller graph for this function:

◆ keyChar()

uint16_t gamp::wt::event::KeyEvent::keyChar ( ) const

inlineconstexprnoexcept

Returns the UTF-16 character reflecting the key symbol incl.

active modifiers.

See also: #getKeySymbol(); #getKeyCode()

Definition at line 806 of file KeyEvent.hpp.

Here is the caller graph for this function:

◆ isPrintableKey()

bool gamp::wt::event::KeyEvent::isPrintableKey ( ) const

inlineconstexprnoexcept

Returns true if key symbol and key char represents a printable character, i.e.

a value other than VK_UNDEFINED and not a control or non-printable private code.

A printable character is neither a modifier key, nor an action key.

Otherwise returns false.

Definition at line 819 of file KeyEvent.hpp.

Here is the caller graph for this function:

◆ isModifierKey()

bool gamp::wt::event::KeyEvent::isModifierKey ( ) const

inlineconstexprnoexcept

Returns true if key symbol represents a modifier key, otherwise false.

See isModifierKey(short) for details.

Note: Implementation uses a cached value.

Definition at line 831 of file KeyEvent.hpp.

Here is the caller graph for this function:

◆ isActionKey()

bool gamp::wt::event::KeyEvent::isActionKey ( ) const

inlineconstexprnoexcept

Returns true if key symbol represents a non-printable and non-modifier action key, otherwise false.

Hence it is the set A of all keys U w/o printable P and w/o modifiers M: A = U - ( P + M )

See also: isPrintableKey(); isModifierKey()

Definition at line 843 of file KeyEvent.hpp.

Here is the caller graph for this function:

◆ isTyped()

bool gamp::wt::event::KeyEvent::isTyped ( ) const

inlineconstexprnoexcept

Returns true if event matches original key typed semantics, i.e.:

  isPrintableKey() && !is_set(InputModifier::autorepeat)

Definition at line 851 of file KeyEvent.hpp.

◆ toString()

std::string gamp::wt::event::KeyEvent::toString ( ) const

inlinenoexcept

Examples: GraphShapes01.cpp, Primitives02.cpp, and RedSquareES2.cpp.

Definition at line 855 of file KeyEvent.hpp.

Here is the caller graph for this function:

The documentation for this class was generated from the following file:

include/gamp/wt/event/KeyEvent.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

KeyEvent Delivery

Unicode Mapping

Unicode Collision

Constructor & Destructor Documentation

◆ KeyEvent()

Member Function Documentation

◆ keySym()

◆ keyChar()

◆ isPrintableKey()

◆ isModifierKey()

◆ isActionKey()

◆ isTyped()

◆ toString()