Shortcuts

Custom text expansion shortcuts for faster typing

Overview

Shortcuts (Gõ tắt) allow you to expand abbreviations into full phrases automatically.

vn  + Space → Việt Nam
ko  + Space → không
hcm + Space → Hồ Chí Minh

How It Works

Trigger Modes

Shortcuts can be triggered in two ways:

Word Boundary

Most common mode - triggers when you press Space or punctuation after the trigger word.

Type: vn + Space
Result: Việt Nam

This is the default mode and recommended for most use cases.

Immediate

Instant mode - triggers immediately after typing the trigger word (no Space needed).

Type: dc
Result: được (immediately)

Use carefully! Immediate mode may interfere with normal typing if the trigger is a common word prefix.

Smart Case Matching

Shortcuts automatically match the case of your input:

Input	Output	Case Type
vn	Việt Nam	lowercase
VN	VIỆT NAM	UPPERCASE
Vn	Việt Nam	Title Case
ko	không	lowercase
KO	KHÔNG	UPPERCASE
Ko	Không	Title Case

Issue #86: Smart case transformation works for all shortcuts, including Vietnamese diacritics.

Creating Shortcuts

Built-in Shortcuts

Gõ Nhanh comes with these default shortcuts:

vn  → Việt Nam
hcm → Hồ Chí Minh
hn  → Hà Nội
dc  → được
ko  → không

Default shortcuts are currently disabled in the latest version. You can add them back manually if needed.

Add Custom Shortcuts

1. Open Settings → Shortcuts
2. Click + Add Shortcut
3. Enter:
   • Trigger: Short text to type (e.g., tphcm)
   • Replacement: Full text to expand (e.g., Thành phố Hồ Chí Minh)
   • Trigger mode: Word boundary or Immediate
   • Input method: All, Telex only, or VNI only
4. Click Save

Shortcut Limits

Max Replacement Length

255 characters (UTF-32 codepoints)

Each Vietnamese character with diacritics (ồ, ế, ẫ) counts as 1 codepoint.

No Trigger Limit

Trigger can be any length, but keep it short and memorable!

Issue #178: Shortcuts longer than 255 characters will be automatically truncated.

Before this fix, shortcuts were limited to 63 characters.

Implementation

Shortcuts are implemented in core/src/engine/shortcut.rs:

Shortcut Structure

pub struct Shortcut {
    /// Trigger string (lowercase for matching)
    pub trigger: String,
    /// Replacement text
    pub replacement: String,
    /// When to trigger
    pub condition: TriggerCondition,
    /// How to handle case
    pub case_mode: CaseMode,
    /// Whether this shortcut is enabled
    pub enabled: bool,
    /// Which input method this shortcut applies to
    pub input_method: InputMethod,
}

Input Method Filtering

Shortcuts can be limited to specific input methods:

All Methods

let shortcut = Shortcut::new("vn", "Việt Nam")
    .for_method(InputMethod::All);

// Works in both Telex and VNI

Telex Only

let shortcut = Shortcut::telex("w", "ư");

// Only works when Telex is active
// Ignored in VNI mode

VNI Only

let shortcut = Shortcut::vni("7", "ơ");

// Only works when VNI is active
// Ignored in Telex mode

Why filter by input method?

Some triggers might conflict with typing in one method but not the other. For example, 7 is a valid shortcut in VNI but would interfere with normal number typing in Telex.

Shortcut Matching

Longest Match First

When multiple shortcuts match, the longest trigger wins:

Shortcuts:
  h   → họ
  hcm → Hồ Chí Minh

Type: hcm + Space
Result: Hồ Chí Minh  ✓  (not "họ + cm")

Case-Insensitive Matching

Triggers are matched case-insensitively:

Shortcut trigger: "ko" → "không"

Matches:
  ko  ✓
  Ko  ✓
  KO  ✓
  kO  ✓

Examples

Common Abbreviations

vn   → Việt Nam
hcm  → Hồ Chí Minh
hn   → Hà Nội
sg   → Sài Gòn
dn   → Đà Nẵng
dc   → được
ko   → không
k    → không
j    → vâng
z    → vậy

Email & Addresses

eml   → [e-mail]
addr  → 123 Nguyễn Huệ, Q1, TP.HCM
tel   → 0901234567

Frequently Used Phrases

tks    → Cảm ơn
sry    → Xin lỗi
brb    → Quay lại sau
omw    → Đang trên đường
lgtm   → Trông ổn
wfh    → Làm việc từ xa

Technical Terms

js     → JavaScript
ts     → TypeScript
py     → Python
rs     → Rust
db     → database
api    → Application Programming Interface

Long Text (Issue #178)

lorem → Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris...

// Supports up to 255 characters (previously 63)

Validation & Limits

Replacement Validation

const MAX_REPLACEMENT_LEN: usize = 255; // UTF-32 codepoints

fn validate_replacement(replacement: &str) -> String {
    let char_count = replacement.chars().count();
    if char_count <= MAX_REPLACEMENT_LEN {
        replacement.to_string()
    } else {
        // Truncate to 255 codepoints
        replacement.chars().take(MAX_REPLACEMENT_LEN).collect()
    }
}

Vietnamese characters with diacritics (ồ, ế, ẫ, ơ, ư) each count as 1 codepoint, not multiple bytes.

Disabling Shortcuts

To temporarily disable a shortcut without deleting it:

1. Open Settings → Shortcuts
2. Find the shortcut in the list
3. Uncheck the Enabled checkbox
4. Click Save

Disabled shortcuts are kept in storage but won’t trigger.

Troubleshooting

Shortcut doesn't trigger

1. Check if it’s enabled in Settings
2. Make sure you’re using the correct trigger mode (word boundary vs immediate)
3. Verify the input method filter (All/Telex/VNI)
4. Try toggling Vietnamese mode OFF and ON

Case doesn't match

Ensure CaseMode is set to MatchCase (default). If you want exact output, change it to Exact.

Replacement is truncated

Your replacement text exceeds 255 characters. Either shorten it or split it into multiple shortcuts.

Shortcut conflicts with typing

Change from Immediate to Word Boundary mode, or choose a less common trigger.

Comparison with Other IMEs

Feature	Gõ Nhanh	UniKey	OpenKey	EVKey
Custom shortcuts	✅	✅	✅	✅
Smart case matching	✅	❌	❌	❌
Input method filtering	✅	❌	❌	❌
Max replacement length	255	63	128	100
Immediate trigger mode	✅	✅	❌	✅
Word boundary mode	✅	✅	✅	✅

Best Practices

Keep Triggers Short

Use 2-5 character triggers for best usability.

Good: vn, hcm, ko

Bad: vietnamcountry, hochiminhcity

Avoid Conflicts

Don’t use triggers that are common word prefixes.

Good: tphcm (unique)

Bad: th (conflicts with “thì”, “thế”, “thực”…)

Use Word Boundary

Prefer word boundary mode over immediate for most shortcuts.

Safer and less intrusive.

Test First

Test new shortcuts in a text editor before using them in important documents.

Related Features

Input Methods

Learn about Telex and VNI

Auto-Restore

Automatic English word restoration