Skip to content

Xarty with AHK

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

Introduction

There are 2 AHK (AutoHotKey) versions available.

  • Xarty.ahk
  • Xarty-extend.ahk

In a nutshell, Xarty-extend.ahk is the enhanced version of Xiart.ahk.

Xarty.ahk

Xarty.ahk implements only the layout and 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 are interested.

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, reading onward to know how the features are implemented in Xarty-extend.ahk.

On startup, the script will generate 2 files.

  • compose.txt
  • xarty_config.ini

When the script cannot find any of the files, a new corresponding one is generated.

compose.txt is explained later in the page. xarty_config.ini is the configuration file for the script. There are descriptions for each property in the file, and I'm not writing that again in Wiki.

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. 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. With 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 an 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 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 small window where you can release the modifier key and press extend key and still make it activated.

Compose (noun)

Compose key is AppsKey (the key right to right Windows key). When you press compose key, nothing will happen. Appskey 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. 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.

A few things to note:

  • Case matters. BTW is not btw.
  • You can do backspace, Compose will work that out. Although sometimes it's inaccurate, meaning the actual text and the text seen by the script can be out of sync, in which case you have to re-type the whole sequence.
  • backspace with Ctrl, Alt, Ctrl + Shift, Ctrl + Alt, Ctrl + Shift + Alt will reset Compose. Text navigation with arrow keys, Home, End will also reset Compose.
  • The moment after sequence is complete typing, you have a window for pressing compose key to have the translation happen. After that, Compose is reset.

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

A 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 20 characters. Remember the key starts at the second character and the first character is to define the keypair's delimiter.

  • 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 value as a keypair. For example:
    ==! ❌ ==! is not a valid keypair.

  • 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 #2, #3, #4 happens, a dialog will pop up, asking you to terminate the script or ignore the invalid keypair and keep going.

At the end, take a look at my compose.txt to give you some customization ideas.

; This file is used to create compose key pairs
; For details and specification, refer to https://github.com/CarrieForle/xarty/wiki/Xarty-with-AHK#composetxt

='c=©
.<=.≤
.>=.≥
.!=.≠
=twf=🇹🇼

; Right to left symbol
=rtlrtl=‮

=pi=π
=inf=∞
='r=®
=tm=™
=TM=™
=ae=æ
=-+=±
=+-=±
=*=×
=/=÷
='name=CarrieForle
='[email protected]
='site=https://github.com/CarrieForle
='site=github.com/CarrieForle
=x''=(´・ω・`)
=x'=(`・ω・´)
=x'>=(ゝ∀･)
>x'=>(´≖◞౪◟≖)
=x'!=Σ( ° △ °)
=x'!!=(゜皿。)
=x'bear= ฅʕ •ᴥ•ʔฅ 
=x'cat=( =^･ω･^=)丿
=x'Cat=( =ʘᆽʘ=)ʃ
=x'cry= ( ಥ╭╮ಥ) 
=x'Cry= ೭( ಥ﹏ಥ)೨
=x'dance=♪♫ (＊ﾉ・◡・)ﾉ ♫♩ ┏(・o･＊)┛ ♫♪
=x'Dance=♪～└[∵┌]└[･▥･]┘[┐∵]┘～♪
=x'girl=(✿◠‿◠)
=x'ha= σ`∀´)σ
=x'owl=( のvの) c[_]
=x'owo=( Θώθ)
=x'Owo=( ʘωʘ)♥
=x'panic=(((ﾟДﾟ;)))
=x'joy=∩(●'‿'●)∩
=x'Joy=∩(◕‿◕｡)∩～♪
=x'lol=(ﾟ∀。)
=x'thup=d( ^◇^)b
=x'Thup=(b￣◇￣)b
=x'what= ಠ_ಠ
=x'why=ლ(ಠ益ಠ ლ)
=x'Why=⊂(;⊙д⊙)つ
=x'shock=(ʘ_ʘ;)
=x'Shock=(ʘ言ʘ╬)
=x'yo=ლ( • ̀ω•́ )っ
Clone this wiki locally