diff options
Diffstat (limited to 'doc/DwPage.txt')
| -rw-r--r-- | doc/DwPage.txt | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/doc/DwPage.txt b/doc/DwPage.txt new file mode 100644 index 00000000..71e6af88 --- /dev/null +++ b/doc/DwPage.txt @@ -0,0 +1,152 @@ +Nov 2001, S.Geerken@ping.de +Last update: Dec 2004 + +====== +DwPage +====== + +A widget for displaying texts. It is (currently) the main widget for +rendering HTML documents. + + +Signals +======= + +DwPage defines the same signals as DwImage, except "image_pressed", +with the exception that the coordinates are always -1. See +DwImage.txt for more details. + + +Collapsing Spaces +================= + +The idea behind this is that every text box has a specific vertical +space around and that they are combined to one space, according to +rules stated below. A rule is either a paragraph within a DwPage +widget, or a DwPage within a DwPage widget, in a single line; the +latter is used for indented boxes and list items. + +The rules: + + 1. If a box is following another, the space between them is the + maximum of both box spaces: + + +---------+ + |/////////| + |/////////| +---------+ + +---------+ |/////////| + | A | |/////////| + +---------+ +---------+ + |/////////| | A | + |/////////| +---------+ + +---------+ are combined like this: |/////////| + |XXXXXXXXX| + +---------+ +---------+ + |\\\\\\\\\| | B | + +---------+ +---------+ + | B | |\\\\\\\\\| + +---------+ +---------+ + |\\\\\\\\\| + +---------+ + + 2. a) If one box is the first box within another, the upper space + of these boxes collapse. b) The analogue is the case for the + last box: + + +---------+ If B and C are put into A, + |/////////| the result is: + |/////////| + +---------+ +---------+ +---------+ + | A | <--+-- |\\\\\\\\\| |/////////| + +---------+ ¦ +---------+ |XXXXXXXXX| + |/////////| | | B | +---------+ + |/////////| | +---------+ | B | + +---------+ | |\\\\\\\\\| +---------+ + | +---------+ |\\\\\\\\\| + | |\\\\\\\\\| + | +---------+ |\\\\\\\\\| + `-- |\\\\\\\\\| +---------+ + |\\\\\\\\\| | C | + |\\\\\\\\\| +---------+ + +---------+ |\\\\\\\\\| + | C | |XXXXXXXXX| + +---------+ |XXXXXXXXX| + |\\\\\\\\\| +---------+ + |\\\\\\\\\| + |\\\\\\\\\| + +---------+ + +For achieving this, there are some features of DwPage: + + - Consequent breaks are automatically combined, according to + rule 1. See the code of a_Dw_page_add_break for details. + + - If a break is added as the first word of the DwPage within + another DwPage, collapsing according to rule 2a is done + automatically. See the code of a_Dw_page_add_break. + + - To collapse spaces according to rule 2b, + a_Dw_page_hand_over_break must be called for the *inner* + widget. The HTML parser does this in Html_eventually_pop_dw. + + +Collapsing Margins +================== + +Collapsing margins, as defined in the CSS2 specification, are, +supported in addition to collapsing spaces. Also, spaces and margins +collapse themselves. I.e., the space between two paragraphs is the +maximum of the space calculated as described in "Collapsing Spaces" +and the space calculated according to the rules for collapsing margins. + +(This is an intermediate hybrid state, collapsing spaces are used in +the current version of dillo, while I implemented collapsing margins +for CSS and integrated it already into the main trunk. For a pure +CSS-based dillo, collapsing spaces will not be needed anymore, and may +be removed for simplicity.) + + +Some Internals +============== + +There are two lists, words and lines. The word list is quite static; +only new words may be added. A word is either text, a widget, a break +or an anchor. Anchors are stored in the text, because it may be +necessary to correct the scroller positions at rewrapping. + +Lines refer to the word list (first and last), they are completely +redundant, i.e., they can be rebuilt from the words. Lines can be +rewrapped either completely or partially (see "Incremental Resizing" +below). For the latter purpose, several values are accumulated in the +lines. See the file "dw_page.h" for details. + + +Incremental Resizing +-------------------- +DwPage makes use of incremental resizing as described in Dw.txt, +section "Resizing". The parent_ref is, for children of a DwPage, +simply the number of the line. + +Generally, there are three cases which may change the size of the +widget: + + 1. The available size of the widget has changed, e.g., because the + user has changed the size of the browser window. In this case, + it is necessary to rewrap all the lines. + + 2. A child widget has changed its size. In this case, only a rewrap + down from the line where this widget is located is necessary. + + (This case is very important for tables. Tables are quite at the + bottom, so that a partial rewrap is relevant. Otherwise, tables + change their size quite often, so that this is necessary for a + fast, non-blocking rendering) + + 3. A word (or widget, break etc.) is added to the page. This makes + it possible to reuse the old size by simply adjusting the + current width and height, so no rewrapping is necessary. + +The state of the size calculation is stored in wrap_ref within DwPage, +which has the value -1 if no rewrapping of lines necessary, or +otherwise the line from which a rewrap is necessary. + |