Skip to content

Xarty with AHK

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

Introduction

There are 2 AHK (AutoHotKey) versions available.

  • Xarty.ahk
  • Xarty-extend.ahk

Xarty.ahk

Xarty-extend.ahk is the enhanced version of Xarty.ahk. Xarty.ahk implements only the layout, with a few shortcut to suspend (Left Alt + Right Alt), reload (Ctrl + Shift + 5) and terminate (Ctrl + Shift + `) the script. The remapping detail is well written in the official AHK documentation if you interest.

Xarty-extend.ahk

Xarty-extend.ahk, having the same shortcut, implements extend layer and compose features. Allow a more flexible use of the keyboard. In contrast, it's advised that you understand the gist of these features before you use this version of the layout. Having a general idea about those, you may read onward to know how the features are implemented in Xarty-extend.ahk.

Features

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

Extend Layers

There are 3 extend layers in Xarty-extend.ahk. For this feature, a few keys are reserved:

  • CapsLock is extend key. Pressing it will not enable Caps Lock.
  • Shift and Ctrl are modifier keys. Their functionalities remain the same.
  • You cannot change these keys (without directly modifying the AHK script).

Every extend layer shares some 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. If you type a sequence not recognized by compose.txt, nothing will happen.

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 a key longer than 10 characters. Remember the key starts at the second character because the first character defines the keypair's delimiter. For example:
    =thisisokay=good ✅ thisisokay is the key. good is the value.
    =thisisnotok=bad ❌ thisisnotok is too long for a key (> 10).

  • As mentioned above, case matters. BTW and btw are different, distinct keys.

  • 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)

  • The longer key (longer text length) has higher precedence and will be checked first when a compose attempt happened. This is to make sure the longer text will not be hidden by shorter key when the key overlap. For example:

    ...
=f=press F to pay respects
=don't f=lol
...

    Typing don't f and press compose will output lol, not don't press F to pay respects.

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
  4. one of the key in keypairs is longer than 10 characters, as mentioned here.

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