diff options
Diffstat (limited to 'doc/DwStyle.txt')
| -rw-r--r-- | doc/DwStyle.txt | 310 |
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. |