Initial revision

1 files changed, 310 insertions, 0 deletions

diff --git a/doc/DwStyle.txt b/doc/DwStyle.txt
new file mode 100644
index 00000000..9a1ec4e5
--- /dev/null
+++ b/doc/DwStyle.txt
@@ -0,0 +1,310 @@
+Apr 2001, S.Geerken@ping.de
+Last update: Dec 2004
+
+=======
+DwStyle
+=======
+
+Styles of Dillo Widgets
+
+
+Note
+====
+
+DwStyle has derived from DwPageAttr, and its current structure is very
+similar to it. In the future, there will be some changes and extensions.
+Namely:
+
+   - image maps will be handled differently (done),
+   - margins, borders, paddings (done),
+   - background colors/images, and
+   - cursors and tooltips will perhaps move into DwStyle.
+
+Furthermore, widgets will probably refer to different styles for
+different states.
+
+
+Overview
+========
+
+DwStyle provides some resources and attributes for drawing widgets, as
+well as for parts of a widget (e.g., DwPage uses DwStyle's for its
+words). Creating a style is done by filling a DwStyle with the
+attributes (except the ref_count), and calling Dw_style_new:
+
+   DwStyle style_attrs, *style;
+
+   style_attrs.foo = bar;
+   // etc.
+   style = a_Dw_style_new (&style_attrs, random_window);
+   // do something with style
+
+After this, the attributes of style should not be changed anymore,
+since styles are often shared between different widgets etc. (see
+below). Most times, you simply copy the attributes of another style
+and modify them:
+
+   style_attrs = *another_style;
+   style_attrs.foo = bar;
+   style = a_Dw_style_new (&style_attrs, random_window);
+
+The font structure can be created by Dw_style_font_new, in a similar
+way (the GdkFont in font_attrs will be ignored), and colors by
+Dw_style_color_new, passing 0xrrggbb as an argument. Note that fonts
+and colors are only intended to be used in conjunction with DwStyle.
+
+
+Lengths and Percentages
+=======================
+
+DwStyleLength is a simple data type for lengths and percentages:
+
+   - A length refers to an absolute measurement. It is used to
+     represent the HTML type %Pixels; and the CSS type <length>.
+
+     For CSS lenghts, there are two units: (i) pixels and absolute
+     units, which have to be converted to pixels (a pixel is, unlike
+     in the CSS specification, treated as absolute unit), and (ii) the
+     relative units "em" and "ex" (see below).
+
+   - A percentage refers to a value relative to another value. It is
+     used for the HTML type %Length; (except %Pixels;), and the CSS
+     type <percentage>.
+
+   - A relative length can be used in lists of HTML MultiLengths.
+
+Since many values in CSS may be either lengths or percentages, a
+single type is very useful.
+
+Useful macros and functions
+---------------------------
+Macros for creating lengths:
+
+   DW_STYLE_CREATE_LENGTH (n)      Returns a length of n pixels.
+
+   DW_STYLE_CREATE_EX_LENGTH (n)   Returns a length of n times the
+                                   'x-height'
+
+   DW_STYLE_CREATE_EM_LENGTH (n)   Returns a length of n times the
+                                   'font-size'
+
+   DW_STYLE_CREATE_PERCENTAGE (n)  Returns a percentage, n is relative
+                                   to 1, not to 100.
+
+   DW_STYLE_CREATE_RELATIVE (n)    Returns a relative length.
+
+   DW_STYLE_UNDEF_LENGTH           Used to indicate unspecified sizes,
+                                   errors, and the end of a list of
+                                   lengths.
+
+Furthermore, there are some functions in html.c:
+
+   DwStyleLength Html_parse_length (gchar *attr);
+
+      Returns a length or a percentage, or DW_STYLE_UNDEF_LENGTH in
+      case of an error.
+
+   DwStyleLength* Html_parse_multi_length (gchar *attr);
+
+      Returns a vector of lengths/percentages. The caller has to free
+      the result when it is not longer used.
+
+Macros for examining lengths:
+
+   DW_STYLE_IS_LENGTH (l)          Returns TRUE if l is a length.
+
+   DW_STYLE_IS_PERCENTAGE (l)      Returns TRUE if l is a percentage.
+
+   DW_STYLE_IS_RELATIVE (l)        Returns TRUE if l is a relative
+                                   length.
+
+   DW_STYLE_GET_LENGTH (l, f)      Returns the value of a length in
+                                   pixels, as an integer. f is the
+                                   font, this is used if l is based on
+                                   font sizes.
+
+   DW_STYLE_GET_PERCENTAGE (l)     Returns the value of a percentage,
+                                   relative to 1, as a float.
+
+   DW_STYLE_GET_RELATIVE (l)       Returns the value of a relative
+                                   length, as a float.
+
+
+Representation
+--------------
+Notes:
+
+   1. This is not part of the interface and may change! Use the
+      macros described above.
+   2. Negative numbers may not work yet.
+
+DwStyleLength is represented by an integer (n is the number of bits of
+an integer):
+
+   - Undefined lengths are represented by 0.
+
+   - Lenghts in pixel:
+
+      +---+ - - - +---+---+---+---+
+      |     int value     | 0 | 1 |
+      +---+ - - - +---+---+---+---+
+       n-1          3   2   1   0
+
+   - Lengths in in x-height:
+
+      +---+ - - - +---+---+---+---+
+      |  real value   | 0 | 1 | 1 |
+      +---+ - - - +---+---+---+---+
+       n-1          3    2   1   0
+
+   - Lengths in in font-size:
+
+      +---+ - - - +---+---+---+---+
+      |  real value   | 1 | 1 | 1 |
+      +---+ - - - +---+---+---+---+
+       n-1          3   2   1   0
+
+   - Percentages:
+
+      +---+ - - - +---+---+---+---+
+      |  real value   | 0 | 1 | 0 |
+      +---+ - - - +---+---+---+---+
+       n-1          3   2   1   0
+
+   - Relative lengths:
+
+      +---+ - - - +---+---+---+---+
+      |  real value   | 1 | 1 | 0 |
+      +---+ - - - +---+---+---+---+
+       n-1          3   2   1   0
+
+A "real value" is a fixed point number consisting of (m is the number
+of bits of the value, not the whole integer):
+
+   +---+ - - - +---+---+ - - - +---+
+   | integer part  |     rest      |
+   +---+ - - - +---+---+ - - - +---+
+     m           16  15          0
+
+For *internal* use, there are two converting macros,
+DW_STYLE_REAL_TO_FLOAT and DW_STYLE_FLOAT_TO_REAL.
+
+
+DwStyle Boxes
+=============
+
+The CSS Box Model
+-----------------
+For borders, margins etc., DwStyle uses the box model defined by
+CSS2. DwStyle contains some members defining these attributes. A
+widget must use these values for any calculation of sizes. There are
+some helper functions (see dw_style.h). A DwStyle box looks quite
+similar to a CSS box:
+
+                   
+                 ,-- margin.left
+                 |   ,-- border.left
+                 |   |   ,-- padding.left
+                 |---+---+---|
+                 +---------------------------------------+ ---
+                 |                                       |  |  margin.top
+                 |   +-------------------------------+   | -+-
+                 |   |          Border               |   |  |  border.top
+                 |   |   +-----------------------+   |   | -+-
+                 |   |   |        Padding        |   |   |  |  padding.top
+   new widget    |   |   |   +---------------+   |   |   | ---
+   allocation -->|   |   |   |               |   |   |   |
+                 |   |   |   |    Content    |   |   |   |
+  former widget ------------>|               |   |   |   |
+   allocation    |   |   |   +---------------+   |   |   | ---
+                 |   |   |                       |   |   |  |  margin.bottom
+                 |   |   +-----------------------+   |   | -+-
+                 |   |                               |   |  |  border.bottom
+                 |   +-------------------------------+   | -+-
+                 |                                       |  |  padding.bottom
+                 +---------------------------------------+ ---
+                                             |---+---+---|
+                              padding.right  --'   |   |
+                                    border.right --'   |
+                                        margin.right --'
+
+Background colors
+-----------------
+The background color is stored in style->background_color, which be
+NULL (the background color of the parent widget is shining through).
+
+For toplevel widgets, this color is set as the background color of the
+viewport, for other widgets, a filled rectangle is drawn, covering the
+content and padding. (This is compliant with CSS2, the background
+color of the toplevel element covers the whole canvas.)
+
+Drawing
+-------
+There is a new function Dw_widget_draw_widget_box, which should be
+called at the beginning of Dw_foo_draw. For parts referring to styles
+(e.g., words in a page), Dw_widget_draw_box should be used.
+
+
+Notes on Memory Management
+==========================
+
+Memory management is done by reference counting, a_Dw_style_new
+returns a pointer to DwStyle with an increased reference counter, so
+you should care about calling Dw_style_unref if it is not used
+anymore. You do *not* need to care about the reference counters of
+fonts and styles.
+
+In detail:
+
+   - a_Dw_style_ref is called in
+
+        * a_Dw_widget_set_style, to assign a style to a widget,
+
+        * a_Dw_page_add_text, a_Dw_page_add_widget,
+          a_Dw_page_add_anchor, to assign a style to a word,
+
+        * and Html_push_tag (often the reference counter is again
+          decreased shortly after this).
+
+   - a_Dw_unref_style is called in:
+
+        * Dw_page_destroy, Dw_widget_destroy, Html_cleanup_tag,
+          Html_pop_tag, Html_close,
+
+        * a_Dw_widget_set_style, Html_set_top_font (and several
+          Html_tag_open_... functions), these functions overwrite an
+          existing style.
+
+
+HTML Stack
+==========
+
+(This is not DwStyle specific, but may be useful if you are working on
+the HTML parser.)
+
+The topmost element of the HTML stack contains a (reference to a)
+style which will be used to add the text to the current page. If you
+use a style only for a short while (see Html_tag_open_frame for an
+example), you may use it this way:
+
+   style_attrs = *html->stack[html->stack_top].style;
+   style_attrs.foo = bar;
+   style = a_Dw_style_new (&style_attrs, random_window);
+
+Do not forget to unref it afterwards. A good choice for random_window
+is html->bw->main_window->window.
+
+In many cases, you want to set the style for the content of an element
+(e.g., <A>). Then you must store it in the stack:
+
+   DwStyle style_attrs, *old_style;
+
+   old_style = html->stack[html->stack_top].style;
+   style_attrs = *old_style;
+   style_attrs.foo = bar;
+   html->stack[html->stack_top].style =
+      a_Dw_style_new (&style_attrs, random_window);
+   a_Dw_style_unref (old_style);
+
+The macro HTML_SET_TOP_ATTR can be used for single attributes, for
+changing more attributes, this code should be copied for efficiency.