Control contexts

Prior to Symbian OS 9.1 controls were able to share a graphics context using the MCoeControlContext API. This was used primarily in compound controls to achieve a common solid background colour and was necessary because controls were required to clear and redraw their own rectangles. Now, with improvements to flicker free drawing and improved framework mechanisms for drawing patterned (skinned) backgrounds, parents and containers are able to provide backgrounds.

The MCoeControlContext API is now deprecated for UIQ.A description of the migration process is described below.

S60 and MOAP do not use the new background framework.

Control Contexts

Control contexts allow a group of controls to share graphics context settings for drawing. Each control may use a control context, a class derived from MCoeControlContext. By using the same control context a group of controls can share common settings. A typical use is for components of a compound control to use the same control context to ensure that they use the same background colour settings.

Functions defined by MCoeControlContext are called from within the control framework when a control is about to be drawn. These functions can be implemented to initialise graphics settings to common values. By using the same control context a group of controls can all be made to use the same graphics settings.

The context is set for all controls that wish to use it by setting their iContext members, either directly, by using CCoeControl::SetControlContext(), or by copying with CCoeControl::CopyControlContextFrom(). Whenever a control is about to be drawn the control framework checks if the control has its iContext member set and, if so, calls MCoeControlContext::ActivateContext(). This function has a default implementation that calls MCoeControlContext::PrepareContext(), which should have been implemented to initialise the graphics settings.

The control framework provides one concrete control context class, CCoeBrushAndPenContext, which sets graphics context brush and pen settings. Applications derive other control context classes as required.

The control framework automatically propagates a compound control’s context to all of its components when the components set their container with CCoeControl::SetContainerWindowL().

The following section describes how code written for older versions of Symbian OS should be updated.

The following changes need to be made to existing code:

• 1. Remove all code referring to the CCoeControl::iContext variable.

• 2. Remove all calls to CCoeControl’s SetControlContext(), CopyControlContextFrom() and ControlContext().

• 3. Remove all implementations of the MCoeControlContext from all custom controls, i.e. remove all ActivateContext(), ResetContext() and PrepareContext() implementations from custom controls.

• 4. Remove all use of the CCoeBrushAndPenContext and MCoeControlBrushContext APIs.

• 5. Remove all calls to MCoeControlContext’s ActivateContext(), ResetContext() and PrepareContext().

• 6. Remove all code that clears the area surrounding the controls’ actual graphical representation.

• 7. Change the draw code of compound controls so that the parent of children correctly updates the area behind the children.

This stage 7 will not work for window-owning controls as the Window Server will prevent the parent from drawing behind the child's window. See MCoeControlBackground and how to write a control.