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 (noun)

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, just like CapsLock for extend layer.

To use Compose, 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

compose.txt is the file storing every keypairs for Compose. a keypair is essentially two strings. One is the key, and the other is the value. Every keys are unique, meaning that when we get to know the key, we can also know its to value since there is no other identical keys pointing to a different value. This is essentially what Compose is doing. By typing a unique sequence (key), we can handily translate it to another text (value) almost instantly.

compose.txt is essentially bunch of text, where each keypairs are separated by newline. It translates 1 line of text to 1 keypair, from left to right, with steps as follow:

  1. Grab the first character of the string. This is identified as the delimiter
  2. Split the string by the first occurrence of the delimiter (or the second, if you count the first character as one).
  3. Remove the first character (the delimiter) of the left string. The script stores it as a key. The right string remains the same, which the script stores as the key's value.

There are exceptions. If the first character of a line is ;, space, tabs, or if a line is completely empty, that line is ignored and it will not be treated as a keypair, essentially allow you to comment a line in the file by having one of these special characters in the beginning of that line.

Here is an example of keypairs:

=btw=By the way → btw is the key. By the way is the value =name=CarrieForle → name is the key. CarrieForle is the value >pi=>3.14159 → pi= is the key. 3.14159 is the value

Few things to note:

  • The translation is literal, i.e., It does not remove the leading or trailing space and tabs. For example:
    >^ > (= ^ =) → ^ is the key. (= ^ =) is the value.

  • You cannot have an empty key (string length is 0) or an empty val as a keypair. For example:
    ==! → ==! is not a valid keypair. (key is empty)

  • It is recommended to select a character that is not in the value as the delimiter of the keypair. This will greatly improve the readability so you won't be confused.

  • You can use Unicode characters for both key and value for any number of keypairs. However, it's unadvised for to have a Unicode character as a delimiter, as the script will not catch this and likely fail to store the keypair correctly. For example:
    =smile=😀 → smile is the key. 😀 is the value.

  • Although it's stated every key is unique. You can have keypairs whose key are identical. The script will select the bottommost keypair as the one in run when this happens. However, it's advised that you not do that and modify the existing keypair instead. For example:

    ...
=std=sexually transmitted disease
=std=standard
...

std is the key. standard is the value. (not a wise choice of name, CPP)

Under the following conditions, the script will fail to load compose.txt or a keypair:

  1. No read permission
  2. No delimiter is found in one of the keypairs
  3. No delimiter is found in keypairs

When the second or the third happens, a dialog will pop up, asking you to terminate the script or ignore the invalid keypair and keep going.

Clone this wiki locally