Skip to content

Xarty with AHK

Jump to bottom
CarrieForle edited this page Jun 12, 2023 · 27 revisions

Introduction

There are 2 AHK (AutoHotKey) versions available.

  • Xarty.ahk
  • Xarty-extend.ahk

The difference between them is Xarty-extend.ahk has extend layer and compose features, while Xarty.ahk is plainly remapping, which is a lot simpler. There isn't too much for Xarty.ahk. Everything works like what you expect how a typical keyboard to work. For reference, You may refer to the official AHK documentation for more technical and specific details of the remapping.

Xarty-extend.ahk

There is a lot to say about Xarty-extend.ahk. That's actually why I wrote this Wiki in the first place. The goal is to tell what you should expect when you are using this version of the layout, what how those fancy works, without having to learn AHK and going through the rather awful spaghetti source code. It's best to have an general idea about extend layers and compose before you move onward, as a good implementation detail will be addressed.

Features

Xarty-extend.ahk supports 3 extend layers and compose feature. You cannot customize the extend layers, but you can write your own text to compose with compose.txt, which will be automatically generated on the first run or when compose.txt is not found in the working folder. Refer here for more details about compose.txt.

Extend Layers

There are 3 extend layers in Xarty-extend.ahk. Few things need to know:

  • CapsLock is extend key. Pressing it will not enable Caps Lock.
  • Shift and Ctrl are modifier keys. Their functionalities remain the same.

Every extend layer shares the common features:

  • You activate the extend layer by pressing extend key. By a combination with different modifier keys, you activate a different extend layer. You essentially are choosing the extend layer you are activating by modifier key. The order you press extend key and modifier keys does not matter. You may press other keys when you are to activate the extend layer, this is not necessary, however.
  • Only 0 or 1 extend layer can be activated at a time.
  • To have an extend layer stay active, keep pressing the extend key. Modifier keys are not required for it to stay active. They are only mandatory at the moment of activating it.
  • To deactivate an extend layer, you can:
    • Release extend key.
    • Activate a different extend layer by pressing a different modifier key while extend key is kept pressed.

Few things to note:

  • Pressing extend key and both modifier keys is treated as if no modifier key is pressed, essentially activate the extend layer that required only extend key being pressed.
  • It's not necessary to press extend key and a modifier key at the same time to activate a different extend layer. While pressing extend key and a different modifier key can activate different extend layers. There's a 150±10ms window where you can release the modifier key and press extend key, which will still have the chosen extend layer activated.

Compose

Compose key is the right Windows key (RWin). When you press compose key, nothing will happen, not even the start menu will show up. RWin completely lost its original functionality for compose feature, just like CapsLock for extend layer.

To use compose feature, type one of the recognized sequence in compose.txt and press compose key (within 2 seconds after the moment sequence is finished). Upon pressing, the sequence will be translated to the dedicated text.

For example, btw is one of the sequence predefined in compose.txt. Type this sequence correctly (mind the case), followed by a press of compose key, and btw will be translated to By the way. You can modify compose.txt and create your own compose sequence (or delete the predefined ones). A restart of the layout is required for the change to be made into practice.

The translation is essentially enough backspace presses to remove the entire sequence, and type the dedicated text, depend on the length of the dedicated text, the translation can take some time.

Compose.txt

Under 3 condition will the script fail to load compose.txt:

  1. No read permission
  2. = is not present in one of the keypair.
  3. Any of the sequences is more than 10 letters.

When compose.txt is failed to load, the script is terminated.

When compose.txt is successfully loaded. The script will translate keypairs to sequence and its dedicated text. It assumes 1 keypair per line. The translation, from left to right, works as follows:

  1. Find the rightmost = until it reach a quotation mark (', ") where between = and the quotation mark is arbitrary number of tabs and space or none. Treat this found = as delimiter.
  2. Save the string at the left of the delimiter. Trim the leading and trailing spaces and tabs. Save it as one of the recognized sequence.
  3. Save the string at the right of the delimiter. Trim the leading and trailing spaces and tabs. if its first and last character are the same quotation mark. remove them. Save it the dedicated text to the saved recognized sequence.

Few things to note:

  • The script does not ignore comments. That is, anything after # or ; is not ignored and will be a part of the translation.
  • The script does not escape character. This implies that you can't make either sequence or dedicated text contain newline.

Example keypairs:

Clone this wiki locally