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

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
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
Signature
hs.keycodes.currentMethod() -> string
Type
Function
Description
Get current input method
Parameters
  • None
Returns
  • Name of current input method, or nil
| 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.
|
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
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
Last modified 1mo ago