Drawing +Tutorial

Variant: Both (ScreenPlay and non-ScreenPlay). Target +audience: Application developers.

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.