/** \page dw-layout-views Layout and Views

Rendering of Dw is done in a way resembling the model-view pattern, at
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
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.

This design helps to archieve three 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.

<li> It makes portability simple.
</ul>


<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,
for the following reasons:

<ul>
<li> Some features, which are used on the level of dw::core::Widget,
     e.g. anchors, refer to scrolling positions.

<li> Size hints (see \ref dw-layout-widgets) depend on the viewport
     sizes, e.g. when the user changes the window size, and so also
     the size of a viewport, the text within should be rewrapped.
</ul>

Therefor, 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.)

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
method returns false, the following methods need not to be implemented
at all:

<ul>
<li> dw::core::View::getHScrollbarThickness,
<li> dw::core::View::getVScrollbarThickness,
<li> dw::core::View::scrollTo, and
<li> dw::core::View::setViewportSize.
</ul>

<h3>Scrolling Positions</h3>

The scrolling position is the canvas position at the upper left corner
of the viewport. Views using viewports must

<ol>
<li> change this value on request (dw::core::View::scrollTo), and
<li> tell other changes to the layout, e.g. caused by user events
     (dw::core::Layout::scrollPosChanged).
</ol>

Applications of scrolling positions (anchors, test search etc.) are
handled by the layout, in a way fully transparent to the views.

<h3>Scrollbars</h3>

A feature of the viewport size model are scrollbars. There may be a
vertical scrollbar and a horizontal scrollbar, displaying the
relationship between canvas and viewport height or width,
respectively. If they are not needed, they are hidden, to save screen
space.

Since scrollbars decrease the usable space of a view, dw::core::Layout
must know how much space they take. Each 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.

Viewport sizes, which denote the size of the viewport widgets, include
scrollbar thicknesses. When referring to the viewport \em excluding
the scrollbars space, we will call it "usable viewport size", this is
the area, which is used to display the canvas.

<h2>Drawing</h2>

A view must implement several drawing methods, which work on the whole
canvas. If it is neccesary to convert them (e.g. into
dw::fltk::FltkViewport), this is done in a way fully transparent to
dw::core::Widget and dw::core::Layout, instead, this is done by the
view implementation.

There exist following situations:

<ul>
<li> A view gets an expose event: It will delegate this to the
     layout (dw::core::Layout::draw), which will then pass it to the
     widgets (dw::core::Widget::draw), with the view as a parameter.
     Eventually, the widgets will call drawing methods of the view.

<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.

<li> A widget requests a resize: This case is described below, in short,
     dw::core::View::queueDrawTotal is called for the view.
</ul>

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
<i>clipping view.</i> A clipping view is a view related to the actual
view, which guarantees that the parts drawn outside are discarded. At
the end, the clipping view is merged into the actual view. Sample
code:

\code
void Foo::draw (dw::core::View *view, dw::core::Rectangle *area)
{
   // 1. Create a clipping view.
   dw::core::View clipView =
      view->getClippingView (allocation.x, allocation.y,
                             allocation.width, getHeight ());

   // 2. Draw into clip_view
   clipView->doSomeDrawing (...);

   // 3. Draw the children, they receive the clipping view as argument.
   dw::core::Rectangle *childArea
   for (<all relevant children>) {
      if (child->intersects (area, &childArea))
         child->draw (clipView, childArea);
   }

   // 4. Merge
   view->mergeClippingView (clipView);
}
\endcode

A drawing process is always embedded into calls of
dw::core::View::startDrawing and dw::core::View::finishDrawing. An
implementation of this may e.g. use backing pixmaps, to prevent
flickering.


<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 following situations:

<ul>
<li> dw::core::Layout::addWidget,
<li> dw::core::Layout::removeWidget (called by dw::core::Widget::~Widget),
     and
<li> dw::core::Layout::queueResize (called by
     dw::core::Widget::queueResize, when a widget itself requests a size
     change).
</ul>

<h3>Viewports</h3>

Furthermore, viewport sizes and scrollbar thicknesses are always the
same. There are two cases, in which 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
     change to the layout, by calling
     dw::core::Layout::viewportSizeChanged. All other views are
     told about this, by calling dw::core::Layout::setViewportSize.

<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
     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
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.

Generally, the scrollbars have to be considered. If e.g. an HTML page
is rather small, it looks like this:

\image html dw-viewport-without-scrollbar.png

If some more data is retrieved, so that the height exceeds the
viewport size, the text has to be rewrapped, since the available width
gets smaller, due to the vertical scrollbar:

\image html dw-viewport-with-scrollbar.png

Notice the different line breaks.

This means circular dependencies between these different sizes:

<ol>
<li> Whether the scrollbars are visible or not, determines the
     usable space of the viewport.

<li> From the usable space of the viewport, the size hints for the
     toplevel are calculated.

<li> The size hints for the toplevel widgets may have an effect on its
     size, which is actually the canvas size.

<li> The canvas size determines the visibility of the scrollbarss.
</ol>

To make an implementation simpler, we simplify the model:

<ol>
<li> For the calls to dw::core::Widget::setAscent and
     dw::core::Widget::setDescent, we will always exclude the
     horizontal scrollbar thickness (i.e. assume the horizontal
     scrollbar is used, although the visibility is determined correctly).

<li> For the calls to dw::core::Widget::setWidth, we will calculate
     the usable viewport width, but with the general assumption, that
     the widget generally gets higher.
</ol>

This results in the following rules:

<ol>
<li> Send always (when it changes) dw::core::Layout::viewportHeight
     minus the maximal value of dw::core::View::getHScrollbarThickness as
     argument to dw::core::Widget::setAscent, and 0 as argument to
     dw::core::Widget::setDescent.

<li> There is a flag, dw::core::Layout::canvasHeightGreater, which is set
     to false in the following cases:

     <ul>
     <li> dw::core::Layout::addWidget,
     <li> dw::core::Layout::removeWidget (called by dw::core::Widget::~Widget),
          and
     <li> dw::core::Layout::viewportSizeChanged.
     </ul>

     Whenever the canvas size is calculated (dw::core::Layout::resizeIdle),
     and dw::core::Layout::canvasHeightGreater is false, a test is made,
     whether the widget has in the meantime grown that high, that the second
     argument should be set to true (i.e. the vertical scrollbar gets visible).
     As soon as and dw::core::Layout::canvasHeightGreater is true, no such test
     is done anymore.
</ol>

*/