BRLTTY Reference Manual: Feature Descriptions

When moving the braille window around the screen while examining the text, say, in an editor, you often need to bring the cursor to a specific character within the braille window. You'll probably find this to be a rather difficult task for a number of reasons. One is that you may not know where the cursor is, and that you may lose your place while trying to find it. Another is that the cursor may move unpredictably as the arrow keys are pressed (some editors, for example, don't allow the cursor to be more to the right than the end of the line it's on). Cursor routing provides just such a capability by knowing where the cursor is, by simulating the same arrow-key presses which you'd have to enter manually, and by monitoring the progress of the cursor as it moves.

Some braille displays have a button, known as a routing key, above each cell. These keys use the ROUTE command to route the cursor right to the desired location.

Cursor routing, while very convenient and effective, is, strictly speaking, not completely reliable. One reason for this is that its current implementation assumes VT100 cursor key escape sequences. Another is that some applications do non-standard things in response to detecting that a cursor key has been pressed. A minor problem found within some editors (like vi), as already mentioned above, is that they throw in some unpredictable horizontal motion when vertical motion is requested because they don't allow the cursor to be to the right of the end of a line. A major problem found within some web browsers (like lynx) is that the up- and down-arrow keys are used to move among the links (which may skip lines and/or move the cursor horizontally, but which rarely just moves the cursor one line in the desired direction), and that the left- and right-arrow keys are used to select links (which has absolutely nothing to do with any form of cursor motion whatsoever, and which even totally changes the screen content).

Cursor routing may not work very well on a heavily loaded system, and definitely doesn't work very well when working on a remote system over a slow link. This is so because of all of the checks which must be made along the way in order to deal with unpredictable cursor motion and in order to ensure that any mistake has at least a fighting chance to be undone. Even though BRLTTY tries to be fairly clever, it must still essentially wait to see what happens after each simulated arrow-key press.

Once a cursor routing request has been made, BRLTTY keeps trying to route the cursor to the desired location until a timeout expires before the cursor reaches that location, the cursor seems to be moving in the wrong direction, or you switch to a different virtual terminal. An attempt is first made to use virtical motion to bring the cursor to the right line, and, only if that succeeds, an attempt is then made to use horizontal motion to bring the cursor to the right column. If another request is made while one is still in progress, then the first one is aborted and the second one is initiated.

A safer but less powerful cursor routing command, CSRJMP_VERT, uses just vertical motion to bring the cursor to anywhere on the top line of the braille window. It's especially useful in conjunction with applications (like lynx) wherein horizontal cursor motion must never be attempted.

5.2 Cut and Paste

This feature enables you to grab some text which is already on the screen and re-enter it at the current cursor position. Using it saves time and avoids errors when a long and/or complicated piece of text needs to be copied, and even when the same short and simple piece of text needs to be copied many times. It's particularly useful for things like long file names, complicated command lines, E-mail addresses, and URLs. Cutting and pasting text involves three simple steps:

Mark either the top-left corner of the rectangular area or the beginning of the linear area on the screen which is to be grabbed (cut). If your display has routing keys, then move the braille window so that the first character to be cut appears anywhere within it, and then:
- invoke the CUTBEGIN command to start a new cut buffer
- invoke the CUTAPPEND command to append to the existing cut buffer
by pressing the key(s) associated with it and then pressing the routing key associated with the character.
Mark either the bottom-right corner of the rectangular area or the end of the linear area on the screen which is to be grabbed (cut). If your display has routing keys, then move the braille window so that the last character to be cut appears anywhere within it, and then
- invoke the CUTRECT command to cut a rectangular area
- invoke the CUTLINE command to cut a linear area
by pressing the key(s) associated with it and then pressing the routing key associated with the character. Marking the end of the cut area appends the selected screen content to the cut buffer. Excess white-space is removed from the end of each line in the cut buffer so that unwanted trailing spaces won't be pasted back in. Control characters are replaced with blanks.
Insert (paste) the text where it's needed. Place the cursor over the character where the text is to be pasted, and invoke the PASTE command. You can paste the same text any number of times without recutting it. This description assumes that you're already in some sort of input mode. If you paste when you're in some other kind of mode (like vi's command mode), then you'd better be aware of what the characters in the cut buffer will do.

The cut buffer is also used by the PRSEARCH/NXSEARCH commands.

5.3 Pointer (Mouse) Support via GPM

If BRLTTY is configured with the --enable-gpm build option on a system where the gpm application has been installed, then it'll interact with the pointer (mouse).

Moving the pointer drags the braille window (see the Window Follows Pointer preference). Whenever the pointer is moved beyond the edge of the braille window, the braille window is dragged along (one character at a time). This gives the braille user another two-dimensional way to inspect the screen content or to quickly move the braille window to a desired location. It also gives a sighted observer an easy way to move the braille window to something he'd like the braille user to read.

gpm uses reverse video to show where the pointer is. Underlining of highlighted characters (see the ATTRVIS command for details) should be turned on, therefore, when the braille user wishes to use the pointer.

This feature also gives the braille user access to gpm's cut-and-paste capability. Although you should read gpm's own documentation, here are some notes on how it works.

Copy the current character to the cut buffer by single-clicking the left button.
Copy the current word (space-delimited) to the cut buffer by double-clicking the left button.
Copy the current line to the cut buffer by tripple-clicking the left button.
Copy a linear region to the cut buffer as follows:
1. Place the pointer on the first character of the region.
2. Press (and hold) the left button.
3. Move the pointer to the last character of the region (all currently selected characters are highlighted).
4. Release the left button.
Paste (input) the current contents of the cut buffer by clicking the middle button of a three-button mouse or by clicking the right button of a two-button mouse.
Append to the cut buffer by using the right button of a three-button mouse.

