Smart macros enable the advanced customization of your UHK and its modules.
This documentation is a reference for smart macros, but let's start with a quick guide on how to use them.
See the following screenshot, which shows a macro named $onInit
containing a command macro action that contains multiple macro commands:
$onInit
is a special macro name. It's a macro event that executes each time your UHK gets powered and when you save its configuration.
set module.trackball.baseSpeed 1
is a macro command that sets the base speed of the trackball module to 1
.
Comments are allowed after the //
characters per line. You can comment out commands or add helpful comments.
Macro commands work in any macros, not only in macro events, and you can bind them to any key. This way, you can make Fn + 1 set your trackball base speed to 1
and make Fn + 2 set it to 2
, for example.
After creating a macro command action, it becomes in-place editable, so you can simply click into it to edit its commands. You'll likely save your macro commands many times to tweak them, in which case, it's quicker to hit Ctrl + S instead of clicking the "Save to keyboard" button.
When your UHK encounters an invalid macro command, its LED display will show ERR
. The printStatus
command reveals the cause of the error. Create a macro named printStatus
containing the printStatus
command:
Bind the macro to a shortcut, such as Fn + ` :
Then open an editor and hit Fn + ` to see the error message.
Last but not least, when a command macro action is selected, many interactive widgets, such as sliders, comboboxes, and checkboxes appear in this documentation, some depending on the currently attached modules. By interacting with these widgets, the relevant commands appear in the current command macro action without writing any code:
Macro events are specially named macros that are executed on select occasions. When your UHK powers up and when you save its configuration, the relevant macro events are executed in the following order:
$onInit
event is always executed.$onKeymapChange {keymapId}
event, such as $onKeymapChange QWR
, is executed when a keymap, such as QWR
, is activated.Following is the list of available macro commands.
When the UHK encounters an invalid macro command, the LED display will display ERR
, and the status buffer will contain the error message. This command "types" the content of the status buffer for debugging purposes.
We recommend binding this command to a shortcut, such as Fn + `, for easy accessibility and triggering it in a text editor when encountering an error.
The trackpoint module sometimes makes the mouse cursor drift. Drifting happens because the auto-calibration mechanism of the trackpoint hardware sometimes kicks in when resting a finger on the trackpoint for several seconds. This issue also affects IBM ThinkPad trackpoints, but given their position, they're not as affected by resting fingers as the UHK trackpoint module.
Avoiding resting fingers on the trackpoint should make this a non-issue. Alternatively, this command resets the trackpoint and recovers it from drift conditions.
The set
command sets variables that affect the behavior of the UHK and its modules. This command has many different parameters, which are explained below.
Sets module speeds. These settings are not useful for the key cluster due to the limited resolution of its mini trackball.
Syntax isset module.{module}.{property} {value}
{module}
is of trackball
, trackpoint
, touchpad
{property}
is of
baseSpeed
: Increasing baseSpeed
increases module sensitivity evenly in both low speeds and high speeds.speed
: Increasing speed
increases module sensitivity unevenly, depending on xceleration value.xceleration
: xceleration
exponent modulates speed
's contribution. Increasing xceleration
decreases sensitivity at low speeds while also increasing sensitivity at high speeds.property name | min | max | trackball default | trackpoint default | touchpad default |
---|---|---|---|---|---|
baseSpeed |
0.0 | 10.0 | 0.5 | 0.0 | 0.5 |
speed |
0.0 | 10.0 | 0.5 | 1.0 | 0.7 |
xceleration |
0.0 | 1.0 | 1.0 | 0.0 | 1.0 |
{value} float
: The range is dependent on {property}
.{{moduleDescriptions[module]}} | |
---|---|
{{speedProp.desc}} |
|
Sets module speed divisors. These settings are not useful for the key cluster due to the limited resolution of its mini trackball.
Syntax isset module.{module}.{property} {value}
{module}
is of keycluster
, trackball
, trackpoint
, touchpad
{property}
is of
caretSpeedDivisor
: Distance (in pixels) that needs to be covered to produce one event in caret mode. The higher the value, the slower the caret speed. {value}
ranges from 1
to 100
and defaults to 16
.scrollSpeedDivisor
: Distance (in pixels) that needs to be covered to produce one event in scroll mode. The higher the value, the slower the scroll speed. {value}
ranges from 1
to 100
and defaults to 8
.pinchZoomDivisor
: Distance (in pixels) that needs to be covered to produce one event while using the touchpad's pinch-to-zoom gesture. The higher the value, the larger gesture is needed for zooming. {value}
ranges from 1
to 10
and defaults to 4
.{value} float
: The range is dependent on {property}
.{{moduleDescriptions[module]}} | |
---|---|
{{speedProp.desc}} |
|
When first moving in a navigation mode with axis locking enabled, the axis is locked to one of the axes. The following variables define axis locking behavior.
Syntax isset module.{module}.{property} {value}
{module}
is of keycluster
, trackball
, trackpoint
, touchpad
{property}
is of
{scrollAxisLock} boolean
: 0
disables scroll axis locking, 1
(default) enables scroll axis locking.{caretAxisLock} boolean
: 0
disables caret axis locking, 1
(default) enables caret axis locking.{axisLockFirstTickSkew} float of 0.5 to 2.0
: The first event produced when the axis is not yet locked can be adjusted as follows.
{value}
to 0.5
to require a stronger push at the beginning of a movement. Useful for the mini trackball to not produce an unwanted move event when trying just to click it. With this value, it will require two roll events to activate.{value}
to 2.0
to make the first event more responsive. For example, caret mode will make the first character move with a very gentle push, while consecutive activations will need greater momentum.axisLockSkew float of 0.5 to 2.0
: Affects how hard it is to change the locked direction once the axis is locked. With {value}
of 0.5
, you have to produce a stroke that goes at least twice as fast in the non-locked direction compared to the locked one. A {value}
of 2.0
allows changing axes easily.{value} float
: The range is dependent on {property}
.{{moduleDescriptions[module]}} | |
---|---|
Scroll axis lock enabled |
|
Caret axis lock enabled |
|
Axis lock first tick skew |
|
Axis lock skew |
|
Inverts the vertical scroll direction per module.
Syntax isset module.{module}.invertScrollDirection {value}
{module}
is of keycluster
, trackball
, trackpoint
, touchpad
{value} boolean
: 0
leaves axes unswapped, 1
swaps axes.{{moduleDescriptions[module]}} | |
---|---|
Invert scroll direction |
Swaps the X and Y axes of the key cluster's mini trackball, which can be useful because it's easier to roll the mini trackball along the horizontal axis with the thumb. This setting is available for all modules, but we only recommend using it with the key cluster.
Syntax isset module.{module}.swapAxes {value}
{module}
is of keycluster
, trackball
, trackpoint
, touchpad
{value} boolean
: 0
leaves axes unswapped, 1
swaps axes.Controls the behavior of the touchpad's pinch-to-zoom gesture.
Syntax isset module.touchpad.pinchZoomMode {navigationMode}
{navigationMode}
is of media
, caret
, zoom
, zoomPc
, zoomMac
, none
. The default zoom
navigation mode usually works fine, but extra + and - characters may be displayed by some applications, in which case the more specific zoomPc
or zoomMac
mode should be used. The media
navigation mode adjusts the volume. See set » module navigation modes for more details.Touchpad pinch-to-zoom mode |
|
UHK modules support the following navigation modes, which are mapped by layer and module:
set module.{moduleId}.navigationMode.{layerId} {navigationMode}
{moduleId}
is of keycluster
, trackball
, trackpoint
, touchpad
{layerId}
is of base
, mod
, mouse
, fn
, fn2
, fn3
, fn4
, fn5
{navigationMode}
is of cursor
, scroll
, caret
, media
, zoom
, zoomPc
, zoomMac
, none
Layer | {{moduleDescriptions[module]}} |
---|---|
{{layer}} |
|
Customize caret or media navigation mode behavior by binding directions to shortcuts or macros.
Syntax isset navigationModeAction.{mode}.{direction} {action}
{mode}
is of caret
, media
, zoomPc
, zoomMac
{direction}
is of up
, down
, left
, right
{action}
is of macro {macroName}
, keystroke {shortcut}
{macroName}
is the case-sensitive macro name that must not contain spaces.{shortcut}
is of {modifiers}
, {key}
, {modifiers}-{key}
{modifiers}
is formatted as [L|R]{S|C|A|G}
of which [L|R]
is an optional left or right side modifier and {S|C|A|G}
is Ctrl, Alt, Shift, or Gui.{key}
describes the key, such as enter
. See the full range of keys in the examples below.{mode} : |
|
{direction} : |
set navigationModeAction.{{navigationModeActionMode}}.{{navigationModeActionDirection}} macro YourMacroName
{shortcut} : |
|
{key} : |
set navigationModeAction.{{navigationModeActionMode}}.{{navigationModeActionDirection}} keystroke {{getScancode()}}
Controls whether modifier layers are triggered by the left, right, or either modifier.
Syntax isset modifierLayerTriggers.{layer} {modifiers}
{layer}
is of shift
, alt
, super
, ctrl
{modifiers}
is of left
, right
, both (default)
Layer | Modifier trigger |
---|---|
{{modifier}} | |
Except for axisSkew
, these settings are already featured on Agent's "Mouse key speed" page, which should be used primarily. These settings are still useful for keymap-specific mouse key speed settings.
set mouseKeys.{mode}.{property} {floatValue}
{mode}
is of move
, scroll
{property}
is of
initialSpeed
: When mouse movement begins, this is the starting speed.baseSpeed
: When a mouse key is held, speed increases until it reaches this speed.initialAcceleration
: The rate of acceleration from the initial speed to the base speed.deceleratedSpeed
: This speed is used when using a mouse key along with the decelerate key.acceleratedSpeed
: This speed is used when using a mouse key along with the decelerate key.axisSkew
: Multiplies horizontal axis and divides vertical axis. It can be useful for wide or tall screens. {floatValue}
is reasonable from 0.5
to 2.0
, and defaults to 1.0
Pointer speed | Scroll speed | |
---|---|---|
{{prop.desc}} |
|
|
By default, the mouse pointer is faster diagonally than horizontally or vertically when using the mouse keys. This setting slows down the pointer diagonally when the mouse keys are used, so its speed matches horizontal and vertical speeds.
Syntax isset diagonalSpeedCompensation {compensationEnabled}
{compensationEnabled} boolean
: 0
disables compensation, 1
enables compensation.This setting affects the behavior of shortcuts on non-base layers. For example, if Mod + d is mapped to Alt + Tab and Mod + d is pressed, Alt + Tab is triggered, then if d is released while Mod is still held, Alt is held, too; hence, the modifier is sticky.
Syntax isset stickyModifiers {stickyMode}
{stickyMode}
is of
smart (default)
: Make only a select few shortcuts sticky, namely when Alt, Super, or Ctrl is pressed along with ~, Tab, or an arrow key.never
: Make every key non-sticky.always
: Make every key sticky.Controls the double tap timeout for layer locking.
Syntax isset doubletapTimeout {timeout}
{timeout} integer of 0 to 1000
: Timeout in milliseconds.Allows slowing down keyboard output. This setting is handy for lousily written RDP clients and other software which scans keys once a while and processes them in the wrong order if multiple keys have been pressed in between.
This setting adds a delay whenever a basic USB report is sent. During this delay, the key matrix is still scanned, and keys are debounced, but instead of activating, the keys are added into a queue to be replayed later.
Syntax iskeystrokeDelay {delay}
{delay} integer of 0 to 1000
: Delay in milliseconds. The recommended value is 10
if you have issues with RDP missing modifier keys, 0
otherwise.Allows triggering chorded shortcuts in arbitrary order. For example, if A + Ctrl is pressed instead of Ctrl + A, the keyboard will still send Ctrl + A if the two key presses follow within the specified time.
Syntax isset chordingDelay {delay}
{delay} integer of 0 to 255, defaults to 0
: Delay in milliseconds.Enable/disable all LEDs.
Syntax isset leds.enabled {ledStatus}
{ledStatus} boolean
: 0
disables LEDs, 1
enables LEDs.Set the brightness of all LEDs.
Syntax isset leds.brightness {brightness}
{brightness} float
: Multiplies the brightness of the per-key backlights and LED display.Set timeout, after which all LEDs fade out to save power until the next user interaction.
Syntax isset leds.fadeTimeout {timeout}
{timeout} integer, defaults to 0
: 0
means disabled fade timeout. Otherwise, the timeout value is specified in seconds.LED fade timeout |
|
There are extended macro commands available besides the commands mentioned here, enabling numerous advanced features.
We plan to add the extended commands to this documentation.