ilyakooo0/vty
1
0
Fork 0
mirror of https://github.com/ilyakooo0/vty.git synced 2024-11-25 19:22:08 +03:00
Code Issues Projects Releases Wiki Activity

README: add documentation on custom character width tables

Browse Source
This commit is contained in:
Jonathan Daugherty 2020-03-05 09:40:36 -08:00
parent ea655ee90d
commit e1384c3266
1 changed files with 66 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
README.md
View File

@ -79,6 +79,72 @@ with some special rules to handle some omissions from `terminfo`.
Windows is not supported.
# Multi-Column Character Support
Vty supports rendering of multi-column characters such as two-column
Asian characters and Emoji characters. This section details how to
take advantage of this feature, since its behavior will depend on the
terminal emulator in use.
Terminal emulators support Unicode to varying degrees, and each terminal
emulator relies on a table of column widths for each supported Unicode
character. Vty also needs to rely on such a table to compute the width
of Vty images to do image layout. Since those tables can disagree if
Vty and the terminal emulator support different versions of Unicode,
and since different terminal emulators will support different versions
of Unicode, it's likely that for some wide characters, Vty applications
will exhibit rendering problems. Those rendering problems arise from Vty
and the terminal emulator coming to different conclusions about how wide
some characters are.
Vty has a built-in Unicode character width table. Unless configured to
do otherwise, by default, Vty will use this built-in table. But since
the built-in table is likely to eventually disagree with your terminal,
Vty provides a feature called custom Unicode character width table
support. This feature allows Vty to query your terminal to build a width
table based solely on your terminal emulator's logic. That table is then
saved to disk and loaded by Vty-based applications to ensure that Vty's
width calculations are correct for that particular terminal.
Custom Unicode width tables based on your terminal emulator can be
built by running Vty's built-in tool, `vty-build-width-table`. The tool
works by querying the current terminal emulator to obtain its width
measurements for the entire supported Unicode range. The
results are then saved to a disk file. These custom tables
can also be generated programmatically by using the API in
`Graphics.Vty.UnicodeWidthTable.Query`.
Saved width tables can then be loaded in one of two ways:
* Via the library API in `Graphics.Vty.UnicodeWidthTable.IO`
* By adding a `widthMap` directive to your Vty configuration file
The Vty configuration file supports the `widthMap` directive to allow
users to specify which custom width table should be loaded for a given
terminal type. This is done by specifying, e.g.,
```
widthMap "xterm" "/path/to/map.dat"
```
where the first argument is the value that `TERM` must have in order for
the table to be loaded, and the second argument is the path to the table
file itself as generated by the two alternatives listed above. If the
Vty configuration file contains multiple matching `widthMap` directives
for the current value of `TERM`, the last one listed in the file is
used.
The tables declared in the configuration file are only ever
automatically loaded when applications set up Vty by calling
`Graphics.Vty.mkVty`.
Before a custom table has been loaded, calls to the library's character
width functions (e.g. `wcwidth`) will use the default built-in table.
Once a custom table has been loaded, the functions will use the new
custom table. Only one custom table load can be performed in a Vty
program. Once a custom table has been loaded, it cannot be replaced or
removed.
# Contributing
If you decide to contribute, that's great! Here are some guidelines you