Use accessors for setting adjustment
[vte.git] / doc / ambiguous.txt
1 Unicode defines width information for characters.  Conventionally this
2 describes the number of columns a character is expected to occupy when
3 printed or drawn using a monospaced font.
4
5 There are five width classes with which we concern ourselves.  Four of
6 these are narrow, wide, half-width, and full-width.  For practical
7 purposes, narrow and half-width can be grouped together as
8 "single-width" (occupying one column), and wide and full-width can be
9 grouped together as "double-width" (occupying two columns).
10
11 The last class we're concerned with is those of ambiguous width.  These
12 are characters which have the same meaning and graphical representation
13 everywhere, but which are either single-width or double-width based on
14 the context in which they appear.
15
16 Width information is crucial for terminal-based applications which need
17 to address the screen:  if the application draws five characters and
18 expects the cursor to be in moved six columns to the right, and the
19 terminal moves the cursor seven (or five, or any number other than six),
20 display bugs manifest.
21
22 Ambiguously-wide characters pose an implementation problem for terminals
23 which may not be running in the same locale as an application which is
24 running inside the terminal.  In these cases, the terminal cannot depend
25 on the libc wcwidth() function because wcwidth() typically makes use of
26 locale information.
27
28 There are basically four approaches to solving this problem:
29 A) Force characters with ambiguous width to be single-width.
30 B) Force characters with ambiguous width to be double-width.
31 C) Force characters with ambiguous width to be have a width value based
32    on the locale's region.
33 D) Force characters with ambiguous width to be have a width value based
34    on the locale's encoding.
35
36 Methods A and B will produce display bugs, because they don't take into
37 account any context information.  Method C fails on glibc-based systems
38 because glibc uses method D and the two methods produce different
39 results for the same wchar_t values.
40
41 So the VteTerminal widget uses approach D.  Depending on the context in
42 which a character was received (a combination of the terminal's encoding
43 and whether or not the character was received as an ISO-2022 sequence),
44 a character is internally assigned a width when it is received from the
45 terminal.
46
47 Text which is not received from the terminal (input method preedit data)
48 is processed using method C, although now that I think about it, the
49 fact that it's UTF-8 text suggests that these characters should be
50 treated as single-width.