changeset 1459:a85637dacd8d

documentation: no more multiple views
author corvid <corvid@lavabit.com>
date Mon, 30 Nov 2009 23:54:41 +0000
parents a4f67c66575b
children a41372a38f02
files doc/dw-changes.doc doc/dw-layout-views.doc doc/dw-layout-widgets.doc doc/dw-overview.doc
diffstat 4 files changed, 37 insertions(+), 58 deletions(-) [+]
line wrap: on
line diff
--- a/doc/dw-changes.doc	Mon Nov 30 20:33:15 2009 +0000
+++ b/doc/dw-changes.doc	Mon Nov 30 23:54:41 2009 +0000
@@ -17,10 +17,6 @@
      <li> The central class managing the widget tree is not anymore
           GtkDwViewport,  but dw::core::Layout.
 
-     <li> There are multiple views (implementations of dw::core::View).
-          Typically, you keep a reference on dw::core::Layout and a "main"
-          view (a viewport).
-
      <li> Drawing is done via dw::core::View, a pointer is passed to
           dw::core::Widget::draw.
 
--- a/doc/dw-layout-views.doc	Mon Nov 30 20:33:15 2009 +0000
+++ b/doc/dw-layout-views.doc	Mon Nov 30 23:54:41 2009 +0000
@@ -4,23 +4,18 @@
 least formally.  Actually, the counterpart of the model, the layout
 (dw::core::Layout), does a bit more than a typical model, namely the
 layouting (delegated to the widget tree, see \ref dw-layout-widgets),
-and the views do a bit less than a typical view, i.e. only the actual
+and the view does 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
+the platform. A platform is typically related to the underlying UI
 toolkit, but other uses may be thought of.
 
-This design helps to archieve three important goals:
+This design helps to archieve two important goals:
 
 <ul>
-<li> It makes different views of the same document simple, e.g. the
-     normal viewport and the preview window.
-
 <li> Abstraction of the actual drawing, by different implementations
-     of dw::core::View. Most important, there must be a viewport, but
-     some other views are possible, e.g. a preview window.
+     of dw::core::View.
 
 <li> It makes portability simple.
 </ul>
@@ -29,7 +24,7 @@
 <h2>Viewports</h2>
 
 Although the design implies that the usage of viewports should be
-fully transparent to the layout module, this cannot be fully archived,
+fully transparent to the layout module, this cannot be fully achieved,
 for the following reasons:
 
 <ul>
@@ -41,15 +36,10 @@
      the size of a viewport, the text within should be rewrapped.
 </ul>
 
-Therefor, dw::core::Layout keeps track of the viewport size, the
+Therefore, dw::core::Layout keeps track of the viewport size, the
 viewport position, and even the thickness of the scrollbars, they are
-relevant, see below for more details. 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.
-
-(The case, that there is no viewport at all, is currently not well
-defined, but this case does not occur currently within dillo.)
+relevant, see below for more details.
+If a viewport is not used, however, the size is not defined.
 
 Whether a given dw::core::View implementation is a viewport or not, is
 defined by the return value of dw::core::View::usesViewport. If this
@@ -75,7 +65,7 @@
 </ol>
 
 Applications of scrolling positions (anchors, test search etc.) are
-handled by the layout, in a way fully transparent to the views.
+handled by the layout, in a way fully transparent to the view.
 
 <h3>Scrollbars</h3>
 
@@ -86,11 +76,10 @@
 space.
 
 Since scrollbars decrease the usable space of a view, dw::core::Layout
-must know how much space they take. Each view returns, via
+must know how much space they take. The view returns, via
 dw::core::View::getHScrollbarThickness and
 dw::core::View::getVScrollbarThickness, how thick they will be, when
-visible. The total space difference is then the maximum of all values,
-which the views return.
+visible.
 
 Viewport sizes, which denote the size of the viewport widgets, include
 scrollbar thicknesses. When referring to the viewport \em excluding
@@ -115,8 +104,8 @@
 
 <li> A widget requests a redraw: In this case, the widget will
      delegate this to the layout (dw::core::Layout::queueDraw), which
-     delegates it to all views (dw::core::View::queueDraw).
-     Typically, the views will queue these requests, for efficiency.
+     delegates it to the view (dw::core::View::queueDraw).
+     Typically, the view will queue these requests for efficiency.
 
 <li> A widget requests a resize: This case is described below, in short,
      dw::core::View::queueDrawTotal is called for the view.
@@ -160,10 +149,9 @@
 
 <h2>Sizes</h2>
 
