How to Use

How to Use

Overview

Upon installation, it will create a shortcut to Typoon in the startup program folder, which is %programdata%/Microsoft/Windows/Start Menu/Programs/StartUp on Windows.

When started, it creates a system tray icon. Clicking on this icon will pop up a menu containing Turn On/Off, Open Config, Open Match, and Exit. The 'Open *' items will open the config file and the match file with the default program repectively.

You can toggle on/off with ctrl-alt-shift-S by default. You can change the combination in the config file.

So, how can you specify what texts should be replaced to what texts? You do it in the match file. A match file is basically a list of pairs of a trigger and a replace, possibly with some options. It's in the JSON5 format. For a detailed explanation, jump to the match part.

If you are looking for a way to change some options, you should check out the config file. It's also in the JSON5 format. Do the notifications bother you? You can turn them off! Does the toggle on/off hotkey collide with a program you use? You can change it! For a complete list and detailed explanations, jump to the config part.

You can make Typoon to be automatically turned on/off or to use different match files depending on the program currently selected. To get more info about this, jump to here.

Match

Matches are the core of the program. They denote what texts should be replaced with what texts.

A match consists of one or more triggers, a replacement text, and zero or more options.

The default match file is in %appdata%/Typoon/match (Windows). Alternatively, you can click on the system tray icon and select Open Match to open the match file with the default program.

You can have it wherever you want, you just need to specify the path to the match file in the config.

If you prefer to learn by examples, you might want to jump right to the example part.

Trigger

A trigger specifies the text to be detected and should be replaced. A match should have 1 or more triggers. If there is only 1, you can set it with the trigger field. For 1 or more triggers, use the triggers field and put them in a list.

Replace Text

It specifies the replacement text that will take place in the trigger text. Set it with the replace field. Every match should have a replace, replace_image, or replace_command.

Cursor Position

When specifying the replacement text, you can optionally indicate the position of the cursor. The default indicator is |_|, but you can change it to whatever you want in the config file.

Replace Image

It specifies the path to the replacement image that will take place in the trigger text. Set it with the replace_image field. It pastes the image with the 'Paste' function. Every match should have a replace, replace_image, or replace_command.

Formats supported: BMP, GIF, JPEG, PNG, TIFF, Exif, WMF, and EMF

Replace Command

It specifies the command to be run which output replaces the trigger text. Set it with the replace_command field. Every match should have a replace, replace_image, or replace_command.

Options

All toggle options are defaulted to false.

Options that affect triggers

• case_sensitive

  If set to true, makes the trigger case sensitive.

• word

  If set to true, makes the trigger detected only when the text is separated to be a word.

• full_composite

  Hangeul Only. If set to true, makes the trigger detected only when the composition of the last letter is finished.

  Valid only if the last letter of the trigger string is a Hangeul letter and word is false.

Options that affect replacements

• propagate_case

  If set to true, propagates the case of the string that triggered the match to the replacement string.

  Valid only if case_sensitive is false and there is at least one cased alphabet in the trigger string.

• uppercase_style

  Can be either capitalize_words or first_letter. If set to capitalize_words, the first letters of each words are capitalized when they should be. If set to first_letter, Only the first letter of the entire string will be capitalized even if the string is multi-word.

  Valid only if propagate_case is true.

• keep_composite

  Hangeul Only. If set to true, makes the last letter to be in-composition mode after replacement.

  Valid only if the last letter of the replacement string is a Hangeul letter, full_composite is false, and the cursor position of the replacement string is at the last(unset).

Groups

You can group some matches to share common options. Put the data according to the following hierarchy: (root)

• groups
  • (entry 1)
    • (option 1)
    • (option 2)
    • matches
  • (entry 2) ...

Import

You can imports other match files. If the path is relative, it'll find from the current match file. List them in the imports field.

Example

