Internationalisation
Bundled Plugins API
keycodes
​
Convert between key-strings and key-codes. Also provides functionality for querying and changing keyboard layouts.

API Overview

API Documentation

Constants

​map​

Signature
hs.keycodes.map
Type
Constant
Description
A mapping from string representation of a key to its keycode, and vice versa.

Functions

​currentLayout​

Signature
hs.keycodes.currentLayout() -> string
Type
Function
Description
Gets the name of the current keyboard layout
Parameters
  • None
Returns
  • A string containing the name of the current keyboard layout

​currentLayoutIcon​

Signature
hs.keycodes.currentLayoutIcon() -> hs.image object
Type
Function
Description
Gets the icon of the current keyboard layout
Parameters
  • None
Returns
  • An hs.image object containing the icon, if available

​currentMethod​

Signature
hs.keycodes.currentMethod() -> string
Type
Function
Description
Get current input method
Parameters
  • None
Returns
  • Name of current input method, or nil

​currentSourceID​

| Signature | hs.keycodes.currentSourceID([sourceID]) -> string | boolean | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Get or set the source id for the keyboard input source | | Parameters |
  • sourceID - an optional string specifying the input source to set for keyboard input
| | Returns |
  • If no parameter is provided, returns a string containing the source id for the current keyboard layout or input method; if a parameter is provided, returns true or false specifying whether or not the input source was able to be changed.
|

​iconForLayoutOrMethod​

Signature
hs.keycodes.iconForLayoutOrMethod(sourceName) -> hs.image object
Type
Function
Description
Gets an hs.image object for a given keyboard layout or input method
Parameters
  • sourceName - A string containing the name of an input method or keyboard layout
Returns
  • An hs.image object, or nil if no image could be found
Notes
  • Not all layouts/methods have icons, so you should assume this will return nil at some point

​inputSourceChanged​

Signature
hs.keycodes.inputSourceChanged(fn)
Type
Function
Description
Sets the function to be called when your input source (i.e. qwerty, dvorak, colemac) changes.
Parameters
  • fn - A function that will be called when the input source changes. No arguments are supplied to the function.
Returns
  • None
Notes
  • This may be helpful for rebinding your hotkeys to appropriate keys in the new layout
  • Setting this will un-set functions previously registered by this function.

​layouts​

Signature
hs.keycodes.layouts([sourceID]) -> table
Type
Function
Description
Gets all of the enabled keyboard layouts that the keyboard input source can be switched to
Parameters
  • sourceID - an optional boolean, default false, indicating whether the keyboard layout names should be returned (false) or their source IDs (true).
Returns
  • A table containing a list of keyboard layouts enabled in System Preferences
Notes
  • Only those layouts which can be explicitly switched to will be included in the table. Keyboard layouts which are part of input methods are not included. See hs.keycodes.methods.

​methods​

Signature
hs.keycodes.methods([sourceID]) -> table
Type
Function
Description
Gets all of the enabled input methods that the keyboard input source can be switched to
Parameters
  • sourceID - an optional boolean, default false, indicating whether the keyboard input method names should be returned (false) or their source IDs (true).
Returns
  • A table containing a list of input methods enabled in System Preferences
Notes
  • Keyboard layouts which are not part of an input method are not included in this table. See hs.keycodes.layouts.

​setLayout​

Signature
hs.keycodes.setLayout(layoutName) -> boolean
Type
Function
Description
Changes the system keyboard layout
Parameters
  • layoutName - A string containing the name of an enabled keyboard layout
Returns
  • A boolean, true if the layout was successfully changed, otherwise false

​setMethod​

Signature
hs.keycodes.setMethod(methodName) -> boolean
Type
Function
Description
Changes the system input method
Parameters
  • methodName - A string containing the name of an enabled input method
Returns
  • A boolean, true if the method was successfully changed, otherwise false