-Generally, all views show the same layout, which has a given size
-(canvas size). In the simplest case, views do not have an influence on
-the canvas size, so that they are just told about changes of the
-canvas size, by a call to dw::core::View::setCanvasSize. This happens
+In the simplest case, the view does not have any influence on
+the canvas size, so it is told about changes of the
+canvas size by a call to dw::core::View::setCanvasSize. This happens
 in the following situations:
 
 <ul>
@@ -177,28 +165,26 @@
 
 <h3>Viewports</h3>
 
-Furthermore, viewport sizes and scrollbar thicknesses are always the
-same. There are two cases, in which the viewport size changes:
+There are two cases where the viewport size changes:
 
 <ul>
 <li> As an reaction on a user event, e.g. when the user changes the
-     window size. In this case, the affected view delegates this
+     window size. In this case, the view delegates this
      change to the layout, by calling
-     dw::core::Layout::viewportSizeChanged. All other views are
-     told about this, by calling dw::core::Layout::setViewportSize.
+     dw::core::Layout::viewportSizeChanged.
 
 <li> 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
+     generally called "viewport markers". This is described in a separate
      section.
 </ul>
 
 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
+a view is attached to a layout, and this view can already specify
+its viewport size, it may call
 dw::core::Layout::viewportSizeChanged within the implementation of
-dw::core::Layout::setLayout. If not, it may do this, as soon as the
-viewport size gets known.
+dw::core::Layout::setLayout. If not, it may do this as soon as the
+viewport size is known.
 
 Generally, the scrollbars have to be considered. If e.g. an HTML page
 is rather small, it looks like this:
--- a/doc/dw-layout-widgets.doc	Mon Nov 30 20:33:15 2009 +0000
+++ b/doc/dw-layout-widgets.doc	Mon Nov 30 23:54:41 2009 +0000
@@ -107,14 +107,11 @@
 </ol>
 
 In both cases, drawing is done by the implementation of
-dw::core::Widget::draw. Generally, a widget draws into different views
-(see \ref dw-layout-views), the view to draw into is passed as the
-first argument. In the first case, only the view, which causes the
-expose event, is passed, in the second case, dw::core::Widget::draw is
-called multiple times, once for each view connected to the layout.
+dw::core::Widget::draw, which draws into the view.
+
 
 Each view provides some primitive methods for drawing, most should be
-obvious. Notice that the views do not know anything about dillo
+obvious. Note that the views do not know anything about dillo
 widgets, and so coordinates have to be passed as canvas coordinates.
 
 A widget may only draw in its own allocation. If this cannot be
@@ -144,7 +141,7 @@
 }
 \endcode
 
-Clipping views are expensive, so they should be avoided, when possible.
+Clipping views are expensive, so they should be avoided when possible.
 
 The second argument to dw::core::Widget::draw is the region, which has
 to be drawn. This may (but needs not) be used for optimization.
@@ -169,9 +166,9 @@
 
 <h2>Mouse Events</h2>
 
-A widget may process mouse events. The views (\ref dw-layout-views)
-pass mouse events to the layout, which then passes them to the
-widgtes. There are two kinds of mouse events:
+A widget may process mouse events. The view (\ref dw-layout-views)
+passes mouse events to the layout, which then passes them to the
+widgets. There are two kinds of mouse events:
 
 <ul>
 <li>events returning bool, and
@@ -221,9 +218,9 @@
 The following paths are calculated:
 
 <ol>
-<li> the path from the old widget to the nearest common anchestor of the old
+<li> the path from the old widget to the nearest common ancestor of the old
      and the new widget, and
-<li> the path from this anchestor to the new widget.
+<li> the path from this ancestor to the new widget.
 </ol>
 
 For the widgets along these paths, dw::core::Widget::enterNotifyImpl
--- a/doc/dw-overview.doc	Mon Nov 30 20:33:15 2009 +0000
+++ b/doc/dw-overview.doc	Mon Nov 30 23:54:41 2009 +0000
@@ -108,13 +108,13 @@
 
 <ul>
 <li> dw::core::Layout is the central class, it manages the widgets and the
-     views, and provides delegation methods for the platform.
+     view, and provides delegation methods for the platform.
 
 <li> The layouting is done by a tree of widgets (details are described in
      \ref dw-layout-widgets), also the drawing, which is finally delegated
-     to the views.
+     to the view.
 
-<li> The views (implementations of dw::core::View) provide primitive methods
+<li> The view (implementation of dw::core::View) provides primitive methods
      for drawing, but also have an influence on
      the canvas size (via size hints). See \ref dw-layout-views for details.
 
@@ -154,4 +154,4 @@
      \ref dw-widget-sizes and \ref dw-layout-views.
 </ul>
 
-*/
\ No newline at end of file
+*/