Drawing Tutorial

Standard windows

All drawing to standard windows must be redraw drawing, which means that it takes place between RWindow::BeginRedraw() and RWindow::EndRedraw() calls. If you use the CCoeControl::DrawNow() and CCoeControl::DrawDeferred() methods, CONE takes care of this for you.

To redraw to an RWindow, an application starts the sequence by activating a CWindowGc to use a particular window for drawing, it then calls RWindow::BeginRedraw() before issuing the drawing commands and finally calling RWindow::EndRedraw(). For example:

gc->Activate(iWindow);
iWindow.BeginRedraw(rect);
DoDraw(rect);
iWindow.EndRedraw();
gc->Deactivate();

BeginRedraw() does the following:

• marks the rectangle passed as its argument as valid (in other words, it removes the rectangle from the invalid region of the window)

• sets the clipping region to the intersection of the invalid region and the rectangle passed as its argument.

In a server-initiated redraw, the drawing must exactly match what was drawn originally, because the Window Server clips the drawing to the newly validated region. If the rectangle drawn in response to a redraw event does not cover the entire invalid region, the Window Server generates another redraw event specifying the bounding rectangle of the region that is still invalid. This continues until the entire window is valid.

In an application-initiated redraw, it is good practice to invalidate the whole region before passing it to the redraw. For example:

gc->Activate(iWindow);
iWindow.Invalidate(rect);
iWindow.BeginRedraw(rect);
DoDraw(rect);
iWindow.EndRedraw();
gc->Deactivate();

After this sequence, the entire window is valid.

Backed-up windows

Backed-up windows are redrawn by the Window Server from the backup bitmap and not by the application. They therefore have no RWindow::Invalidate(), RWindow::BeginRedraw() or RWindow::EndRedraw() member functions. The sequence for drawing to backed-up windows is therefore as follows:

gc->Activate(iWindow);
DoDraw(rect);
gc->Deactivate();

Note: Backed-up windows are deprecated in Symbian^3.

Pre-emptive multi tasking

Because Symbian is a pre-emptive system, another application—or the Window Server itself—may pre-empt the application that is drawing or redrawing. The result is that DoDraw() may be partially complete when preemption occurs. Then, when the DoDraw() receives control again, it may draw to an area that has been invalidated without its knowledge.

For this reason, the Window Server marks a window region as valid at RWindow::BeginRedraw() time, not at RWindow::EndRedraw() time. Then, any regions that become invalid because of a preempting application’s activity are correctly added to the invalid region. The DoDraw() completes, but the Window Server generates another redraw event and the application must start the redraw again.