| 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 />>========================<</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.] <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> |