{
    // Imports all the match files listed in here.
    imports: ['C:/some/other/match_file.json5', '../another/match_file.json5'],

    groups: [
        {
            case_sensitive: true,
            // All the triggers of the matches below are now case sensitive.
            matches: [
                {
                    trigger: 'some',
                    replace: 'words'
                },
                {
                    trigger: 'other',
                    replace: 'words',
                    word: true,  // This match is now effectively case_sensitive + word
                }
            ]
        },
        {
            ...
        }
    ],

    matches: [
        {
            trigger: 'aaaa',
            replace: 'AAAA',
            case_sensitive: true,
            // `aaaa` -> `AAAA`.
            // Typing `Aaaa` will *NOT* be replaced, nor `AaAa` does.
        },
        {
            triggers: ['alth', 'alh'],
            replace: 'although',
            word: true
            // `AlTh` + a non-alphanumeric letter -> `although` + the letter typed.
            // `alh` + a non-alphanumeric letter -> `although` + the letter typed.
        },
        {
            trigger: 'recieve',
            replace: 'receive',
            propagate_case: true
            // `recieve` -> `receive`.
            // `Recieve` -> `Receive`.
            // `RECIEVE` -> `RECEIVE`.
        },
        {
            trigger: ';tbh',
            replace: 'to be honest',
            word: true,
            propagate_case: true,
            uppercase_style: 'capitalize_words'
            // `;tbh` + a non-alphanumeric letter -> `to be honest` + the letter typed.
            // `;Tbh` + a non-alphanumeric letter -> `To Be Honest` + the letter typed.
            // `;TBH` + a non-alphanumeric letter -> `TO BE HONEST` + the letter typed.
        },
        {
            trigger: ';sti',
            replace: 'static_cast<int>(|_|)'
            // `;sti` -> `static_cast<int>()`, and the cursor will be placed between the braces.
        },
        {
            trigger: '스빈다',
            replace: '습니다',
            keep_composite: true
            // `스빈다` -> `습니다`, and `다` will be in-composite mode. 
            // So, if you type `스빈답`, it will be `습니답`. Without the `keep_composite`, it will be `습니다ㅂ`.
        },
        {
            trigger: '가나',
            replace: 'Ghana',
            full_compisite: true
            // `가나` + finishing the composition -> `Ghana` + letters that finished the composition if any.
            //    - `가나` + toggling Korean/English -> `Ghana`
            //    - `가나다` -> `Ghana다`. (If you don't want it, add the `word: true` option)
            //      It won't be replaced until you type the last `ㅏ` so that the composition of `나` is finished.
            //    - `가나 ` -> `Ghana ` (There's a trailing space)
            // Typing `가난` will *NOT* be replaced.
        },
        {
            trigger: '혼합mixed',
            replace: 'mixed혼합',
            keep_composite: true
            // `혼합mixed` -> `mixed혼합`. Also, the type mode will be in Korean mode.
        },

        {
            trigger: ';pepe',
            replace_image: 'C:/path/to/pepe.jpg'
            // It pastes the image of the given path when you type ;pepe.
        },
        {
            trigger: ';datetime',
            replace_command: 'echo %date%%time%'
            // It runs the `echo %date%%time%` when you type ;datetime and replace the trigger with the output of the command.
        },
    ]
}

Config

The config file is located in %appdata%/Typoon on Windows. Alternatively, you can click on the system tray icon and select Open Config to open the config file with the default program.

match_file_path

The path to the match file. It can be either relative or absolute. If it's relative, it finds from where the config file is (%appdata%/Typoon on Windows).

Defaulted to match/matches.json5.

max_backspace_count

How many backspaces to keep track of.

For instance, if there's a trigger abc and the value of this config is 5, typing abddddd then deleting all d's then typing c will be detected, but if there were more d's, it wouldn't have been detected.

Defaulted to 5.

cursor_placeholder

The placeholder to use in the replacement text to indicate the cursor's position.

Defaulted to |_|.

notify_config_load

Whether to show a notification when a config file is (re)loaded.

Defaulted to true.

notify_match_load

Whether to show a notification when a match file is (re)loaded.

Defaulted to true.

notify_on_off

Whether to show a notification when Typoon is turned on and off.

Defaulted to false.

hotkey_toggle_on_off

The hotkey to toggle Typoon on and off. If you don't want to set a hotkey for this feature, simply delete this field entirely (removing the key field is enough, actually).

Defaulted to ctrl-alt-shift-s.

• ctrl - Whether the control key should be held.
• alt - Whether the alt key should be held.
• shift - Whether the shift key should be held.
• win - Windows only. Whether the Windows key should be held. Note that this is not recommended since hotkeys involving the Windows key are reserved.
• cmd - Mac only. Whether the command key should be held. *Note that Mac is not supported currently.*
• key - The main key. Case insensitive. Refer to the key list for the key-text pairs.

hotkey_get_program_name

The hotkey to copy the name of the current program to the clipboard. It can be used for program-based config below. The rest is the same as the above.

Defaulted to ctrl-alt-shift-d.

program_overrides

Overriding configs depending on the program currently active. It's a list with compounds comprised of:

• programs: A list of the name of the programs. They can be obtained with the hotkey above.
• disable: If set to true, Typoon will be disabled while you're using these programs.
• match_file_path: If set, the match file residing at this path will be used instead of the default one.
• includes: A list of the match file paths that will be combined to the base match file.
• excludes: Prevent the match files that are being used from importing these match files.

Example

{
  match_file_path: "c:/some/path/to/custom/match/file.json5",
  max_backspace_count: 2,
  cursor_placeholder: "$|$",  // espanso style!
  notify_config_load: false,
  notify_match_load: true,
  notify_on_off: true,
  hotkey_toggle_on_off: {
    ctrl: true,
    alt: true,
    shift: true,
    key: "O"
  },  // The hotkey for toggling on and off is now ctrl-alt-shift-o
  hotkey_get_program_name: {
    ctrl: true,
    alt: true,
    key: "p"
  },  // The hotkey for getting the name of the current window is now ctrl-alt-p.
  program_overrides: [
    {
      programs: [
        "Discord",
        "Microsoft Visual Studio 2022"
      ],
      includes: [
        'match/discord.json5',
      ]
    },  // When you're using Discord and Visual Studio, match/discord.json5 will be added on top of the base match file.
    {
      programs: [
        "KakaoTalk",
      ],
      disable: true
    },  // Disables Typoon when using KakaoTalk.
    {
      programs: [
        "Chrome",
      ],
      excludes: [
        'match/images.json5',
      ]
    },  // Ignore the import of match/images.json5 while using Chrome.
    {
      programs: [
        "Notepad",
      ],
      match_file_path: "match/discord.json5",
    },  // Use the match/discord.json5 instead of the default one when using Notepad.
  ]
}