Drawing Tutorial

Standard windows

All drawing to standard windows must be redraw drawing, which means that it takes place between [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow::BeginRedraw() and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow::EndRedraw() calls. If you use the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]CCoeControl::DrawNow() and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]CCoeControl::DrawDeferred() methods, CONE takes care of this for you.

To redraw to an [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow, an application starts the sequence by activating a [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]CWindowGc to use a particular window for drawing, it then calls [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow::BeginRedraw() before issuing the drawing commands and finally calling [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow::Invalidate(), [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow::BeginRedraw() or [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]RWindow::BeginRedraw() time, not at [[[ERROR: [NOKX000E] Unable to find definition for key reference 'RWindow']]]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.