Debian Codegraph @

doc/hacking-terminal.html

raw ◀ ▶
1 Debian patch touch this file
1 <html>
2 <head>
3 <title>netrik hacker's manual: terminal and color handling</title>
4 </head>
5 <body>
6
7 <h1 align="center">netrik hacker's manual<br />>========================&lt;</h1>
8
9 <p>
10 [This file describes handling of terminal input/output, and color handling. See
11 hacking.txt or <a href="hacking.html">hacking.html</a> for an overview
12 of the manual.] &lt;a name="color" id="color">
13 </p>
14
15 <h2>Color Handling</h2>
16
17 <h3>Color Representation</h3>
18
19 <p>
20 For storing color values internally (in the
21 <a href="hacking-layout.html#string">String</a> structure in the
22 layout, see <a href="hacking-layout.html">hacking-layout.html</a>) and
23 for passing to the color setting functions (see
24 <a href="screenC">screen.c</a> below), a one-byte color
25 representation is used much like the one of CGA/EGA/VGA cards:
26 </p>
27
28 <p><pre>
29 +-------+-------+-------+-------+-------+-------+-------+-------+
30 |bright : |bright : |
31 |back- : background color |fore- : foreground color |
32 |ground : |ground : |
33 +-------+-------+-------+-------+-------+-------+-------+-------+
34 7 6 5 4 3 2 1 0
35 </pre></p>
36
37 <h3>Text Colors</h3>
38
39 <p>
40 Background colors are presently only used for link highlighting, so setting the
41 original text color boils down to determining the foreground color.
42 </p>
43
44 <p>
45 The text colors of the text on the layouted page are determined when storing
46 the text while <a href="hacking-layout.html#parseStruct">Parsing
47 Structure</a> during the layouting process (see
48 <a "href=hacking-layout.html">hacking-layout.*</a>).
49 </p>
50
51 <p>
52 The right color for each text part is determined by a facility named text
53 modes: For every kind of text on the page (normal text, emphasized text, links,
54 layout marks etc.) one constant exists in "enum Text_mode", and some fixed
55 color value corresponds to each one.
56 </p>
57
58 <p>
59 The assignement of color values to the text modes is done with the
60 "color_map[]" array, which is declared and initialized in colors.c. (See
61 <a href="#colorSchemes">Colors Schemes</a> below.)
62 </p>
63
64 <p>
65 For the various kinds of layout/form/image markers the color is directly taken
66 from the map entry of the appropriate text type and passed to
67 <a href="hackting-layout.html">add_string()</a> (see
68 hacking-layout.*). Text modes that affect normal text (content) added during
69 parsing (like links, emphasize), set the "state.text_mode" variable instead; any
70 normal text will be added in the mode currently stored in this variable.
71 </p>
72
73 <p>
74 Bold text (strong emphasize) is presently handled in a different manner: The
75 "state.bold" flag is set, causing all text added inside the section to be added with
76 a negated brightness flag. (i.e. normal colors will become bright/bold, while
77 colors for text modes already having "bright" set in the color map will be
78 non-bright instead.)
79 </p>
80
81 <a name="colorSchemes" id="colorSchemes">
82
83 <h3>Color Schemes</h3>
84
85 <p>
86 Netrik allows using different color schemes, according to one's preferences and
87 terminal colors. However, the color schemes aren't fully customizable for now;
88 there are only two color schemes (defined in colors-dark.c and colors-bright.c)
89 that can be switched by "cfg.bright_background" (using --bright-background or
90 --dark-background).
91 </p>
92
93 <p>
94 This is chiefly because our preffered colors only look good on black background,
95 but are unusable on bright background, so different color schemes have to be
96 provided for those situations.
97 </p>
98
99 <p>
100 The handling is actually quite simple: Depending on the setting of
101 "cfg.bright_background", either "color_map_bright" (from colors-bright.c) or
102 "color_map_dark" (from colors-dark.c) is assigned to "color_map". This is done
103 in load_color_map(), which is called after reading the command line/config file
104 options in main().
105 </p>
106
107 <p>
•108 Note that, unless explicitly overridden by --no-force-colors,
109 "cfg.force_colors" is automatically set if "cfg.bright_background" is not set,
110 so a black background will always be used with the dark color scheme, even on a
111 terminal normally having a bright background. This isn't done with the bright
112 color scheme; here, the terminal's default colors are kept.
113 </p>
114
115 </a> <!-- colorSchemes -->
116
117 <h3>Monochrome Mode</h3>
118
119 <p>
120 Netrik now features an extremly crude monochrome mode, which is activated by
121 passing the --bw command line option, or automatically in init_curses(), if the
122 terminal definition lacks color switching capabilities.
123 </p>
124
125 <p>
126 The monochrome mode presently completely disables all color/attribute
127 switching.
128 </p>
129
130 <p>
131 This is achieved by skipping all color initializations and making all color
132 setting functions nops. Thus, it needs handling only in screen.c (s.b.), and is
133 otherwise completely transparant.
134 </p>
135
136 </a> <!-- color -->
137
138 <a name="screenC" id="screenC">
139
140 <h2>screen.c</h2>
141
142 <p>
143 screen.c contains a couple of helper functions for handling curses, both in raw
144 and in full screen mode.
145 </p>
146
147 <p>
148 init_curses() is responsible for initializing curses in raw mode, and getting
149 some control sequences for setting colors etc. If cfg.inverse_bold was not
150 specified by the user, this is also done here: If the terminal name contains
151 "xterm", cfg.inverse_bold is set, otherwise reset.
152 </p>
153
154 <p>
155 start_curses() initializes curses in full screen mode, and sets the
156 foreground/background color pairs. (This is necessary to change colors using
157 curses.) It also initializes several curses settings.
158 </p>
159
160 <p>
161 All 63 modifiable color pairs are initialized (pair 0 is hard-wired in curses),
162 in such a manner that every combination of the eight foreground and eight
163 background colors is covered. (Brightness is controled by extra flags, and not
164 coded in the color pairs.) The upper three bits of the six-bit pair number
165 specify the background, the lower 3 the foreground. While the background colors
166 are mapped directly, some magic is necessary for the foreground, to ensure that
167 color pair 0 (which is hard-wired to white on black) will actually correspond
168 to the right color in the color scheme. This is achieved by rotating the
169 foreground color space by one, so color 0 gets white, color 1 gets black etc.,
170 instead of color 0 being black and color 7 being white.
171 </p>
172
173 <p>
174 For color pairs having black background or white foreground, the respective
175 parts aren't set; the terminal default is used instead. (Unless --force-colors
176 is used.) This is to produce the expected results in most xterms (or other
177 terminals with bright background and black text).
178 </p>
179
180 <p>
181 set_color() sets the text attributes in full screen mode. The foreground color
182 is set, and the "bold" attribute if it is a light color.
183 </p>
184
185 <p>
186 If the background color is bright, the "blink" attribute is set, which works on
187 most terminals. (Sadly not all...)
188 </p>
189
190 <p>
191 As this doesn't work in xterm, another approach has to be used for those: If
192 cfg.inverse_bold was set (see above), the "blink" attribute is used in
193 conjuction with reverse video instead. Of course we have to swap foreground and
194 background colors to get the actually desired ones. (Note that this trick
195 doesn't work on linux console, so we can use it *only* when in an xterm!)
196 </p>
197
198 <p>
199 The drawback is that the foreground is always bold but dark in this mode -- we
200 can neiter prevent it getting bold nor get it bright to distinguish between
201 bold and normal foreground as soon as a bright background is set...
202 </p>
203
204 <p>
205 set_color_raw() does the same in raw mode. As raw mode has no color pairs to be
206 set during initialization, handling of default colors for white
207 foreground/black background has to be done here. The respective parts simply
208 aren't set at all, thus keeping the terminal default colors.
209 </p>
210
211 <p>
212 reset_colors_raw() resets all text attributes to their default values.
213 </p>
214
215 </a> <!-- screenC -->
216
217 <a name="winch" id="winch">
218
219 <h2>SIGWINCH Handling</h2>
220
221 <p>
222 Handling of the "winch" singnal (which is raised by the terminal each time the
223 text area changes, e.g. when resizing an xterm window) itself is quite simple,
224 as we use the default handler provided by ncurses. On SIGWINCH, ncurses will
225 adjust its own data structures, and also store the pseudo-key "KEY_RESIZE" in
226 the input queue, so we know there was a change.
227 </p>
228
229 <p>
230 Only thing we have to care of here is ensuring that ncurses won't resize its
231 data structures while we are making some changes to the screen contents, as
232 this might cause failure when we are outside the screen unexpectedly. This is
233 achieved by the two functions hold_winch() and enable_winch() from winch.c.
234 hold_winch() stops immediate delivery of the winch signal, bud does not descard
235 it; instead, it is put on hold. enable_winch() reenables delivery of the
236 singal. If there is a pending signal generated during the hold phase, it is
237 also delivered now.
238 </p>
239
240 <p>
241 To ensure that SIGWINCH arrives only in controlled circumstances, it is put on
242 hold before entering fullscreen mode at the beginning of
243 <a href="hacking-pager.html#display">display()</a> (see
244 hacking-pager.*), and released only after switching to scroll mode again.
245 (Inside end_fullscreen(), which is located in screen.c.) Only for the time of
246 the getch() call (waiting for a keypress) it is enabled, as the resulting
247 KEY_RESIZE will be handled immediately, thus no problems with unexpected
248 changes can arise.
249 </p>
250
251 <p>
252 Of course, resizing the pager window is not enough; the page contents also
253 needs to be adapted to the new screen width. This is done by returning to
254 <a href="hacking.html#main">main()</a> (see hacking.*) with
255 RET_WINCH, where
256 <a href="hacking-layout.html#resize">ressize()</a> (described in
257 hacking-layout.*) is called before returning to the pager.
258 </p>
259
260 </a> <!-- winch -->
261
262 </body>
263 </html>