<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C" xml:lang="en"><title>Control
contexts</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Prior to Symbian OS v9.1 controls were able to share a graphics context
using the <codeph>MCoeControlContext</codeph> API. This was used primarily
in compound controls to achieve a common solid background color 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. </p>
<p> <b>The MCoeControlContext API is now deprecated for UIQ.</b> A description
of the migration process is described below. </p>
<p>S60 and MOAP do not use the new background framework. </p>
<section id="GUID-321057E8-417E-4D8C-8C53-3AE1C80C3ED6"><title/><p><b>Control
Contexts </b> </p> <p>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 <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref>. 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 color settings. </p> <p>Functions
defined by <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref> are called from within the
control framework when a control is about to be drawn. These functions can
be implemented to initialize 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. </p> <p>The context is set for all controls that wish to
use it by setting their <codeph>iContext</codeph> members, either directly,
by using <codeph>CCoeControl::SetControlContext(),</codeph> or by copying
with <codeph>CCoeControl::CopyControlContextFrom()</codeph>. Whenever a control
is about to be drawn the control framework checks if the control has its <codeph>iContext</codeph> member
set and, if so, calls <codeph>MCoeControlContext::ActivateContext()</codeph>.
This function has a default implementation that calls <codeph>MCoeControlContext::PrepareContext()</codeph>,
which should have been implemented to initialize the graphics settings. </p> <p>The
control framework provides one concrete control context class, <codeph>CCoeBrushAndPenContext</codeph>,
which sets graphics context brush and pen settings. Applications derive other
control context classes as required. </p> <p>The control framework automatically
propagates a compound control’s context to all of its components when the
components set their container with <codeph>CCoeControl::SetContainerWindowL()</codeph>. </p> <p> </p> <p><b>The
following section describes how code written for older versions of Symbian
platform must be updated. </b> </p> <p>The following changes need to be made
to existing code: </p> <ul>
<li id="GUID-71F1C167-CD12-5D00-9F16-73732BD698CB"><p>Remove all code referring
to the <codeph>CCoeControl::iContext</codeph> variable. </p> </li>
<li id="GUID-3B13DB08-A7B9-5B2D-9A6D-FBA8D9B3A6B0"><p>Remove all calls to <codeph>CCoeControl’s
                SetControlContext()</codeph>, <codeph>CopyControlContextFrom()</codeph> and <codeph>ControlContext()</codeph>. </p> </li>
<li id="GUID-4CD48156-C053-5DF0-9ACC-9AF5415C3104"><p>Remove all implementations
of the <codeph>MCoeControlContext</codeph> from all custom controls, i.e.
remove all <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph> implementations
from custom controls. </p> </li>
<li id="GUID-AD956F60-78C0-5A77-AE7E-FED2FAA096E8"><p>Remove all use of the <codeph>CCoeBrushAndPenContext</codeph> and <codeph>MCoeControlBrushContext</codeph> APIs. </p> </li>
<li id="GUID-8519E952-7A86-5CE5-BE18-2DA081AA16B9"><p>Remove all calls to <codeph>MCoeControlContext</codeph> ’s <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph>. </p> </li>
<li id="GUID-C27D37C8-7E49-5A62-B7F9-966D66FF1DB5"><p>Remove all code that
clears the area surrounding the controls’ actual graphical representation. </p> </li>
<li id="GUID-1A5941C7-74BC-584C-9733-609EF79CEC19"><p>Change
the draw code of compound controls so that the parent of children correctly
updates the area behind the children. </p> </li>
</ul> <p>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 <xref href="GUID-88936D48-B801-3D9C-8A9D-3498807937CE.dita"><apiname>MCoeControlBackground</apiname></xref> and <xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290.dita#GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290/GUID-FF7DB067-24AD-50C3-BF52-952F836609B0">how
to write a control</xref>. </p> </section>
</conbody></concept>