Keyboard Support

[Ketschak]

How does the Murl Engine handle keyboard support?

The Murl Engine provides two possible ways to process keyboard events.

RawKeys

The Murl::Input::IRawKeyboardDevice can be used to obtain the status of physical keys on the keyboard – we call them "raw keys". The definition for raw key codes can be found in the file murl_raw_key_codes.h:

enum RawKeyCode
    {
        RAWKEY_NONE             = 0x00,
       
        RAWKEY_ESCAPE           = 0x01,
        RAWKEY_1                = 0x02,
        RAWKEY_2                = 0x03,
        …
 

The file should contain a RAWKEY_… definition for every possible physical key. The list includes e.g. RAWKEY_0, RAWKEY_KEYPAD_0, RAWKEY_LEFT_SHIFT, RAWKEY_KEYPAD_NUMLOCK, RAWKEY_VOLUME_UP, RAWKEY_KANJI etc.

If you press on an English keyboard the key Y you will get events for RAWKEY_Y. The same key is labeled with Z on a German keyboard. Nevertheless if you press the key Z on a German keyboard you will get events for RAWKEY_Y because it is the same physical button with the same key code.

If you press the two keys left SHIFT and Y you will get events for both keys RAWKEY_Y and RAWKEY_LEFT_SHIFT.

To obtain the status for physical keyboard input, you can use the device handler's WasRawKeyPressed() method.

Logic::IDeviceHandler* deviceHandler = state->GetDeviceHandler();
if (deviceHandler->WasRawKeyPressed(RAWKEY_Y))
  //do whatever is to do

In addition to WasRawKeyPressed(), physical keyboard input is also reflected by the IsRawKeyPressed() and WasRawKeyReleased() methods. During a regular keystroke, these methods return true in the following sequence:

1. At the moment of first pressing the key down, WasRawKeyPressed() returns true for exactly one logic tick
   
2. As long as the key is down, IsRawKeyPressed() returns true in every logic tick.
   
3. When the key is released, WasRawKeyReleased() returns true for exacly one logic tick.
   

This behavior is also detailed described in the tutorials section: http://murlengine.com/tutorials/en/_tuto...01_t02.php

Please note that the framework do not report raw keys for non-physical keyboards e.g. touch screen keyboards on mobile devices.

Vanilla Keys

The Murl::Input::IKeyboardDevice can be used to obtain the character value of a keystroke after the operating system processed the key codes – we call them "vanilla keys".

While the IRawKeyboardDevice only reports key states, the IKeyboardDevice reports the UTF8 encoded character representation of a keystroke. The result depends for example on your language settings.

If you press the key Y you will get a lowercase y if the language is set to English. If you press the two keys SHIFT and Y you will get uppercase Y. If the language is set to German you will get z or Z respectively.

You can use the the device handler's GetNumberOfKeys, GetKey and GetKeys methods to obtain the UTF8 character representation.

Logic::IDeviceHandler* deviceHandler = state->GetDeviceHandler();
UInt32 numKeys = deviceHandler->GetNumberOfKeys();
for (UInt32 i = 0; i < numKeys; i++)
	Debug::Trace(deviceHandler->GetKey(i));
if (deviceHandler->WasRawKeyPressed(RAWKEY_Y))
	Debug::Trace("RAW Y PRESSED");
if (deviceHandler->WasRawKeyReleased(RAWKEY_Y))
	Debug::Trace("RAW Y RELEASED");