5.4 Alert Tunes

BRLTTY alerts you to the occurrence of significant events by playing short predefined tunes. This feature can be activated and deactivated with either the TUNES command or the Alert Tunes preference. The tunes are played via the internal beeper by default, but other alternatives can be selected with the Tune Device preference.

Each significant event is associated, from highest to lowest priority, with one or more of the following:

a tune: If a tune has been associated with the event, if the Alert Tunes preference (see also the TUNES command) is active, and if the selected tune device (see the Tune Device preference) can be opened, then the tune is played.
a dot pattern: If a dot pattern has been associated with the event, and if the Alert Dots preference is active, then the dot pattern is briefly displayed on every braille cell. Some braille displays don't respond quickly enough for this mechanism to work effectively.
a message: If a message has been associated with the event, and if the Alert Messages preference is active, then it is displayed for a few seconds (see the -M command line option).

These events include:

When the braille display driver starts or stops.
When a lengthy command completes.
When a command cannot be executed.
When a mark is set.
When the start or end of the cut block is set.
When a feature is activated or deactivated.
When cursor tracking is turned on or off.
When the screen image is frozen or unfrozen.
When the braille window wraps either down to the beginning of the next line or up to the end of the previous line.
When identical lines are skipped.
When a requested motion cannot be performed.
When cursor routing starts, finishes, or fails.

5.5 Preferences Settings

When BRLTTY starts, it loads a file which contains your preferences settings. The file doesn't need to exist, and is created the first time the settings are saved with the PREFSAVE command. The most recently saved settings can be restored at any time with the PREFLOAD command.

The name for this file is /etc/brltty-driver.prefs. where driver is the two-letter driver identification code.

The Preferences Menu

The preferences settings are saved as binary data which, therefore, can't be edited by hand. BRLTTY, however, has a simple menu from which you can easily change them.

The meny is activated by the PREFMENU command. The braille display briefly (see the -M command line option) shows the menu title, and then presents the current item and its current setting.

Navigating the Menu

See Menu Navigation Commands for the full list of commands which enable you to select items and change settings within the menu. For backward compatibility with old drivers, the window motion commands, which have modified meanings in this context, can also be used.

TOP/BOT, TOP_LEFT/BOT_LEFT, PAGE_UP/PAGE_DOWN: Go to the first/last item in the menu (same as MENU_FIRST_ITEM/MENU_LAST_ITEM).
LNUP/LNDN, PRDIFLN/NXDIFLN, CURSOR_UP/CURSOR_DOWN: Go to the previous/next item in the menu (same as MENU_PREV_ITEM/MENU_NEXT_ITEM).
WINUP/WINDN, CHRLT/CHRRT, CURSOR_LEFT/CURSOR_RIGHT, BACK/HOME: Decrement/increment the current menu item's setting (same as MENU_PREV_SETTING/MENU_NEXT_SETTING).

Notes:

The routing keys can also be used to select a setting for the current item. If the item has numeric settings, then the entire row of routing keys acts as a scroll bar which covers the full range of valid values. If the item has named settings, then the routing keys correspond ordinally with the settings.
Use the PREFLOAD command to undo all of the changes which were made since entering the menu.
Use the PREFMENU command (again) to leave the new settings in effect, exit the menu, and resume normal operation. If the "Save Settings on Exit" item is set, then, in addition, the new settings are written to the preferences settings file. Any command not recognized by the menu system also does these same things.

The Menu Items

Save on Exit

When exiting the preferences menu:

No: Don't automatically save the preferences settings.
Yes: Automatically save the preferences settings.

The initial setting is No.

Text Style

When displaying screen content (see the DISPMD command), show characters:

8-dot: With all eight dots.
6-dot: With only dots 1 through 6. If a contraction table has been selected (see the -c command line option and the contraction-table configuration file directive), then it is used.

This setting can also be changed with the SIXDOTS command.

Skip Identical Lines

When moving either up or down exactly one line with the LNUP/LNDN commands, as well as the line wrapping feature of the FWINLT/FWINRT and FWINLTSKIP/FWINRTSKIP commands:

No: Don't skip past lines which have the same content as the current line.
Yes: Skip past lines which have the same content as the current line.

This setting can also be changed with the SKPIDLNS command.

Skip Blank Windows

When moving either left or right with the FWINLT/FWINRT commands:

No: Don't skip past blank windows.
Yes: Skip past blank windows.

This setting can also be changed with the SKPBLNKWINS command.

Which Blank Windows

If blank windows are to be skipped:

All: Skip all of them.
End of Line: Only skip those which are at the end (on the right side) of a line.
Rest of Line: Only skip those which are at the end (on the right side) of a line when reading forward, and at the beginning (on the left side) of a line when reading backward.

Sliding Window

If the cursor is being tracked (see the CSRTRK command), and the cursor moves too close to (or beyond) either end of the braille window:

No: Horizontally reposition the window such that its left end is a multiple of its width from the left edge of the screen.
Yes: Horizontally reposition the window such that the cursor, while remaining on that side of the window, is nearer the centre.

This setting can also be changed with the SLIDEWIN command.

Eager Sliding Window

If the braille window is to slide:

No: Reposition it whenever the cursor moves beyond either end.
Yes: Reposition it whenever the cursor moves too close to either end.

The initial setting is No.

Window Overlap