| 1 |
<html> |
| 2 |
<head> |
| 3 |
<title>netrik hacker's manual: pager</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<h1 align="center">netrik hacker's manual<br />>========================<</h1> |
| 8 |
|
| 9 |
<p> |
| 10 |
[This file contains a description of the viewer module. See hacking.txt or |
| 11 |
<a href="hacking.html">hacking.html</a> for an overview of the manual.] |
| 12 |
</p> |
| 13 |
|
| 14 |
<h2>Pager Operation</h2> |
| 15 |
|
| 16 |
<p> |
| 17 |
As the pager doesn't just follow a static algorithm, but has to react to |
| 18 |
certain events (keyboard input), the structure is somewhat harder to retrace. |
| 19 |
</p> |
| 20 |
|
| 21 |
<p> |
| 22 |
The central pager function is <a href="#display">display()</a>, |
| 23 |
which contains the main loop (keyboard dispatcher) which performs some |
| 24 |
action(s) on each keypress, as well as the interface to main(). |
| 25 |
</p> |
| 26 |
|
| 27 |
<p> |
| 28 |
These actions directly performed by the keyboard commands mostly do not have a |
| 29 |
direct visible effect; instead, they alter the pager state, which becomes |
| 30 |
visible with the next screen update -- this is performed in each main loop |
| 31 |
iteration before waiting for the next keypress. Some actions also require |
| 32 |
temporarily exiting the pager and returning to main(), which is fairly easy and |
| 33 |
transparent, as the pager state is stored directly in the |
| 34 |
<a href="hacking-page.html#pageStruct">page structure</a> and the |
| 35 |
screen contents thus can be easily restored when reentering the pager. |
| 36 |
</p> |
| 37 |
|
| 38 |
<p> |
| 39 |
The pager state consists of three basic components: "pager_pos" is the line |
| 40 |
number (in page) of the first line visible on the screen. "active_link" |
| 41 |
contains the link number of the currently selected link. (Or -1 if none.) |
| 42 |
"cursor_x" and "cursor_y" tell where the cursor is on the page. (Not the |
| 43 |
screen!) The additional "sticky_cursor" flag allows keeping the cursor in its |
| 44 |
place while scrolling (if possible), instead of moving it to the screen top. |
| 45 |
</p> |
| 46 |
|
| 47 |
<p> |
| 48 |
Each of the major parameters is manipulated chiefly by one function: |
| 49 |
<a href="#scrollTo">scroll_to()</a> sets "pager_pos", |
| 50 |
<a href="#activateLink">activate_link()</a> sets "active_link", |
| 51 |
and <a href="#setCursor">set_cursor()</a> sets the cursor position |
| 52 |
(and also manages the "sticky_cursor" status). The variables aren't |
| 53 |
independent, however -- scroll_to() may need to deactivate the active link if |
| 54 |
it moved off the screen, and often move the cursor; activate_link may need to |
| 55 |
scroll if the link is presently not an the screen, and always has to set the |
| 56 |
cursor position; set_cursor() has to deactivate any previously active link, and |
| 57 |
also scroll if the desired cursor position is outside the current screen. This |
| 58 |
interrelation requires the functions calling each other in a quite complicated |
| 59 |
manner, sometimes even recursively... Maybe we should try to write a generic |
| 60 |
function for updating all the states at once by a single request. |
| 61 |
</p> |
| 62 |
|
| 63 |
<p> |
| 64 |
Note that scroll_to() and activate_link() do not only set the state, but also |
| 65 |
(re)render the visible page part (using |
| 66 |
<a href="hacking-layout.html#render">render()</a>, which is |
| 67 |
described in hacking-layout.*). Probably it would be better to do this in the |
| 68 |
main loop also. Moreover, activate_link() even modifies the page, which was a |
| 69 |
very bad idea and surely will be changed in the future. |
| 70 |
</p> |
| 71 |
|
| 72 |
<a name="display" id="display"> |
| 73 |
|
| 74 |
<h2>display()</h2> |
| 75 |
|
| 76 |
<p> |
| 77 |
The viewer basically consists of a keyboard dispatcher that loops until some |
| 78 |
command was given that requires some action by main(). These include the quit |
| 79 |
command, link following, history commands, entering the command prompt, or text |
| 80 |
search. |
| 81 |
</p> |
| 82 |
|
| 83 |
<p> |
| 84 |
display() tells main() what action is required, by the return value which is an |
| 85 |
"enum Pager_ret". |
| 86 |
</p> |
| 87 |
|
| 88 |
<p> |
| 89 |
After main() has done it's work, display() will be called again; it will then |
| 90 |
continue just where it stopped, which is possible because the important pager |
| 91 |
state information (postion of the currently visible page part, cursor position, |
| 92 |
currently selected link) are stored in the |
| 93 |
<a href="hacking-page.html#pageStruct">page structure</a>, which is |
| 94 |
described under <a href="hacking-page.html#pageList">Page List |
| 95 |
Handling</a> in hacking-page.*. Thus the way over main() is quite |
| 96 |
seemless; to the user it usually looks as if he was in the pager all the time. |
| 97 |
</p> |
| 98 |
|
| 99 |
<p> |
| 100 |
To allow for this, display() needs to do some work to restore the state upon |
| 101 |
startup. |
| 102 |
</p> |
| 103 |
|
| 104 |
<p> |
| 105 |
First, the page is scrolled to the previous position, using |
| 106 |
<a href="#scrollTo">scroll_to()</a>. "old_line" is set to |
| 107 |
PAGE_INVALID (meaning the pager presently displays nothing) before scrolling, |
| 108 |
so that the screen contents always will be drawn completely anew. |
| 109 |
</p> |
| 110 |
|
| 111 |
<p> |
| 112 |
Afterwards, the cursor position is set to the saved one using |
| 113 |
<a href="#setCursor">set_cursor()</a>. Note that the position |
| 114 |
has to be stored before scroll_to(), as this function might move it out of the |
| 115 |
screen and adjust the cursor, in case a new cursor position was requested. (By |
| 116 |
a text search.) |
| 117 |
</p> |
| 118 |
|
| 119 |
<p> |
| 120 |
Finally, if there is a selected link, it is (re)activated with |
| 121 |
<a href="hacking-links.html#activateLink">activate_link()</a> |
| 122 |
(described in hacking-links.*). The active link also has to be saved before |
| 123 |
scroll_to(), as the link position may have changed in the meantime, causing |
| 124 |
scroll_to() to deactivate the previouly selected link if it is no longer on the |
| 125 |
screen. |
| 126 |
</p> |
| 127 |
|
| 128 |
<p> |
| 129 |
Reactivating the link is omitted when the pager is restarted after a text |
| 130 |
search command ("search.type" is set) -- in this case the cursor position has |
| 131 |
higher priority and is not to be overwritten. |
| 132 |
</p> |
| 133 |
|
| 134 |
<p> |
| 135 |
Initialization is slightly different if an anchor was activated, which is |
| 136 |
indicated by "page->active_anchor" being set. In this case, instead of callig |
| 137 |
scroll_to() directly, |
| 138 |
<a href="hacking-links.html#activateAnchor">activate_anchor()</a> |
| 139 |
(also described in hacking-links.*) is used. This one also scrolls (but to the |
| 140 |
anchor position, not the previous pager position), and additionally draws the |
| 141 |
anchor marks. |
| 142 |
</p> |
| 143 |
|
| 144 |
<p> |
| 145 |
After completing these initalizations, the keyboard input loop is entered, |
| 146 |
which reads one character in each iteration (note that the mvgetch() fuction |
| 147 |
used for that also updates the curses screen), and then dispatches to the |
| 148 |
requested command in a big switch. |
| 149 |
</p> |
| 150 |
|
| 151 |
<p> |
| 152 |
The cursor position (passed to mvgetch()) is determined from |
| 153 |
"page->cursor_[xy]", which are page coordinates, and have to be transformed to |
| 154 |
screen coordinates first. |
| 155 |
</p> |
| 156 |
|
| 157 |
</a> <!-- display --> |
| 158 |
|
| 159 |
<h2>Scrolling Commands</h2> |
| 160 |
|
| 161 |
<p> |
| 162 |
The scrolling commands are all implemented by simple calls to scroll_to() with |
| 163 |
different parameters. All relative movement commands can simply add or subtract |
| 164 |
a constant number of lines to move, as scroll_to() checks for the page |
| 165 |
boundaries. |
| 166 |
</p> |
| 167 |
|
| 168 |
<a name="scrollTo" id="scrollTo"> |
| 169 |
|
| 170 |
<h3>scroll_to()</h3> |
| 171 |
|
| 172 |
<p> |
| 173 |
This function scrolls the visible page area to the desired position. It moves |
| 174 |
(or deletes) the screen content, and repaints newly visible areas using |
| 175 |
<a href="hacking-layout.html#render">render()</a> (see |
| 176 |
hacking-layout.*). |
| 177 |
</p> |
| 178 |
|
| 179 |
<p> |
| 180 |
It is called with the desired new position as argument. This position is |
| 181 |
described by the line number, of that line of the output page which is |
| 182 |
displayed in the first screen line. |
| 183 |
</p> |
| 184 |
|
| 185 |
<p> |
| 186 |
First the desired new position is checked to be in the valid range. |
| 187 |
</p> |
| 188 |
|
| 189 |
<p> |
| 190 |
If it is greater than the page length minus one screenwidth, it is set to that |
| 191 |
value. (The last page line can't move above the bottom screen line this way.) |
| 192 |
</p> |
| 193 |
|
| 194 |
<p> |
| 195 |
If smaller then zero, it is set to zero. (The page top can't move below the |
| 196 |
screen top.) Note that this will undo the above check, if the output page is |
| 197 |
smaller than one screenfull -- in this case, the page end is always above the |
| 198 |
screen end. |
| 199 |
</p> |
| 200 |
|
| 201 |
<p> |
| 202 |
Now that we know the real destination position, the difference to the present |
| 203 |
position (stored in the static "old_line") is calculated. |
| 204 |
</p> |
| 205 |
|
| 206 |
<p> |
| 207 |
If the absolute value of that difference is not more than a screenfull, |
| 208 |
scrolling is used. This is done by the insdelln() curses function, called with |
| 209 |
the cursor being in the first screen line. (Called with a negative value it |
| 210 |
deletes lines, causing the screen contents to scroll up; called with a positive |
| 211 |
argument, it inserts lines, causing the screen contents to scroll down.) |
| 212 |
</p> |
| 213 |
|
| 214 |
<p> |
| 215 |
After scrolling, the new lines revealed at the top or bottom of the screen need |
| 216 |
to be rendered. After scrolling down (negative "scroll_lines"), the first |
| 217 |
"scroll_lines" of the screen have to be repainted. This is done by calling |
| 218 |
render() with "scroll_lines" as the height, 0 as the screen position (the first |
| 219 |
lines of the screen are repainted), and "new_line" as page position. |
| 220 |
("new_line" contains the page position of the first screen line.) |
| 221 |
</p> |
| 222 |
|
| 223 |
<p> |
| 224 |
After scrolling up, the last screen lines have to be repainted. This is done |
| 225 |
similar. The hight is "-scroll_lines" ("scroll_lines" is negative when |
| 226 |
scrolling up), the screen position is the screen end minus "-sroll_lines", and |
| 227 |
the page position is the page position of the first screen line ("new_line") |
| 228 |
plus the screen position of the rendered area. |
| 229 |
</p> |
| 230 |
|
| 231 |
<p> |
| 232 |
If the difference is too big for scrolling, the whole screen is erased and |
| 233 |
repainted. |
| 234 |
</p> |
| 235 |
|
| 236 |
<p> |
| 237 |
The first time this function is called, "old_line" has the value PAGE_INVALID |
| 238 |
(defined as the biggest possible positive int value), indicating that the |
| 239 |
screen contains nothing valid yet. There is no special handling necessary for |
| 240 |
this case -- "scroll_lines" gets a very big value, and thus the whole screen is |
| 241 |
always repainted. |
| 242 |
</p> |
| 243 |
|
| 244 |
<p> |
| 245 |
Finally, the cursor position is updated, if necessary. If the cursor is no |
| 246 |
longer on the screen (more exactly, inside the active screen area), it is set |
| 247 |
to the home position with <a href="#setCursor">set_cursor()</a>. |
| 248 |
If the "sticky_cursor" flag is not set, the cursor is always homed. |
| 249 |
</p> |
| 250 |
|
| 251 |
</a> <!-- scrollTo --> |
| 252 |
|
| 253 |
<h2>Cursor Movement Commands</h2> |
| 254 |
|
| 255 |
<p> |
| 256 |
Just like the scrolling commands, the cursor movement commands are all |
| 257 |
implemented by single calls to a specific function (set_cursor()) with the |
| 258 |
desired new position, which is calculated from the current one. |
| 259 |
</p> |
| 260 |
|
| 261 |
<a name="setCursor" id="setCursor"> |
| 262 |
|
| 263 |
<h3>set_cursor()</h3> |
| 264 |
|
| 265 |
<p> |
| 266 |
set_cursor() is responsible for setting the cursor to some desired page |
| 267 |
position (not screen position!). It also sets the "sticky_cursor" flag, so that |
| 268 |
the cursor will stay in it's place (again, page position) until reset. |
| 269 |
</p> |
| 270 |
|
| 271 |
<p> |
| 272 |
If called with -1 as x and y position, the "sticky_cursor" flag is cleared instead, |
| 273 |
and the cursor set to the home position -- which is column 0 in the first line |
| 274 |
inside the active screen area. |
| 275 |
</p> |
| 276 |
|
| 277 |
<p> |
| 278 |
If the requested new position is outside the present active screen area, the |
| 279 |
page first needs to be scrolled. If the position is before the active screen |
| 280 |
area, we scroll as many lines back as the position is outside; if it is behind |
| 281 |
the active area, we scroll as many lines forward. |
| 282 |
</p> |
| 283 |
|
| 284 |
<p> |
| 285 |
Now we test whether the requested position is on the screen, and truncate if |
| 286 |
not. The y position is actually tested against the page boundaries (after |
| 287 |
scrolling, those should be equal in case the requested position is outside); |
| 288 |
only the x position is tested against the screen boundaries, as there is |
| 289 |
presently no x scrolling. |
| 290 |
</p> |
| 291 |
|
| 292 |
<p> |
| 293 |
Finally, we test whether there is some link at the new cursor position. If |
| 294 |
there is one, and it wasn't already active, we activate it now. (Using |
| 295 |
<a href="hacking-links.html#activateLink">activate_link()</a>, |
| 296 |
see hacking-links.*.) If there was a link active up to now, but there is no |
| 297 |
link at the new position, the old one is deactivated. (activate_link() does |
| 298 |
this automatically, as -1 will be passed as the link number in this situation.) |
| 299 |
</p> |
| 300 |
|
| 301 |
<p> |
| 302 |
Only now the cursor is set to the new position, and the sticky status set. (Or |
| 303 |
reset, if homing.) |
| 304 |
</p> |
| 305 |
|
| 306 |
</a> <!-- setCursor --> |
| 307 |
|
| 308 |
<a name="select" id="select"> |
| 309 |
|
| 310 |
<h2>Link Selection Commands</h2> |
| 311 |
|
| 312 |
<p> |
| 313 |
As explained under <a href="#display">display()</a> above, the |
| 314 |
pager keeps track of the current active link by the "active_link" variable in |
| 315 |
the "page" struct. (-1 means no link is active.) |
| 316 |
</p> |
| 317 |
|
| 318 |
<p> |
| 319 |
All link selection commands are implemented using a generic link search |
| 320 |
function to find out which link to activate, and then just activating it with |
| 321 |
<a href="hacking-links.html#activateLink">activate_link()</a> (see |
| 322 |
hacking-links.*). |
| 323 |
</p> |
| 324 |
|
| 325 |
<a name="findLink" id="findLink"> |
| 326 |
|
| 327 |
<h3>find_link()</h3> |
| 328 |
|
| 329 |
<p> |
| 330 |
Finding the link to activate is done with the find_link() function. This |
| 331 |
function is flexible enough to implement almost all link selection commands |
| 332 |
with only one invocation. |
| 333 |
</p> |
| 334 |
|
| 335 |
<p> |
| 336 |
find_link() looks for the first link or the last link (depending on |
| 337 |
"match_type") inside a desired range. |
| 338 |
</p> |
| 339 |
|
| 340 |
<p> |
| 341 |
The search area is primarily specified by the coordinates "start_x", "start_y" |
| 342 |
and "end_x", "end_y", enclosing a part of the page inside which the links to be |
| 343 |
considered have to *start*. (As usual, the start coordinates give the first |
| 344 |
allowed positin, while the end coordinates give the first invalid position.) |
| 345 |
Note that regardless of the beginning and end positions being given by |
| 346 |
coordinate pairs, the range is actually linear: It spanns from the start |
| 347 |
position to the end of the line, includes (in whole) the following lines till |
| 348 |
"end_y", and concludes with the beginning of the line "end_y" before the end |
| 349 |
position. |
| 350 |
</p> |
| 351 |
|
| 352 |
<p><pre> |
| 353 |
line zero |
| 354 |
|
| 355 |
line one with <zeroth link> in it |
| 356 |
|
| 357 |
line two with <firST LINK> IN IT <-- start_y |
| 358 |
^start_x |
| 359 |
LINE THREE WITH <SECOND LINK> IN IT |
| 360 |
|
| 361 |
LINE FOUR |
| 362 |
|
| 363 |
LINE FIVE WITH <THIRD LInk> in it <-- end_y |
| 364 |
^end_x |
| 365 |
line six with <fourth link> in it |
| 366 |
</pre></p> |
| 367 |
|
| 368 |
<p> |
| 369 |
(The second and third links are inside the area, the zeroth, first, and fourth |
| 370 |
not.) |
| 371 |
</p> |
| 372 |
|
| 373 |
<p> |
| 374 |
There is one additional parameter limiting the search area: "end_line" limits |
| 375 |
the range where links can *end*. (As usual, it gives the first invalid line.) |
| 376 |
This is necessary as some commands only activate links that are already inside |
| 377 |
the screen completely. |
| 378 |
</p> |
| 379 |
|
| 380 |
<p> |
| 381 |
"end_line" or "end_x" and "end_y" can be specified alternatively, or both -- |
| 382 |
only links inside both ranges will be considered. |
| 383 |
</p> |
| 384 |
|
| 385 |
<p> |
| 386 |
If any of the y paramaters ("start_y", "end_y", "end_line") is given as "-1", |
| 387 |
it is ignored, i.e. the range extends to the end beginning/end of the page. For |
| 388 |
the x parameters, the behaviour is more complicated: "-1" actually means that |
| 389 |
the range starts/ends *before* the beginning of the line; thus, "start_x" being |
| 390 |
-1 means the whole "start_y" line is inside the range, but "end_x" being -1 |
| 391 |
means the whole line is *outside* the range, i.e. only links ending *before* |
| 392 |
"end_y" are accepted. (Just as with "end_line" and other range ends.) This may |
| 393 |
look confusing at first, but it is consistent: Giving "end_x" means that the |
| 394 |
beginning of the "end_y" line is inside the range *additionally* to the lines |
| 395 |
before "end_y", just as "start_x" means the beginning of the "start_x" line is |
| 396 |
not inside. If this isn't clear, take another look at the figure above, and |
| 397 |
imagine what happens when "start_x" and/or "start_y" are moved to the beginning |
| 398 |
of the line. |
| 399 |
</p> |
| 400 |
|
| 401 |
<p> |
| 402 |
The implemetation of find_link() is actually fairly small, though not simple. |
| 403 |
</p> |
| 404 |
|
| 405 |
<p> |
| 406 |
First, two macros are defined: INSIDE_START() testing whether "link" starts |
| 407 |
behind the beginning of the range (i.e. whether "start_x" and "start_y" are |
| 408 |
fulfilled), and INSIDE_END(), which tests the end of the area -- both the end |
| 409 |
of the link start range ("end_x" and "end_y") and the link end ("end_line"). |
| 410 |
</p> |
| 411 |
|
| 412 |
<p> |
| 413 |
The first step is finding the candidate link -- when "match_type" is |
| 414 |
FIND_FIRST, this is the first link starting after the beginning of the range, |
| 415 |
and with FIND_LAST the last link before the end of the range. |
| 416 |
</p> |
| 417 |
|
| 418 |
<p> |
| 419 |
The candidate located using a binary search. (Note that "first" and "last" are |
| 420 |
really only helper variables for the search, just like "mid". The fact that, |
| 421 |
depending on "match_type", one of those is actually the result, is only a side |
| 422 |
effect of the search algorithm; but the respective other one is only garbage. |
| 423 |
You should *not* confuse them for always being the first and last link inside |
| 424 |
the area -- only one of the bounds is checked in this search!) |
| 425 |
</p> |
| 426 |
|
| 427 |
<p><pre> |
| 428 |
link0 link1 link2 link3 link4 |
| 429 |
start =>| ^candidate |
| 430 |
</pre></p> |
| 431 |
|
| 432 |
<p> |
| 433 |
Now we test whether the candidate is actually a valid link (inside the link |
| 434 |
number range), i.e. there are *any* links inside the boundary. |
| 435 |
</p> |
| 436 |
|
| 437 |
<p> |
| 438 |
Finally, the other boundary has to be tested. |
| 439 |
</p> |
| 440 |
|
| 441 |
<p><pre> |
| 442 |
link0 link1 link2 link3 link4 |
| 443 |
=>| ^ |<= end |
| 444 |
|------------->| |
| 445 |
candidate < end => OK |
| 446 |
</pre></p> |
| 447 |
|
| 448 |
<p> |
| 449 |
(If there are no links inside the range, still a candidate matching the first |
| 450 |
bound may have been found.) |
| 451 |
</p> |
| 452 |
|
| 453 |
<p><pre> |
| 454 |
link0 link1 link2 link3 link4 |
| 455 |
=>| |<= ^ |
| 456 |
|<----| |
| 457 |
candidate > end => nothing in range |
| 458 |
</pre></p> |
| 459 |
|
| 460 |
<p> |
| 461 |
If no link matching the criteria was found, find_link() returns -1. |
| 462 |
</p> |
| 463 |
|
| 464 |
</a> <!-- findLink --> |
| 465 |
|
| 466 |
<h3>active_start() and active_end()</h3> |
| 467 |
|
| 468 |
<p> |
| 469 |
Cheking whether a link is (or would be) inside the valid screen area for active |
| 470 |
links, primarily during link selection but also in a few other places, is done |
| 471 |
using the active_start() and active_end() functions. These simply return the |
| 472 |
bounds of the valid area (in page coordinates, not screen coordinates!). |
| 473 |
</p> |
| 474 |
|
| 475 |
<p> |
| 476 |
Normally, the area starts in the line that shows up at the screen top (i.e. |
| 477 |
"pager_pos") plus "cfg.link_margin" -- this is one line below the screen top |
| 478 |
with the default setting. The end is the last line on screen minus the link |
| 479 |
margin, accordingly. (But note that active_end returns the number of the *first |
| 480 |
invalid* line, i.e. *after* the end of the valid area, as all end coordinates |
| 481 |
are specfied this way!) |
| 482 |
</p> |
| 483 |
|
| 484 |
<p> |
| 485 |
An exception is the pager being at the top (for active_start()) or bottom (for |
| 486 |
active_end()) of the page -- in this case the valid area includes the first or |
| 487 |
last page lines, as these can never move into the normal valid area. (The page |
| 488 |
top can't ever move below the screen top; same for bottom.) |
| 489 |
</p> |
| 490 |
|
| 491 |
<p> |
| 492 |
The "pos" parameter allows specifying some other pager position (relative to |
| 493 |
the current "page->pager_pos") to check; 0 means using the current position. |
| 494 |
</p> |
| 495 |
|
| 496 |
<h3>Command Implementations</h3> |
| 497 |
|
| 498 |
<p> |
| 499 |
Thanks to the powerful <a href="#findLink">find_link()</a> |
| 500 |
function, the commands are actually very simple. Most commands just consist of |
| 501 |
one call to find_link() to find the new link, and a call to |
| 502 |
<a href="hacking-links.html#activateLink">activate_link()</a> with |
| 503 |
the new link number to activate it. |
| 504 |
</p> |
| 505 |
|
| 506 |
<p> |
| 507 |
The simplest commands are those independant of the current cursor position. |
| 508 |
('H', 'L', 'M') These just pass a range of line numbers (aquired with |
| 509 |
active_start() and active_end()) to find_link(). |
| 510 |
</p> |
| 511 |
|
| 512 |
<p> |
| 513 |
Many commands however search forward or backward starting from the current |
| 514 |
cursor position. These just pass the cursor position as the start (for those |
| 515 |
searching forward) or the end of the search range, respectively. There is one |
| 516 |
little complication when searching forward: If a link is active already |
| 517 |
(implying the cursor is at the link start), a search starting with the cursor |
| 518 |
position will always give the active link again. Thus, "x_start" needs to be |
| 519 |
incremented by one in this case. |
| 520 |
</p> |
| 521 |
|
| 522 |
<p> |
| 523 |
The other end of the range depends on how far the specific command searches: |
| 524 |
Some (<tab>, 'p') search till the end of the document, while others ('J', 'K', |
| 525 |
and also '+' and '-') only to the end of the active screen area, optionally |
| 526 |
with scrolling one line. |
| 527 |
</p> |
| 528 |
|
| 529 |
<p> |
| 530 |
The latter also have to test whether a link was actually found in the desired |
| 531 |
area, and just scroll one line with |
| 532 |
<a href="#scrollTo">scroll_to()</a> otherwise. |
| 533 |
</p> |
| 534 |
|
| 535 |
<p> |
| 536 |
Some commands ('+', '-', '^', ' and '0') do not directly search from the |
| 537 |
cursor position, but in a range relative to the cursor line. Those are very |
| 538 |
similar. Two of them are more complicated however: |
| 539 |
</p> |
| 540 |
|
| 541 |
<p> |
| 542 |
'-' is complicated, because it has to find the first link in some range (the |
| 543 |
previous line having any links), but the beginning of that range isn't fixed -- |
| 544 |
there might be already links in the previous line, but we might also have to go |
| 545 |
a few lines back. Before we can search for the desired link, we have to find |
| 546 |
out the line where to search. This is done with another invocation of |
| 547 |
find_link(), looking for the last link starting before the current line; as |
| 548 |
this link is obviously in the previous line having links, we can use this |
| 549 |
link's starting line as the beginning of our search range. |
| 550 |
</p> |
| 551 |
|
| 552 |
<p><pre> |
| 553 |
a line with the <first link> |
| 554 |
|
| 555 |
a line with the <second link> and the <third link> <-- start_y=new_link->y_start |
| 556 |
~~~~~~~~~~~~~goal ^^^^^^^^^^^^new_link (helper) |
| 557 |
a line with no links |
| 558 |
|
| 559 |
another line with no links |
| 560 |
|
| 561 |
a line with the <fourth link> <-- page->cursor_y |
| 562 |
^cursor position |
| 563 |
another line |
| 564 |
</pre></p> |
| 565 |
|
| 566 |
<p> |
| 567 |
'0' is complicated, because -- opposite to all other commands -- it has to find |
| 568 |
a link *ending* in or after some given line. find_link() has no provision for |
| 569 |
that; extending it in this way just for this single command would be stupid. |
| 570 |
</p> |
| 571 |
|
| 572 |
<p> |
| 573 |
Thus, we have to use a trick: We first search for the last link ending *before* |
| 574 |
the current line (so we can use the existing "end_line" parameter), and then |
| 575 |
just look for the next link -- which is obviosly the first one ending in or |
| 576 |
after the current line. |
| 577 |
</p> |
| 578 |
|
| 579 |
</a> <!-- select --> |
| 580 |
|
| 581 |
<h2>History Commands</h2> |
| 582 |
|
| 583 |
<p> |
| 584 |
The history commands all work alike: |
| 585 |
</p> |
| 586 |
|
| 587 |
<p> |
| 588 |
'b' goes back to the previous page by setting the current position in the |
| 589 |
history one backwards (decrementing). The page is then (re)loaded by quitting |
| 590 |
the pager with "RET_HISTORY" -- main() then invokes the necessary actions for |
| 591 |
loading the page, before restarting display(). |
| 592 |
(<a href="hacking-page.html#loadPage">load_page()</a> and |
| 593 |
<a href="hacking-load.html#initLoad">init_load()</a> take care for |
| 594 |
correct loading of pages from history.) |
| 595 |
</p> |
| 596 |
|
| 597 |
<p> |
| 598 |
'f' goes forward in the same manner (incrementing "pos"). |
| 599 |
</p> |
| 600 |
|
| 601 |
<p> |
| 602 |
'B' searches the history backwards, until it finds some page that is followed |
| 603 |
either by one with the "absolute" flag set or by an internal page (the internal |
| 604 |
page is treated like a new site). If nothing is found the search stops at the |
| 605 |
first entry in the history, and that one is taken. |
| 606 |
</p> |
| 607 |
|
| 608 |
<p> |
| 609 |
'F' searches forwards, also looking for a page followed by an absoulte URL. The |
| 610 |
last entry is taken if nothing was found. |
| 611 |
</p> |
| 612 |
|
| 613 |
<p> |
| 614 |
'^r' causes the current page to be reloaded, by returning RET_HISTORY, but not |
| 615 |
changing the position in the page list. Thus it is not really a history command |
| 616 |
from the user's point of view -- but technically, it is. |
| 617 |
</p> |
| 618 |
|
| 619 |
<p> |
| 620 |
'r' searches backwards for a page with "mark" set. It also takes the first page |
| 621 |
if nothing was found; 'R' does the same forwards. |
| 622 |
</p> |
| 623 |
|
| 624 |
<p> |
| 625 |
The marks are set by the 's' command. This one simply sets the "mark" flag of |
| 626 |
the current "page" structure. |
| 627 |
</p> |
| 628 |
|
| 629 |
<h2>Link Following</h2> |
| 630 |
|
| 631 |
<p> |
| 632 |
When a link is followed by typing <return>, "RET_LINK" is returned, and the |
| 633 |
main program follows the current "active_link". This process is described under |
| 634 |
<a href="hacking-links.html#followLink">main()</a> in |
| 635 |
hacking-links.*. |
| 636 |
</p> |
| 637 |
|
| 638 |
<h2>URL commands</h2> |
| 639 |
|
| 640 |
<p> |
| 641 |
The 'u' command causes display() to return "RET_LINK_URL"; main() then shows |
| 642 |
the URL of the currently active link. |
| 643 |
</p> |
| 644 |
|
| 645 |
<p> |
| 646 |
'c' returns "RET_URL", and main() shows the current page URL. |
| 647 |
</p> |
| 648 |
|
| 649 |
<p> |
| 650 |
'U' returns "RET_ABSOLUTE_URL", causing main() to print the absolute link |
| 651 |
target URL which is used when the link is actually followed. |
| 652 |
</p> |
| 653 |
|
| 654 |
<h2>Other Commands</h2> |
| 655 |
|
| 656 |
<p> |
| 657 |
When 'q' is typed the pager simply returns with "RET_QUIT", indicating that the |
| 658 |
main program should quit also. |
| 659 |
</p> |
| 660 |
|
| 661 |
<p> |
| 662 |
When ':' is typed the pager quits too, but returns "RET_COMMAND"; this means |
| 663 |
that the main program should enter command mode. |
| 664 |
</p> |
| 665 |
|
| 666 |
<p> |
| 667 |
'/' is very similar: "pager_ret" is set to "RET_SEARCH"; additionally, |
| 668 |
"search.type" is set to "SEARCH_FORWARD". |
| 669 |
</p> |
| 670 |
|
| 671 |
</body> |
| 672 |
</html> |