dw-layout-views.doc

/** \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 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. A platform is typically related to the underlying UI
toolkit, but other uses may be thought of.

This design helps to archieve two important goals:

<ul>
<li> Abstraction of the actual drawing, by different implementations
     of dw::core::View.

<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 achieved,
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>

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

<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. The view returns, via
dw::core::View::getHScrollbarThickness and
dw::core::View::getVScrollbarThickness, how thick they will be, when
visible.

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

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

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 view delegates this
     change to the layout, by calling
     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 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 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 is 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>

*/