Word

Word definitions

Words are defined in the dictionary list in settings.yaml. The chords and key sequences for words are both automatically generated from that definition.

The simplest way to define a word in the dictionary, such as the, is like this:

- {word: "the"}

By default, the chord will be generated by combining the existing plain_key chords mapped to each letter in the word. So in this example, the chord for the consists of the chords for key_t, key_h, and key_e pressed all at once.

This chord-generation approach causes conflicts when multiple words would be assigned the same chord - like "the", "teeth", and "thee". We call these conflicting words anagrams, and use anagram_modifiers to select which one we want. You can add up to 15 anagrams for the same chord, and order them in the dictionary such that the words you use most often come first. We can define "the", "teeth" and "thee" like this:

- {word: "the"}
- {word: "teeth", anagram: 1}
- {word: "thee", anagram: 2}

Now you can type "teeth" by pressing the chords for key_t, key_h, key_e, and mod_anagram1 all at once, or type "thee" by pressing mod_anagram2 instead of mod_anagram1. Alternatively, if you forgot to use the correct anagram_modifier, you can press the command_cycle_word chord to delete the last word and replace it with the next anagram in the list. So if you had just typed "the", pressing command_cycle_word once would replace it with "teeth", and pressing it again would replace that with "thee".

Overlapping letters

Anagram conflicts can also happen if two words have different letters, but the chords for those letters overlap. For example, if pressing m + p produces z, then "map" and "zap" are anagrams of each other. When you press all of those switches at once, the keyboard can't know whether you wanted to type an m and a p, or just a z, or some combination of the three.

This also means that if you rearrange individual letters in the keymap, the anagrams will change, and you'll need to edit the anagram numbers in the dictionary list. The pipit-config tool will guide you in this process by pointing out both new anagram conflicts and words that have unnecessarily high anagram numbers left over from previous conflicts.

Custom chords and briefs

You can also set custom chords for words - like a stenographer's brief. For example, "different" is a common word that, by default, requires an awkward combination of 7 switches (for d, i, f, e, r, n, and t). The following definition lets you to type it just by pressing d, i, and f, instead:

- {word: "different", chord: "dif"}

This feature is also useful for adding longer phrases that you use frequently:

- {word: "as far as I know", chord: "afi"}
- {word: "sounds good", chord: "sg"}
- {word: "thank you for", chord: "tyf"}

Modifiers

Word chords can be modified only by word_modifiers and anagram_modifiers.

By default, words are automatically preceded by a space, and they're typed out in the same case as they're written in the dictionary (so usually, all lowercase). If one or more word_modifiers are pressed at the same time as the word's chord, they will change that behavior in the following ways:

modifier effect
mod_capital Capitalize the first letter of the word.
mod_nospace Do not type a space before the word.
mod_shorten First type backspace to shorten the previous word, then type the new word (without a space before it). You can turn "create" into "creating" by pressing "ing" + mod_shorten
mod_double First repeat the last letter of the previous word, then type the new word (without a space before it). You can turn "tap" into "tapping" by pressing "ing" + mod_double.
mod_anagram1 Type the first anagram of the word.
mod_anagram2 Type the second anagram of the word.

Cycle commands

If you forgot to use one of the word modifiers above, you can get the same effect by pressing one of these cycling commands immediately after the word. They will delete the word, and replace it with a new version.

command effect
command_cycle_capital Toggle whether the word's first letter is capitalized.
command_cycle_nospace Toggle whether the word is preceded by a space.
command_shorten_last_word Go back and shorten the word before the one you just typed.
command_cycle_word Cycle between all possible anagrams of a word. This lets you reach higher anagram numbers than you could directly type using just mod_anagram1 or mod_anagram2.

Word movement commands

The keyboard stores a history of the last few words you typed, and lets you move between them, delete them, or edit them (with the cycling commands in the previous section).

command effect
command_delete_word Delete the word the previous word in the history (by typing the correct number of backspaces)
command_left_word Move the cursor to the end of the previous word in the history (by typing the correct number of left arrows.)
command_right_word Move the cursor to the end of the next word in the history.
command_left_limit Move the cursor to the oldest character in the history.
command_right_limit Move the cursor to the newest character in the history.

For example, say you write the following phrase, using word chords for each word. The | indicates the cursor position.

Coffee with camera and sugar|

You now realize that you meant to say "cream" instead of "camera", but forgot to press the correct anagram modifier. You can fix it by pressing this sequence of commands:

  1. command_left_word ⮕ Coffee with camera and| sugar

  2. command_left_word ⮕ Coffee with camera| and sugar

  3. command_cycle_word ⮕ Coffee with cream| and sugar

  4. command_right_limit ⮕ Coffee with cream and sugar|

Note that the keyboard can't have perfect knowledge of what's on your screen, so the stored history can become invalid if you, for example:

  • use text editor shortcuts or use the mouse to re-position the cursor
  • hold a switch down for long enough to trigger the host computer's key repeat

The history is automatically erased whenever you type keys like mod_ctrl, since they're likely to be part of shortcuts that would invalidate the history. But the keyboard can't detect other actions like mouse movements, so be aware that history commands won't work correctly in those situations.