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 Layout and 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:

• Abstraction of the actual drawing, by different implementations of dw::core::View.

• It makes portability simple.

Viewports

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:

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

• Size hints (see Layout and 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.

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:

• dw::core::View::getHScrollbarThickness,
• dw::core::View::getVScrollbarThickness,
• dw::core::View::scrollTo, and
• dw::core::View::setViewportSize.

Scrolling Positions

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

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

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

Scrollbars

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 excluding the scrollbars space, we will call it "usable viewport size", this is the area, which is used to display the canvas.

Drawing

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:

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

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

• A widget requests a resize: This case is described below, in short, dw::core::View::queueDrawTotal is called for the view.

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

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);
}

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.

Sizes

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:

• dw::core::Layout::addWidget,
• dw::core::Layout::removeWidget (called by dw::core::Widget::~Widget), and
• dw::core::Layout::queueResize (called by dw::core::Widget::queueResize, when a widget itself requests a size change).

Viewports

There are two cases where the viewport size changes:

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

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

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:

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:

Notice the different line breaks.

This means circular dependencies between these different sizes:

1. Whether the scrollbars are visible or not, determines the usable space of the viewport.

2. From the usable space of the viewport, the size hints for the toplevel are calculated.

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

4. The canvas size determines the visibility of the scrollbarss.

To make an implementation simpler, we simplify the model:

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

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

This results in the following rules:

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

2. There is a flag, dw::core::Layout::canvasHeightGreater, which is set to false in the following cases:
   • dw::core::Layout::addWidget,
   • dw::core::Layout::removeWidget (called by dw::core::Widget::~Widget), and
   • dw::core::Layout::viewportSizeChanged.

   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.