glfwGetKeyName function

String glfwGetKeyName(
  1. int key,
  2. int scancode
)

! @brief Returns the layout-specific name of the specified printable key.

This function returns 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 function for text input(@ref input_char). You will break text input for many languages even if it happens to work for yours.

If the key is GLFW_KEY_UNKNOWN, the scancode is used to identify the key, otherwise the scancode is ignored. If you specify a non-printable key, or GLFW_KEY_UNKNOWN and a scancode that maps to a non-printable key, this function returns NULL but does not emit an error.

This behavior allows you to always pass in the arguments in the key callback(@ref input_key) without modification.

The printable keys are:

  • GLFW_KEY_APOSTROPHE
  • GLFW_KEY_COMMA
  • GLFW_KEY_MINUS
  • GLFW_KEY_PERIOD
  • GLFW_KEY_SLASH
  • GLFW_KEY_SEMICOLON
  • GLFW_KEY_EQUAL
  • GLFW_KEY_LEFT_BRACKET
  • GLFW_KEY_RIGHT_BRACKET
  • GLFW_KEY_BACKSLASH
  • GLFW_KEY_WORLD_1
  • GLFW_KEY_WORLD_2
  • GLFW_KEY_0 to GLFW_KEY_9
  • GLFW_KEY_A to GLFW_KEY_Z
  • GLFW_KEY_KP_0 to GLFW_KEY_KP_9
  • GLFW_KEY_KP_DECIMAL
  • GLFW_KEY_KP_DIVIDE
  • GLFW_KEY_KP_MULTIPLY
  • GLFW_KEY_KP_SUBTRACT
  • GLFW_KEY_KP_ADD
  • GLFW_KEY_KP_EQUAL

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.

@paramin key The key to query, or GLFW_KEY_UNKNOWN. @paramin scancode The scancode of the key to query. @return The UTF-8 encoded, layout-specific name of the key, or NULL.

@errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_INVALID_VALUE, @ref GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.

@remark The contents of the returned string may change when a keyboard layout change event is received.

@pointer_lifetime The returned string is allocated and freed by GLFW. You should not free it yourself. It is valid until the library is terminated.

@thread_safety This function must only be called from the main thread.

@sa @ref input_key_name

@since Added in version 3.2.

@ingroup input

GLFWAPI const char* glfwGetKeyName(int key, int scancode)

Implementation

String glfwGetKeyName(int key, int scancode) {
  final glfwGetKeyNameLookupFunction = libglfw.lookupFunction<
      Pointer<Utf8> Function(Int32 key, Int32 scancode),
      Pointer<Utf8> Function(int key, int scancode)>('glfwGetKeyName');
  return glfwGetKeyNameLookupFunction(key, scancode).toDartString();
}