Mercurial > dillo_port1.3
changeset 394:0c759db427b5
- Removed obsolete Dw* documentation.
| author | jcid |
|---|---|
| date | Wed, 08 Oct 2008 15:37:46 +0200 |
| parents | c3bafcdde88a |
| children | 094b63be5d0f |
| files | doc/Dw.txt doc/DwImage.txt doc/DwPage.txt doc/DwRender.txt doc/DwStyle.txt doc/DwTable.txt doc/DwWidget.txt |
| diffstat | 7 files changed, 4 insertions(+), 2203 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/Dw.txt Tue Oct 07 21:01:41 2008 +0200 +++ b/doc/Dw.txt Wed Oct 08 15:37:46 2008 +0200 @@ -1,383 +1,11 @@ -Jan 2001, S.Geerken@ping.de -Last update: Dec 2004 +Last update: Oct 2008 ================ Dw: Dillo Widget ================ -NOTE (Aug 2004): The rendering has changed quite much, and many other -documents are out of date, in ways described in DwRendering.txt. They -will be updated some day. - -Dw is mainly the module for rendering HTML. It provides a framework -for widgets, based on the Gtk+ object framework, and is very similar -to Gtk+, so that experiences in using and extending Gtk+ help very -much in understanding Dw. There is some documentation at www.gtk.org -(and probably on your local harddisk, somewhere in /usr/doc/*gtk*), -you should especially have read the chapter "Writing Your Own -Widgets" in the tutorial. - - -Why Not Gtk+? -============= - -There are two reasons for designing a new model instead of simply -using Gtk+ objects: - - 1. Most important, Gtk+ widgets are limited in size, because X - windows are so. - 2. There are a few extensions which are due to the different needs - for HTML rendering compared to GUI's. (Of course, this could - have been solved by defining a new object derived from - GtkWidget.) - - -Notes On Naming -=============== - -According to the naming standards, functions beginning with "a_Dw_" -may be used outside of Dw, while, as an extention, functions used -within Dw (e.g. p_Dw_widget_queue_resize) are prefixed with "p_Dw_". -[todo: This could be included in NC_design.txt.] - -Non-static functions beginning with "Dw_" are only used between -GtkDwViewport and DwWidget (e.g. Dw_gtk_viewport_remove_dw), they -belong to the core of Dw. And, of course, functions only used within a -sub-module (e.g. a specific widget) start with "Dw_" and are static -(e.g. Dw_page_find_line_index). - -Dw widgets and some other structures have the prefix "Dw", while Gtk+ -widgets in Dw have the prefix "GtkDw", but functions of them begin -with "Dw_gtk_" or "a_Dw_gtk", respectively. - - -Basic Overview -============== - -Dw widgets are objects derived from DwWidget, which itself derives -from GtkObject. DwWidget is quite similar to GtkWidget, the main -difference is that Dw widgets are always windowless and that they are -presented in a viewport, so there is no need to limit the size. Much -of the functionality normally provided by the X server is simulated -by Dw. - -The interface between Gtk+ and Dw is the Gtk+ widget GtkDwViewport, -which contains (at most) one top-level Dw widget. - -A Few Definitions: - - - world coordinates: coordinates relative to the upper left corner - of the whole scrolled area ("the world") - - viewport coordinates: coordinates relative to the upper left - corner of the visible area - - widget coordinates: coordinates relative to the upper left corner - of the widget - -Dw widgets draw into the viewport window, and must adhere to -*viewport coordinates*: the "world" is only an abstract term, there -is no window for it. When GtkDwViewport processes expose events, they -are automatically delivered to the Dw widgets. Redrawing requests due -to scrolling of the viewport is done by the base object GtkLayout, -you will not find any code for this in Dw. - -Mouse events also contain viewport coordinates. Dw will try to find -the right Dw widget to deliver the event to. - -Resizing the GtkDwViewport will not resize the top-level Dw widget, -but the latter will get some hints, so that, e.g., the page widget -rewraps the lines at the appropriate width. - -See DwWidget.txt for more details. - - -Embedding Gtk+ Widgets In Dw ----------------------------- -Dw Widgets may embed Gtk+ widgets, this is done by the Dw widget -DwEmbedGtk. For Gtk+, these embedded Gtk+ widgets are themselves -children of the GtkDwViewport, since Gtk+ does not care about Dw. - -Of course, embedded Gtk+ widgets are again limited in size, but but -in position: GtkDwViewport is derived from GtkLayout which is exactly -designed for positioning widgets in an infinite scrolled area. - - -How To Get The Top-Level Dw Widget From A BrowserWindow -------------------------------------------------------- -The member "docwin" of BrowserWindow points on a GtkDwScrolledWindow, -which contains a GtkDwScrolledFrame, which contains a GtkDwViewport. -The member "child" of the latter points on the top-level Dw widget, -or may be NULL. The top-level Dw is (currently) a DwPage (HTML and -plain text documents) or a DwImage (images). - -There is a function a_Dw_gtk_scrolled_window_get_dw for this. - - -Sizes ------ -A feature adapted from the old Dw are baselines. As well DwAllocation -as DwRequisition do not have a height member, but instead ascent and -descent, both positive or zero. (Originally I removed this, but there -will be a few widgets in future depending on this, e.g., math -formulas.) - -Unlike in Gtk, sizes of zero are allowed. The upper limit for the -size of a widget is 2^31 (this will be enough to show the contents of -a small library in a web page). - - -Resizing -======== - -From outside: When writing a new widget, you should implement the -signal "size_request". When the widget changes its size, it should -call p_Dw_widget_queue_resize, as in a_Dw_image_size. See "Incremental -Resizing" below for a way to increase the speed. - -Even if the implementation of "size_request" gets quite expensive, -you do not have to check whether the size has changed, this is done -by a_Dw_widget_size_request. - -Inside: q_Dw_widget_queue_resize will set the DW_NEEDS_RESIZE flag, a -further call of a_Dw_widget_size_request will only then emit the -"size_request" signal. Furthermore, mark_size_change and -mark_extremes_change are called (see below). After that, the resizing -is done in an idle loop, this prevents too many size requests. The -algorithm is quite simple: any widget with a child which needs -resizing, needs resizing, thus all parents up to top-level widget are -marked. - -Incremental Resizing ---------------------- -A widget may calculate its size based on size calculations already -done before. In this case, a widget must exactly know the reasons, why -a call of size_request is necessary. To make use of this, a widget -must implement the following: - - 1. There is a member in DwWidget, called parent_ref, which is - totally under control of the parent widget (and so sometimes not - used at all). It is necessary to define how parent_ref is used - by a specific parent widget, and it has to be set to the correct - value whenever necessary. - - 2. The widget must implement mark_size_change and - mark_extremes_change, these methods are called in two cases: - - a) directly after q_Dw_widget_queue_resize, with the argument - ref was passed to q_Dw_widget_queue_resize, and - b) if a child widget has called q_Dw_widget_queue_resize, - with the value of the parent_ref member of this child. - -This way, a widget can exactly keep track on size changes, and so -implement resizing in a faster way. A good example on how to use this -is the DwPage widget, see DwPage.txt for details. - - -Anchors and Scrolling -===================== - -Anchors -------- -todo: This section is out of sync with the actual code. - -To set the anchor a page is viewed at, you can use one of the -following functions: - - - void a_Dw_gtk_viewport_set_anchor (GtkDwViewport *viewport, - gchar *anchor) - - Scroll directly to an anchor. The anchor does not need to exist - already, see below. - - - void a_Dw_gtk_viewport_queue_anchor (GtkDwViewport *viewport, - gchar *anchor) +Dw is the internal widget library for rendering HTML. It has excellent +documentation. - Set the anchor for the next top-level DwWidget (the next call - of a_Dw_gtk_viewport_add_dw). - -There are wrappers, a_Dw_gtk_scrolled_window_queue_anchor and -a_Dw_gtk_scrolled_window_set_anchor. - -After a_Dw_gtk_viewport_set_anchor has been called (indirectly by -Nav_open_url, or by a_Dw_gtk_viewport_add_dw), changes of anchor -positions (e.g., if widgets change there size or the anchor was not -known before) will correct the viewport adjustment (in function -p_Dw_gtk_viewport_update_anchor), but only as long as the user did not -change it directly. Look at Dw_gtk_scrolled_window_init for details -about the latter. - -Use p_Dw_widget_set_anchor to add anchors to a widget, see -DwWidget.txt. - -Scrolling ---------- -Here is an overview on more functions for scrolling: - - - To scroll to a given position, there are two possibilities: - a_Dw_gtk_viewport_set_scrolling_position simply scrolls to this - position, while Dw_gtk_viewport_scroll_to has more facilities: - you specify a rectangle you want to see, and the way how it is - seen (at the border, centered, or just scroll as much as - necessary, that it is seen). If you have a widget, you can also - use Dw_widget_scroll_to. There is also a wrapper for - GtkDwScrolledWindow, - a_Dw_gtk_scrolled_window_set_scrolling_position, and two - functions for getting the position, - a_Dw_gtk_scrolled_window_get_scrolling_position_x, and - a_Dw_gtk_scrolled_window_get_scrolling_position_y. - - - If you have a region, and want to display it, use - a_Dw_iterator_scroll_to. For example, the findtext module makes - use of it. There are equivalents for DwExtIterator and - DwWordIterator. See comments on and in the function for more - informations. - - - If you just want to determine where some content is allocated, - represented by an iterator, you can use - a_Dw_iterator_get_allocation. There are equivalents for - DwExtIterator and DwWordIterator. - - -The Objects -=========== - -This is the hierarchy of all objects of Dw: - - (GtkObject) - +-DwWidget - | +----DwBullet - | +----DwContainer - | | `----DwPage - | +----DwEmbedGtk - | +----DwHruler - | `----DwImage - `----(GtkWidget) - `----(GtkContainer) - +----(GtkBin) - | +----(GtkScrolledWindow) - | | `----GtkDwScrolledWindow - | `----GtkDwScrolledFrame - `----(GtkLayout) - `----GtkDwViewport - -Objects in parentheses are part of Gtk+, not of Dw. - - -DwBullet --------- -Simple widget used for unnumbered list (<ul>). - - -DwContainer ------------ -The base object for Dw widgets which contain other Dw widgets. As in -Gtk+, containers are responsible for storing the children, there is -no common data structure. There are a few signals: - - - void add (DwContainer *container, - DwWidget *child); - - Currently not used, but may be in future. - - - void remove (DwContainer *container, - DwWidget *widget); - - *Recognize* that a widget is destroyed, i.e., an implementation - should remove *the pointer* from the list or so, but not - destroy the child widget. It is called by Dw_widget_shutdown. + Just run "doxygen" and browse the html/ directory! - - void forall (DwContainer *container, - DwCallback callback, - gpointer callback_data); - - Process callback for all children, in the form - (*callback)(child, callback_data). - - The include_internals of the Gtk+ equivalent was not adapted, - since it is used for more sophisticated purposes not needed in - Dw. - - -DwEmbedGtk ----------- -This Dw widget is used to embed Gtk+ widgets into Dw container -widgets. The Gtk+ widget is set by a_Dw_embed_gtk_add_gtk, and can -simply be removed by destroying it. - -If the DwEmbedGtk contains no Gtk+ widget, it always returns 0x0x0 as -size, so, for speed reasons, first add the Gtk+ widget into the -DwEmbedGtk, and then the DwEmbedGtk into the other Dw widget, as at -the end of Html_tag_open_input. - - -DwHruler --------- -Simple widget used for the <hr> tag. - - -DwImage -------- -Widget for displaying image. See DwImage.txt for details. - - -DwPage ------- -A widget for displaying texts. See DwPage.txt for details. - - -DwTable -------- -A container widget for rendering tables. See DwTable.txt for details. - - -DwWidget --------- -The base object for all Dw widgets. See DwWidget.txt for details. - - -GtkDwScrolledWindow -------------------- -Adds a few functionalities to GtkScrolledWindow: it creates the -GtkDwScrolledFrame and the GtkDwViewport, connects some signals, and -provides some wrappers for using the GtkDwViewport. - - -GtkDwScrolledFrame ------------------- -General purpose scrolled widget containing another scrolled widget, -adding a border and a focus frame. Furthermore, it processes key -presses and mouse drags (button 2, as in Gimp) to move the viewport. - -There are two signals (except "set_scroll_adjustments"), -"user_hchanged" and "user_vchanged", which are emitted when the user -changed the viewport adjustments horizontally/vertically by using the -keys or button 2 dragging. - - -GtkDwViewport -------------- -The interface between Gtk+ and Dw. It is responsible for displaying -Dw Widgets and processing their events. It is derived from GtkLayout, -to make embedding Gtk+ widgets into Dw widgets simpler, see the -documentation of GtkLayout in the Gtk+ tutorial for details. - -GtkDwViewport contains at most one top-level Dw Widget, if it exists. -The Gtk+ methods of GtkDwViewport are more or less mapped on the -methods of the DwWidget. In detail: - - - Dw_gtk_viewport_size_allocate will call a_Dw_widget_set_width, - a_Dw_widget_set_ascent (with allocation->height) and - a_Dw_widget_set_descent (with zero as argument), and then allocate - the Dw widget at the size returned by a_Dw_widget_size_request. - - - Dw_gtk_viewport_draw and Dw_gtk_viewport_expose will call - a_Dw_widget_draw, which will emit the "draw" signal. - - - Handling of mouse events is mostly done in Dw_widget_mouse_event, - see DwWidget.txt for details. Note that the functions return - FALSE, if the event was not processed, so that they are delivered - to the parent widget(s) of the GtkDwViewport, this scheme e.g. - prevents dragging of the viewport (done by GtkScrolledFrame) when - pressing mouse button 2 on a link. - -You may call gtk_container_set_border_width for a border around the -scrolled area.
--- a/doc/DwImage.txt Tue Oct 07 21:01:41 2008 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,201 +0,0 @@ -Jan 2001, S.Geerken@ping.de -Last update: Dec 2004 - -======= -DwImage -======= - -A widget for displaying images and handling image maps. - - -Image Maps -========== - -Client Side Image Maps ----------------------- -You must first create a list of image maps: Allocate a DwImageMapList, -and initialize it by calling a_Dw_image_map_list_init. Adding a map is -done by a_Dw_image_map_list_add_map. a_Dw_image_map_list_add_shape -adds a shape to the last map. For the meaning of the link argument, -see Section "Signals". - -Image maps are referred by a URL (not only by a name). But currently, -the image map list is stored in DilloHtmlLB and there is no -possibility to parse documents without rendering, so images can only -use maps defined in the same document. - -To use a map in an image, call a_Dw_image_set_usemap with the image, -the map list, and the URL of the map. Passing the whole list makes it -possible to use maps parsed after the image is created. - - -Server Side Image Maps ----------------------- -To use images for server side image maps, you must call -a_Dw_image_set_ismap and the style must contain a valid link -element. See section "Signals" for more details. - - -Signals -======= - -There are five signals, which can be connected to process actions with -links. All have at least three arguments: - - - link is the link element of the DwStyle (server side image maps) - or DwImageMapShape (client side image maps). The value is an - integer, which is currently only used for hypertext links. But - generally, it depends on the signal callback how this value is - used. - - - x and y are, when server side image maps are used, the relative - coordinates of the mouse pointer, otherwise always -1. - -Note that, unlike by DwPage before, no cursors are set. Instead, the -signal callback function has to do this. - -The signals: - - - void link_entered (DwImage *image, - gint link, gint x, gint y) - - Emitted when the link the mouse pointer is over has - changed. "Changed" includes link, x and y, so this signal is also - emitted each time the pointer is moved within a server side image - map. If the pointer is outside of a link, all arguments have the - value -1. - - - - void link_pressed (DwImage *image, - gint link, gint x, gint y, - GdkEventButton *event) - - Emitted when the user presses a mouse button _inside_ a link, - this signal is never emitted with link = -1. You can use the - event to get information about the button, shift keys, etc. - - - - void link_released (DwImage *image, - gint link, gint x, gint y, - GdkEventButton *event) - - - void link_clicked (DwImage *image, - gint link, gint x, gint y, - GdkEventButton *event) - - Analogue to link_pressed. - - - void void (*image_pressed) (DwImage *page, - GdkEventButton *event) - - Emitted when the user presses the mouse button on an image which - has no related map. In some cases, it may be neccessary to - suppress event processing by a_Dw_widget_set_button_sensitive(). - - -Future Extentions -================= - -(See also Imgbuf.txt, what is named DilloImageBuffer here, has been -implemented under the name Imgbuf.) - -These are some ideas for a different design, which will solve several -problems (image transparency, memory usage when implementing a global -size factor): - -1. Instead of a guchar array, a new data type, DilloImageBuffer, - should be used (DICacheEntry::ImageBuffer and DwImage::buffer). Any - access is done by function calls. Copying the lines (in - a_Image_write) is done by a_Image_buffer_copy_line, etc. The call to - Image_line becomes obsolete, since DilloImageBuffer will deal with - different types: indexed, RGB, gray, RGBA, gray-alpha(?). This may - be useful for a more efficient implementation of DilloImageBuffer. - -2. The modules Png, Jpeg, Gif, Image and DICache deal with the - original image size (read by the decoders), while DwImage gets the - "viewed" size (original size, multiplied by the global image - scaling factor) from DilloImageBuffer. - -3. For DwImage, there are further methods which replace the current - direct access. Note to worth: - - - Scaled buffers are shared, reference counters are used. Copying - rows will automatically also affect the related scaled buffers. - - - There are two methods for drawing, one called after expose events - (Dw_image_draw) and another called by a_Dw_image_draw_row. The - exact rules, how the buffer is scaled (this can, e.g., differ by a - pixel or so), is hidden by DilloImageBuffer. - - - As noted above, all DwImage code is based on the viewed size. - -4. The global image scaling factor is used in two places. The HTML - parser must apply it on the WIDTH and HEIGHT attributes of the - <IMG> tag and DilloImageBuffer must use it to scale the inherent - size of an image. There are two modes, which the user can switch - by a dillorc option: - - (i) The original image data is preserved, and an additional scaled - buffer is created: - - +-------+ +------------------+ additional - | Image | -- copy --> | DilloImageBuffer | --> scaled - +-------+ rows | (original size) | buffers - +------------------+ - | ^ - | | - scale requests - each row for scaled - | buffers - | | - v | - +------------------+ - | DilloImageBuffer | - | (viewed size) | - +------------------+ - ^ - | - +---------+ - | DwImage | - +---------+ - - (ii) The original data gets lost just after scaling: - - +-------+ +------------------+ - | Image | -- copy --> | DilloImageBuffer | --> scaled - +-------+ rows | (viewed size) | buffers - +------------------+ - ^ - | - +---------+ - | DwImage | - +---------+ - - (ii) uses generally less memory, while in some cases leads to a - lower rendering quality, as in this example: - - "foo.png" has a size of 100x100 pixels, the image scaling factor is - 50%, and the following HTML sniplet is rendered: - - <img src="foo.png"> - <img src="foo.png" width=200 height=200> - - The first image is displayed at a size of 50x50, the second at - 100x100. (i) will, for the second, use the original buffer, but - (ii) will enlarge the buffer, which was scaled down before, so - resulting in a "pixelized" image. - -5. Any implementation of DilloImageBuffer will handle transparency - independent of the background, i.e., the background colour will not - be used anymore. The first implementation may be based on GdkRGB - and (when needed) dithered clipping bitmaps. Better implementations - may then be developed in the future. - -6. Background images: The modules Image and DICache do no longer - access the DwImage directly, all calls are replaced by an - Interface, which is then implemented by DwImage and an appropriate - structure for background images (part of DwStyle). The interface is - in C realized by a struct of function pointers, and a generic - pointer on DwImage, etc. - -7. If someone really needs it, animated GIF's may be considered.
--- a/doc/DwPage.txt Tue Oct 07 21:01:41 2008 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,152 +0,0 @@ -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. -
--- a/doc/DwRender.txt Tue Oct 07 21:01:41 2008 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,620 +0,0 @@ -Aug 2004, S.Geerken@ping.de - -=========================== - Dw Render Abstraction -=========================== - -This document describes the rendering abstraction used in Dw. At the -time this document was written, some other documents about Dw were out -of date, and have to be rewritten. - -Sometimes, you will find remarks about the old design (with one -concrete Gtk+ widget instead of the layout/multiple rendering views); -those are useful for those, who are already familiar with the old -design. Furthermore, it makes the explanation often simpler, because -the new design is a bit more complex. - -Naming ------- -As stated in "Dw.txt", the prefix "p_Dw_" is used for functions used -within the whole Dw module, but not outside. Typically, these are -protected functions, which are called by inherited classes. E.g., a -specific widget will have to call p_Dw_widget_queue_resize(), but this -function should not called outside from Dw. - -The "Dw_" prefix is not only used for functions, which use is -restricted to a sub-module, but also for functions used only within -the core of Dw. The distinction between both can simply made, whether -the function is declared as static or not. The core of Dw consists of -the modules Dw_widget and Dw_render, anything else is inherited from -these two modules (widgets, platforms, views). As an example, -Dw_gtk_viewport_queue_resize() is only called in the Dw_widget module, -it should not be called by a widget implementation. - - -Overview -======== - -Rendering of Dw is done in a way resembling the model-view pattern, at -least formally. Actually, the counterpart of the model, the layout -(DwRenderLayout), does a bit more than a typical model, namely -calculating the layout, and the views do a bit less than a typical -view, i.e. only the actual drawing. - -Additionally, there is a structure representing common properties of -the platform, views generally work only together with one specific -platform. A platform is typically related to the underlying UI -toolkit, but other uses may be thought of. - -The general structure looks like this: - - 1 +------------------+ - .---->| DwRenderPlatform | - +----------------+ 1 / +------------------+ - | DwRenderLayout |--< ^ 1 - +----------------+ \ | * - 1 ^ | 1 \ +--------------+ - | | `---->| DwRenderView | - | | * +--------------+ - | | - layout | | toplevel_dw - | | - * | V 0..1 - +----------+ 0..1 - | DwWidget |--. parent - +----------+ | - * | | - `-------' - (children) - -(This is a bit simplified, actually, only DwContainer has child -widgets, and the relation is only defined in an abstract way). - -DwRenderLayout and DwWidget (including sub classes) are platform and -view independant, i.e., it should be possible to adopt them into -another platform, after suitable implementations of DwRenderPlatform -and DwRenderView have been developed. - -(The only exception is DwEmbedGtk, a widget which, in the old design, -embeds Gtk+ widgets into the DwWidget tree. This will still remain a -platform specific widget, see notes in the section "UI Widgets". - -Furthermore, this design does not yet cover DwStyle, which is still -bound to the Gtk+ platform. It may be simply replaced for other -platforms, but this will lose the possibility to have multiple -implementations of DwRenderPlatform running within the same program. -The same aplies to DwTooltip and Imgbuf.) - -This new design helps to archieve two important goals: - - 1. Abstraction of the actual rendering. Currently, we only have the - normal viewport, but a list of planned implementations can be - found below in this text. - - 2. It makes different views of the same document simple, e.g. the - normal viewport and the preview window. - - 3. It makes portability simpler. - -Vieports are handles by this design, but only in a rather abstract -way, and may be removed completely, i.e., they will be only part of -specific view implementations. This also means, that the distinction -between world coordinates and viewport coordinates vanishes from most -parts of Dw. - - -World -===== - -The world is the whole area, in which content is rendered. For a view -without a viewport, this is the whole itself. A view with a viewport -provides a way, so that the user may see some part of the world within -a (in most cases) smaller window, the viewport. - -The world may have a base line, so that the worls size is described by -three numbers, width, ascent and descent. - -Any view must implement the method set_world_size(), which is called, -whenever the world size changes. For viewports, this will change -scroll bars etc., for views without viewport, this will normally -change the size of the view itself. (Although on this level, "view -size" is not defined. This should not be confused with the viewport -size!) - - -Drawing -======= - -A view must implement several drawing methods, which work on the whole -world. If it is neccesary to convert them (e.g. in DwGtkViewport), -this is done in a way fully transparent to DwWidget and -DwRenderingLayout, instead, this is done by the view implementation. - -There exist following situations: - - - A view gets an expose event: It will delegate this to the - rendering layout, which will then pass it to the widgets, with - the view as a parameter. Eventually, the widgets will call - drawing methods of the view. - - - A widget requests a redraw: In this case, the widget will - delegate this to the layout. The drawing requests are queued, and - compressed. in an this idle function, DwWidget::draw is called - for the toplevel widget, for each view. - - (This is still something to consider, the queueing may be moved - again into the view implementations.) - -If the draw method of a widget is implemented in a way that it may -draw outside of the widget's allocation, it should draw into a -clipping view. A clipping view is a rendering view related to the -actual rendering view, which guarantees that the parts drawn outside -are discarded. At the end, the clipping view is merged into the actual -view. Sample code for widget DwFoo: - - void Dw_foo_draw (DwWidget *widget, - DwRenderView *view, - DwRectangle *area) - { - DwRenderView *clip_view; - - /* 1. Create a clipping view. */ - clip_view = - p_Dw_render_view_get_clipping_view (view, - widget->allocation.x, - widget->allocation.y, - widget->allocation.width - DW_WIDGET_HEIGHT (widget)); - - /* 2. Draw into clip_view. */ - Dw_render_view_do_some_drawing (clip_view, ...); - - /* 3. Draw the children, they receive the clipping view as argument. */ - for (<all relevant children>) { - if (p_Dw_widget_intersect (button->child, area, &child_area)) - p_Dw_widget_draw (child, clip_view, child_area); - } - - p_Dw_render_view_merge_clipping_view (view, clip_view); - } - -A drawing process is always embedded into calls of -DwRenderView::start_drawing() and DwRenderView::finish_drawing(). An -implementation of this are backing pixmaps, to prevent flickering. - - -Viewports and Scrolling Positions -================================= - -Although the design implies that the usage of viewports should be -fully transparent to the Dw_render module, this cannot be fully -archived, for the following reasons: - - 1. Some features, which are used on the level of DwWidget, - e.g. anchors, refer to scrolling positions. - - 2. Some code in DwWidget is currently tightly bound to viewports. - This may be change, by delegating some of this functionality to - viewports, and defining scrolling positions in a more abstract - way. - -Therefor, DwRenderLayout keeps track of the viewport size, the -viewport position, and even the thickness of the scrollbars (or, -generally, "viewport marker"), they are relevant, see below. These -sizes are always equal in all views. However, a given view may not use -viewports at all, and there may be the case, that no view related to a -layout uses viewports, in this case, the viewport size is not defined -at all. - -Unlike world sized, viewports are not considered to have a base line, -i.e., they are described by only two numbers, width and height. - -Viewport Size -------------- -All viewport sizes and positions are the same in all views, which uses -viewports. There are two cases, in which the viewport size changes: - - 1. As an reaction on a user event, e.g. when the user changes the - window size. In this case, the affected view delegates this - change to the layout, by calling - p_Dw_render_layout_vieport_size_changed(). All other views are - told about this, by calling DwRenderView::set_viewport_size(). - - 2. The viewport size may also depend on the visibility of UI - widgets, which depend on the world size, e.g scrollbars, - generally called "viewport markers". This is described in an own - section. - -After the creation of the layout, the viewport size is undefined. When -a view is attached to a layout, and this view is already to be able to -define its viewport size, it may already call -p_Dw_render_layout_vieport_size_changed() within the implementation of -set_layout. If not, it may do this, as soon as the viewport size gets -known. - -Each call of p_Dw_render_layout_vieport_size_changed() will change the -viewport size of all other views, which use viewports, so this -function has to be called with care. - -If there is no view attached, which used viewports, the viewport size -remains undefined. - -Viewport Markers ----------------- -Viewport markers are UI widgets, which display to the user the -relation of the world size and the widget size. Most commonly, -scrollbars will be used. - -When they are not needed, they are hidden, as in the following figure: - - - +--------------------+ - | This is only a | - | very short text. | - | | - | | - | | - +--------------------+ - -but shown, as soon as the world size exceeds the viewport size: - - +------------------+-+ - | In this example, |^| - | there is some |#| - | more text, so |#| - | that the | | - | vertical |v| - +------------------+-+ - -A view using viewports must provide, how large the differences -are. Generally, there are four cases, from the combinations of whether -the world width is smaller (-) or greater (+) than the viewport width, -and whether the world height is smaller (-) or greater (+) than the -viewport height. So there are eight numbers, the horizontal difference -dh, and the vertical difference dv, for the cases --, -+, +-, and ++. - -For scrollbars, the values are rather simple: - - - dh is 0 for the cases -- and -+, and the thickness of the - vertical scrollbar in the cases +- and ++. - - - dv is 0 for the cases -- and +-, and the thickness of the - horizontal scrollbar in the cases -+ and ++. - -For any view implementation, the following rules must be fullfeeded -(dx means either dh or dv): - - - dx(-+) >= d(--) - - dx(++) >= d(+-) - - dx(+-) >= d(--) - - dx(++) >= d(-+) - -In short, when smaller world dimensions (-) grow (switch to +), the -differences may not become less. - -The sizes of viewport markers are part of the viewport size, the -method DwRenderView::set_viewport_size() has four parameters: - - - two for the size of the viewport, *including* the markers - (i.e. the markers never change the size), and - - - two, which denote the differences between the above and the - actual viewport size, caused by the markers. If a value of these - is 0, the respective marker is hidden, if it is greater than 0, - it is shown. In the latter case, the maximun is calculated, and - passed to all views. - -(Actually, the decision, whether the markers are visible or not, is a -bit more complicated, since the vieport size also defines the size -hints for the topmost widget, which may affect the widget size, and so -the world size. Handling this problem is done within DwRenderLayout, -look at the comments there.) - -Scrolling Positions -------------------- -The scrolling position is the world position at the upper left corner -of the viewport. Views using viewports must - - 1. change this value on request, and - 2. tell other changes to the layout, e.g. caused by user events. - -Applications of scrolling positions (anchors, test search etc.) are -handled by the layout, in a way fully transparent to the views. - - -An Example with Nested Views -============================ -The following example refers to graphical plugins, which are not yet -realized (I have some working proof-of-concept code), but which will -most likely follow the design, which is here shortly described, as -needed to understand the example (since there is no specification of -graphical plugins yet). I included this, to demonstrate, how nested -layouts can be used. - -Graphical plugins will communicate with dillo via two protocols, dpi1 -(for anything not directly related to rendering), and a new protocol, -which is an extension of the XEmbed protocol (see somewhere at -http://freedesktop.org, this is the protocol, which GtkPlug and -GtkSocket use). Within dillo, a socket window will be created, which -window id will be (via dpi1?) passed to the plugin. The plugin will -then create a plugin window, in which the contents of a web recource -is shown, which dillo cannot show natively. - -XEmbed will be extended, so that the plugins may make use of the -extensions, which the Dw size model adds to the XEmbed size -model. Such a plugin behaves (on an abstract level) like a DwWidget, -so following extensions are necessary: - - - a plugin may not simply have a size, but instead distinguish - between ascent and descent, - - a plugin may return width extremes, and - - it is possible to send size hints to the plugin. - -Within Dw, the socket will be realized by a special plugin, -DwSocketGtk (or a respective widget for other platforms), which is a -sub class of DwEmbedGtk, and embeds another UI widget, which will -provide the socket window (for Gtk+, either GtkSocket, or a sub class -of this). - -The plugins may be implemented independently of Dw, they either do not -support the extensions to XEmbed (then, the respective features behave -in a default way), or they may contain there own implementation. -However, Dw may be extracted from dillo, to become an own library. A -plugin using this library may then use a special type of view, -GtkDwFlatView (for plugins based on Gtk+, actually, the UI toolkit for -dillo and the plugin must not be the same, since the protocol will be -UI toolkit independant.) - -This will lead to a structure like this: - - top_layout:DwRenderLayout ----- top_page:DwPage - / \ | - :GtkDwPlatform top_view:GtkDwView `- table:DwTable - | - `- cell:DwTableCell - | - `- socket:DwSocketGtk - | - DILLO gtk_socket:GtkSocket - . -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - . (extension of - . XEmbed) - PLUGIN - plugin_layout:DwRenderLayout ----- dw_flat_view:GtkDwFlatView - \ - `------- foo:DwFoo - -GtkDwFlatView is both an extension of GtkSocket, as well as an -implementation of DwRenderView. - -This case must be equivalent to the case, that the widget "foo" is a -direct child of the widget "cell", since all objects between them only -delegate all functionality. Size hints must so sent as in the -following scenario: - - 1. The view "top_view" receieves an event, which will change the - viewport size, and delegates this to the layout. - - 2. The layout will make size hints of this viewport size, i.e., it - calls the set_* methods of the widget "top_page". - - 3. DwPage::set_* will queue a resize request, which is delegated - to the layout. - - 4. Handling the resize request is done within a idle loop. Here, - size_request is called for the widget "top_page", to determine - the preferred size. - - 5. DwPage::size_request will depend on the size hints, especially, - it will use the hinted size to determine the word wrap width. - Within DwPage::size_request, size hints will be sent to the - child widgets. The size hints sent to the children are those - sent to the page, minus the respective border widths (margins, - borders, paddings). (How the ascent and descent hints should - generally be delegated to the children, is still a matter of - consideration, and may change.) - - 6. DwTable::size_request, which is called within this context, has - a different way to delegate the size hints to the children: - ascent and descent are handled the same way, but the widths are - calculated from the column widths, which are calculated within - DwTable::size_request. - - 7. Via the widget "cell", finally the widget "socket" receives - appropriate size hints. These must be (equally) delegated to - the widget "foo", this is done in a way described in the - following steps. - - 8. The size hints are transmitted via the protocol extending - XEmbed. The Gtk+ widget "dw_flat_view" receives them (via the - widget "gtk_socket"), and delegates them to the respective - layout "plugin_layout". (TODO: How is this done? What has to be - done is to send the size hints to the toplevel widget, but a - view has no access to it.) - - 9. The layout "plugin_layout" will then delegate this (what ever - "this" means), as size hints, to the widget "foo". - - 10. The widget "foo" will queue a size_request, which is delegated - to the layout. In the idle function handling this request, the - recalculation of the widget size will change the world size, - which is delegated to the view "dw_flat_view". - - 11. For GtkDwFlatView, the world size is the view size. For this - reason, it changes its size, to fit the world size. This size - is send to the DwSocket, which will then request a size - request. - - -UI Widgets -========== -A note before: This chapter refers often to Gtk+ as base UI toolkit, -just to make naming simpler, For other UI toolkits, the same, mostly -only with other names, applies. - -In some cases, it is necessary to embed widgets from the UI toolkit -into the view, e.g. to realize HTML forms in dillo. - -The Dw_render module provides no interface at all, instead, this is -completely left to the platform implementations. Below, two design -approaches are discussed, which have following in common: - - 1. There is a special Dw widget, which embeds something related to - the UI widgets (below called DwEmbedGtk). - - 2. This Dw widget, the platform, and the views are tightly bound, - beyond the methods, which the respective interfaces provide. The - Dw widget can simply refer to the platform by - (DwWidget::render_layout->platform, and the platform may refer - to the views, when DwPlatform::attach_view and - DwPlatform::detach_view are implemented. - -General Problems ----------------- -For most UI toolkits, there have to be multiple instances of widgets -in different views. Furthermore, there may be, on the same platform, -different classes for the same widgets. Consider this simple example: - - :DwRenderLayout ------------------- :DwPage - / \ | - ,----' `----. dw:DwEmbedGtk - / \ - view1:GtkDwViewport view2:GtkDwViewport - | | - gtk1:GtkButton gtk2:GtkButton - -This structure represents a page with one button in it, which is, in -the DwWidget tree, represented by the DwEmbedGtk "dw", and, in the -views "view1" and "view2", by the Gtk+ widgets "gtk1" and "gtk2", -respectively. The old approach, where the UI widget (in this case -GtkButton) is not directly applicable, since there must be multiple -instances of this UI widget. - -Here is a more complex example: - - :DwRenderLayout ------------------- :DwPage - / \ | - ,----' `----. dw:DwEmbedGtk - / \ - view1:GtkDwFooView view2:GtkDwBarView - | | - gtk1:GtkFooButton gtk2:GtkBarButton - -In this case, the different views GtkDwFooView and GtkDwBarView deal -with different classes for buttons, GtkFooButton and GtkBarButton. - -Simple Approach ---------------- -Within dillo, the following limitations are reasonable: - - 1. There is only one view instance, which actually needs UI widgets - (GtkDwViewport for Gtk+). There may be multiple views, but these - additional views do not need instances of widgets, e.g. in the - preview, a UI widget is simply shown as a grey box. - - 2. There is only one type of UI widget, i.e. normal Gtk+ widgets. - -Because of these limitations, the implementation of UI widgets is -currently quite simple in dillo. As before, the widget DwEmbedGtk -refers to an instance of a concrete Gtk+ widget. This Gtk+ widget is -told to the platform, of which DwEmbedGtk knows, that it is an -instance of GtkDwPlatform. GtkDwPlatform will add this Gtk+ widget to -the single view, which needs it, and DwEmbedGtk will be responsible of -allocating etc. of the Gtk+ widget. - -Advanced Approach ------------------ -This is a short overview of an approach, which will overcome the -limitations of the simple approach, but with the costs of a greater -complexity. It will be detailed, in the case, that it is implemented. - - +------------+ factory +---------------------+ - | DwEmbedGtk | ---------> | DwGtkWidgetFactory | - +------------+ 1 1 +---------------------+ - | create_foo_widget() | - | create_bar_widget() | - +---------------------+ - . . . - /_\ /_\ /_\ - | | | - - - - - - - - - - - - - - - - - - . - | | - +---------------------+ +---------------------+ | - | DwGtkButtonFactory | | DwGtkListFactoty | (other ...) - +---------------------+ +---------------------+ - | create_foo_widget() | | create_foo_widget() | - | create_bar_widget() | | create_bar_widget() | - +---------------------+ | add_list_item(...) | - +---------------------+ - -DwEmbedGtk refers to a factory, which creates the UI widgets for each -view. For each general widget type (e.g. button, list, ...), there is -an implementation of this interface. - -This interface DwGtkWidgetFactory contains different method for -different views. E.g., when a button is shown, and so DwEmbedGtk -refers to a DwGtkButtonFactoty, GtkDwFooView may need a GtkFooButton, -which is created by create_foo_widget(), while GtkDwBarView may call -create_bar_widget(), to get a GtkBarButton. (This design still makes -it hard to add new views, which then need, say, GtkBazButtons.) - -The concrete factories may contain additional methods, in the diagram -above, DwGtkListFactory must provide a function to add items to the -lists. This method will add a item to all list widget, which were -created by this factory. - - -More Ideas for View Implementations -=================================== - -Preview Window --------------- -The status bar gets a new button, on which the user may click to get a -small image of the small page, in which he can select the viewport -position by dragging a rubber-band rectangle. The actual scaling -factor will probably depend on the aspect ratio of the page. - -(This has already been implemented for Gtk+, as GtkDwPreview and -GtkDwPreviewButton.) - -Graphical Plugin ----------------- -See section "An Example with Nested Views" for explanations. - -====================================================================== - -Alternative design for handling UI widgets: - -- There is a platform *independant* widget, the platform dependencies - are within the factories. - - DwEmbedUI::draw - -> DwRenderView::draw_ui_widget(..., factory) - -Implementation of "draw_ui_widget" in a preview view: - -> draw some gray boxes etc. - -Implementation of "draw_ui_widget" in a normal "bar" view (for platform "foo"): - -> determine that is is a factory for a "baz" widget? - -> (BarFactory*)factory->get_foo_bar_widget(this) - -This method either returns an already created widget, or creates one -with the current state of the factory. "This" is taken as a key. - ----- - - | general | widget specific -----------------------+------------------+------------------------ - platform independant | nothing? | e.g. adding list items -----------------------+------------------+------------------------ - platform dependant | e.g. creating a | ??? - | widget, or | - | informations | - | about drawing in | - | a preview | - -====================================================================== - -Abstraction of DwStyle ----------------------- -structures needed:
--- a/doc/DwStyle.txt Tue Oct 07 21:01:41 2008 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,310 +0,0 @@ -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.
--- a/doc/DwTable.txt Tue Oct 07 21:01:41 2008 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,205 +0,0 @@ -May 2001, S.Geerken@ping.de -Last update: Dec 2004 - -======= -DwTable -======= - -A container widget for rendering tables. - - -The DwTable Widget -================== - -DwTable is a container widget for rendering tables. It aligns other -DwWidgets (normally DwPage), according to the following rules: - - 1. All columns have have the same width W, except: - - - W is less than the minimal column width, or - - W is greater than the maximal column width. - - Furthermore, W is - - - less than all minimal widths of columns not having W as - width, and - - greater than all maximal widths of columns not having W as - width. - - 2. The table tries to use exactly the whole available width, except - if it is not possible, because the it is less/greater than the - minimal/maximal table width. - -This is simple to implement for columns with COLSPAN == 1, using -a_Dw_get_extremes for getting the minimal and maximal widths. For -arbitrary COLSPAN values, an approach described in "Subtables" is -used to get optimal results (as described above) in most cases, while -the rendering remains fast. - - -Subtables -========= - -A table is divided into subtables, which do not (in most cases) share -spanning cells, until single columns are left. Cells spanning the -whole width are removed before dividing further. Example: - - +---+-------+---+ - | A | B | C | - +---+-------+---+ - | D | E | - +---+-------+---+ - | F | G | H | - +---+-------+---+ - ' ' ` ` - ' ' ` ` - +---+-------+ +---+ - | A | B | | C | - +---+-------+ +---+ - removed --> | D | | E | - +---+-------+ +---+ - | F | G | | H | - +---+-------+ +---+ - ' ' ` ` final - ' ' ` ` - +---+ +-------+ - | A | | B | <-. - +---+ +-------+ >- removed - | F | | G | <-' - +---+ +-------+ - final ' ' ` ` - ' ' ` ` - [empty] [empty] - final final - -There is a structure, DwTableSub, for holding all the information. It -is rebuilt when new cells are added. Do not confuse this with nested -tables, these are represented by the Dw widget hierarchy. - -If table cells overlap horizontally, they are (virtually) divided. The -minimal and maximal widths are apportioned to the other columns -(resulting in a non optimal layout): - - +-------+---+---+ - | A | B | C | - +---+---+---+---+ - | D | E | - +---+-----------+ - ' ' ` ` - ' ' ` ` - +-------+ +---+---+ - | A | | B | C | - +---+---+ +---+---+ - | D |1/3| | 2/3 E | - | | E | | | - +---+---+ +-------+ - -Example for a non-optimal case ------------------------------- -The HTML document fragment - - <table> - <tr> - <td colspan="2">Text - <td>LongText - <tr> - <td>Text - <td colspan="2">LongText - </table> - -will result in: - - | 0 | 1 | 2 | - - +------------+----------+ - | Text | LongText | - +------+-----+----------+ - | Text | LongText | - +------+----------------+ - -The width of column 1 is determined by the half of the minimal width -of the LongText. An optimal rendering would be something like: - - ,- 1 - | 0 || 2 | - - +-------+----------+ - | Text | LongText | - +------++----------+ - | Text | LongText | - +------+-----------+ - - -Algorithms -========== - -Calculating extremes --------------------- -The extremes of all subtables are calculated by -Dw_table_sub_get_extremes and stored in DwTableSub: - - minimal/maximal width (sub table) = - - for single column: maximum of all minimal/maximal widths - - otherwise: maximum of - 1. all minimal/maximal widths of cells spanning - the whole width, and - 2. the sum of the minimal/maximal widths of the - sub-subtables - - In step 1, the width argument is used to adjust the maximum - and minimum width of the whole subtable and mark it as fixed. - -todo: describe percentages. - -Calculating column widths -------------------------- -The calculation is based on a fixed width, which is, at the top, the -width set by a_Dw_widget_set_width. This is corrected by the minimal and -maximal width of the whole table, and, if given, the width attribute -of the table. At each level, the available width is always between the -minimal and the maximal width of the subtable. - -For single columns, the width is the passed fixed width. Otherwise: - - 1. Calculate relative widths, they effect the minimal and maximal - widths. (Temporally, not permanently!) - - 2. The sum of these corrected minima may be greater as the fixed - width of the subtable. In this case, decrease them again to - match exactly the fixed width, then use them as sub-subtable - fixed widths and finish. Otherwise, continue: - - 3. If the extremes of the spanning widths of the subtable are - greater than the sum of sub-subtables extremes, adjust the - extremes of sub-subtables which are not fixed, i.e., where no - width argument (either percentage or fixed) freezes the width. - - 4. Use an iteration on the subtables, to determine the column - widths, see Dw_table_sub_calc_col_widths for details. - - 5. After this, apply this recursively on all subtables and pass the - subtable width as fixed width. - - -Borders, Paddings, Spacing -========================== - -Currently, DwTable supports only the separated borders model (see CSS -specification). Borders, paddings, spacing is done by creating DwStyle -structures with values equivalent to following CSS: - - TABLE { - border: outset <table-border>; - border-collapse: separate; - border-spacing: <table-cellspacing> - background-color: <table-bgcolor> - } - - TD TH { - border: inset <table-border>; - padding: <table-cellspacing> - background-color: <td/th-bgcolor> - } - -Here, <foo-bar> refers to the attribute bar of the tag foo. See -Html_open_table and Html_open_table_cell for more details.
--- a/doc/DwWidget.txt Tue Oct 07 21:01:41 2008 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,339 +0,0 @@ -Jan 2001, S.Geerken@ping.de -Last update: Dec 2004 - -======== -DwWidget -======== - -The base object for all Dw widgets. - - -Structures -========== - -DwRectangle ------------ -A replacement for GdkRectangle, the only difference is the use of 32 -instead of 16 bit integers. - - -DwAllocation, DwRequisition ---------------------------- -Similar to GtkAllocation and GtkRequisition. Instead of a height, you -have two members, ascent and descent. - - -DwExtremes ----------- -A structure containing the minimal and maximal width of a widget. See -get_extremes below for details. - - -DwWidget --------- -Some members you may use: - - parent The parent widget. NULL for toplevel widgets. - - flags See below. - - style The style attached to the widget, this must - always be defined, but is not created - automatically. Instead, this has to be done - immediately after creating the widget - (e.g., in a_Web_dispatch_by_type). This style - contains attributes and resources for general - drawing. See DwStyle.txt for details. - -These members should only be used within the "core" (GtkDw*, DwWidget -and DwEmbedGtk): - - viewport The viewport containing the widget. Defined - for all widgets. - - allocation, - requisition, - extremes, - user_requisition These are used to optimize several wrappers, - see below. - - anchors_table See notes on achors. - -Flags ------ -Flags can be set and unset with DW_WIDGET_SET_FLAGS and -DW_WIDGET_UNSET_FLAGS. For reading flags use the macros DW_WIDGET_... - - DW_NEEDS_RESIZE - DW_EXTREMES_CHANGED Denotes that the widget must be resized. Used - only internally. See Dw.txt and the source - for more details. - - DW_NEEDS_ALLOCATE Set to overide the optimation in - a_Dw_widget_size_allocate. Used only - internally. - - DW_REALIZED Set when the widget is realized. Should be - used to prevent crashes in certain - situations. - -Following flags describe characteristics of widgets and are typically -set in the init function: - - DW_USES_HINTS A widget with this flag set has a complex way - to deal with sizes, and should - - - implement the functions set_width, - set_ascent, set_descent, and - get_extremes, and - - deal completely with width and height - in widget->style. - - Examples are DwPage and DwTable. Other - widgets, like DwImage and DwHRuler, are much - simpler and don't have to set this flag. For - these widgets, much of the size calculation - is done by the parent widget. - - This flag is unset by default. - - DW_HAS_CONTENT If this flag is set, more space is reserved - for the widget in some circumstances. E.g., - if an image has a width of 100%, it makes - sense to use more space within a table cell, - as compared to a horizontal ruler, which does - not "have a content". - - This flag is set by default. - - -Signal Prototypes -================= - - - void size_request (DwWidget *widget, - DwRequisition *requisition); - - Similar to Gtk. - - void get_extremes (DwWidget *widget, - DwExtremes *extremes); - - Return the maximal and minimal width of the widget, equivalent - to the requisition width after calling set_width with zero and - infinitive, respectively. This is important for fast table - rendering. Simple widgets do not have to implement this; the - default is the requisition width for both values. - - - void size_allocate (DwWidget *widget, - DwAllocation *allocation); - - Similar in Gtk. Note: allocation has world coordinates. - - - void set_width (DwWidget *widget, - guint32 width); - - - void set_height (DwWidget *widget, - guint32 height); - - These are hints by the caller, which *may* influence the size - returned by size_request. The implementation should call - Dw_widget_queue_resize if necessary. In most cases, these - signals do not have to be implemented. Currently, only the - DwPage widget uses this to determine the width for rewrapping - text (note that the resulting width returned by - Dw_page_size_request may be _bigger_) and relative sizes of the - children. - - - void draw (DwWidget *widget, - DwRectangle *area, - GdkEventExpose *event); - - Draw the widget's content in the specified area. It may either - be caused by an expose event, or by an internal drawing request - (e.g., followed by resizing of widgets). In the first case, you - get the *original* expose event as third argument. In the - latter, event is NULL. The area argument has widget - coordinates. A DwContainer is responsible for drawing its - children. - - (Since DwWidget's are always windowless, there was no need for - two signals, "draw" and "expose_event".) - - - void realize (DwWidget *widget); - - Create all necessary X resources. Called when either the - viewport (top-level widgets) or, respectively, the parent Dw - widget is realized, or an widget is added to an already - realized Dw widget/viewport. - - - void unrealize (DwWidget *widget); - - Remove created X resources. - - - gint button_press_event (DwWidget *widget, - guint32 x, - guint32 y, - GdkEventButton *event); - - This signal is emitted when the user presses a mouse button in - a DwWidget. x and y are the coordinates relative to the origin - of the widget, event is the *original* event, which may, e.g., - be used to determine the number of the pressed button, the state - of the shift keys, etc. The implementation of this signal - should return TRUE, if the event has been processed, otherwise - FALSE. - - A DwContainer is *not* responsible for delivering button press - events to its children. Instead, Dw first emits the - button_press_event signal for the most inner widgets and - continues this for the parents, until TRUE is returned. - - - gint button_release_event (DwWidget *widget, - guint32 x, - guint32 y, - GdkEventButton *event); - - Compare button_press_event. - - - gint motion_notify_event (DwWidget *widget, - guint32 x, - guint32 y, - GdkEventMotion *event); - - Compare button_press_event. event may be NULL when the call was - caused by something different than a "real" motion notify event. - E.g., either when widgets are moved (not yet implemented), or the - viewport. - - - gint enter_notify_event (DwWidget *widget, - DwWidget *last_widget, - GdkEventMotion *event); - - These "events" are simulated based on motion nofify events. - event is the *original* event (may also be NULL in some cases). - last_widget is the widget in which the pointer was in before. - - - gint leave_notify_event (DwWidget *widget, - DwWidget *next_widget, - GdkEventMotion *event); - - Compare enter_notify_event. next_widget is the widget the - pointer is now in. - - -Useful Internal Functions and Macros -==================================== - - - gint Dw_widget_intersect (DwWidget *widget, - DwRectangle *area, - DwRectangle *intersection); - - Calculates the intersection of widget->allocation and area, - returned in intersection (in widget coordinates!). Typically - used by containers when drawing their children. Returns whether - intersection is not empty. - - - gint32 Dw_widget_x_viewport_to_world (DwWidget *widget, - gint16 viewport_x); - - - gint32 Dw_widget_y_viewport_to_world (DwWidget *widget, - gint16 viewport_y); - - - gint16 Dw_widget_x_world_to_viewport (DwWidget *widget, - gint32 world_x); - - - gint16 Dw_widget_y_world_to_viewport (DwWidget *widget, - gint32 world_y); - - These functions convert between world and viewport coordinates. - - - void Dw_widget_queue_draw (DwWidget *widget); - - - void Dw_widget_queue_draw_area (DwWidget *widget, - gint32 x, - gint32 y, - guint32 width, - guint32 height); - - - void Dw_widget_queue_clear (DwWidget *widget); - - - void Dw_widget_queue_clear_area (DwWidget *widget, - gint32 x, - gint32 y, - guint32 width, - guint32 height); - - Equivalents to the Gtk+ functions. They (currently) result in a - call of gtk_widget_xxx_area with the viewport as first - argument. x and y are widget coordinates. - - - void Dw_widget_queue_resize (DwWidget *widget, - gint ref, - gboolean extremes_changed); - - Similar to gtk_widget_queue_resize. Call this function when the - widget has changed its size. The next call to - Dw_xxx_size_request should then return the new size. - - See Dw.txt for explanation on how to use the ref argument, - extremes_changed specifies whether the extremes have changed - (the latter is often not the case for an implementations of - set_{width|ascent|descent}). - - - void Dw_widget_set_anchor (DwWidget *widget, - gchar *name, - int pos); - - Add an anchor to a widget. The name will not be copied, it has - to be stored elsewhere (DwPage e.g. stores it in the DwPageWord - structure). - - - void a_Dw_widget_set_cursor (DwWidget *widget, - GdkCursor *cursor) - - Set the cursor for a DwWidget. cursor has to be stored - elsewhere, it is not copied (and not destroyed). If cursor is - NULL, the cursor of the parent widget is used. - - (This will probably be changed in the future and replaced by a - common style mechanism.) - - - DW_WIDGET_WINDOW (widget) - - Returns the window a widget should draw into. - - -External Functions -================== - - - void a_Dw_widget_set_usize (DwWidget *widget, - guint32 width, - guint32 ascent, - guint32 descent); - - Override the "desired" size of a widget. Further calls of - a_Dw_widget_request_size will return these values, except those - specified as -1. A possible use shows Html_add_widget in - html.c. - - (This will probably be removed. Instead DwStyle should be used.) - - - - void a_Dw_widget_set_bg_color (DwWidget *widget, - gint32 color); - - Set the background color of a widget. This works currently only - for the top-level widget. In this case, the background color of - the GtkDwViewport is changed. In future, background colors for - all widgets will be needed, e.g., for table cells (will be - DwPage's), this will (probably) be based on filled rectangles. - - - void a_Dw_widget_scroll_to (DwWidget *widget, - int pos) - - Scroll viewport to pos (vertical widget coordinate). - -There are furthermore wrappers for the signals, in some cases they -are optimized and/or provide further functionality. In (almost) no -case should you emit the signals directly. See dw_widget.c for more -details.