Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1.dita
changeset 7 51a74ef9ed63
equal deleted inserted replaced
6:43e37759235e 7:51a74ef9ed63
       
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE concept
       
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
       
    12 <concept id="GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1" xml:lang="en"><title>Control
       
    13 contexts</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <p>Prior to Symbian OS v9.1 controls were able to share a graphics context
       
    15 using the <codeph>MCoeControlContext</codeph> API. This was used primarily
       
    16 in compound controls to achieve a common solid background color and was necessary
       
    17 because controls were required to clear and redraw their own rectangles. Now,
       
    18 with improvements to flicker free drawing and improved framework mechanisms
       
    19 for drawing patterned (skinned) backgrounds, parents and containers are able
       
    20 to provide backgrounds. </p>
       
    21 <p> <b>The MCoeControlContext API is now deprecated for UIQ.</b> A description
       
    22 of the migration process is described below. </p>
       
    23 <p>S60 and MOAP do not use the new background framework. </p>
       
    24 <section id="GUID-321057E8-417E-4D8C-8C53-3AE1C80C3ED6-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4"><title/><p><b>Control
       
    25 Contexts </b> </p> <p>Control contexts allow a group of controls to share
       
    26 graphics context settings for drawing. Each control may use a control context,
       
    27 a class derived from <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref>. By using the same
       
    28 control context a group of controls can share common settings. A typical use
       
    29 is for components of a compound control to use the same control context to
       
    30 ensure that they use the same background color settings. </p> <p>Functions
       
    31 defined by <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref> are called from within the
       
    32 control framework when a control is about to be drawn. These functions can
       
    33 be implemented to initialize graphics settings to common values. By using
       
    34 the same control context a group of controls can all be made to use the same
       
    35 graphics settings. </p> <p>The context is set for all controls that wish to
       
    36 use it by setting their <codeph>iContext</codeph> members, either directly,
       
    37 by using <codeph>CCoeControl::SetControlContext(),</codeph> or by copying
       
    38 with <codeph>CCoeControl::CopyControlContextFrom()</codeph>. Whenever a control
       
    39 is about to be drawn the control framework checks if the control has its <codeph>iContext</codeph> member
       
    40 set and, if so, calls <codeph>MCoeControlContext::ActivateContext()</codeph>.
       
    41 This function has a default implementation that calls <codeph>MCoeControlContext::PrepareContext()</codeph>,
       
    42 which should have been implemented to initialize the graphics settings. </p> <p>The
       
    43 control framework provides one concrete control context class, <codeph>CCoeBrushAndPenContext</codeph>,
       
    44 which sets graphics context brush and pen settings. Applications derive other
       
    45 control context classes as required. </p> <p>The control framework automatically
       
    46 propagates a compound control’s context to all of its components when the
       
    47 components set their container with <codeph>CCoeControl::SetContainerWindowL()</codeph>. </p> <p> </p> <p><b>The
       
    48 following section describes how code written for older versions of Symbian
       
    49 platform must be updated. </b> </p> <p>The following changes need to be made
       
    50 to existing code: </p> <ul>
       
    51 <li id="GUID-71F1C167-CD12-5D00-9F16-73732BD698CB-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-1"><p>Remove all code referring
       
    52 to the <codeph>CCoeControl::iContext</codeph> variable. </p> </li>
       
    53 <li id="GUID-3B13DB08-A7B9-5B2D-9A6D-FBA8D9B3A6B0-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-2"><p>Remove all calls to <codeph>CCoeControl’s
       
    54                 SetControlContext()</codeph>, <codeph>CopyControlContextFrom()</codeph> and <codeph>ControlContext()</codeph>. </p> </li>
       
    55 <li id="GUID-4CD48156-C053-5DF0-9ACC-9AF5415C3104-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-3"><p>Remove all implementations
       
    56 of the <codeph>MCoeControlContext</codeph> from all custom controls, i.e.
       
    57 remove all <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph> implementations
       
    58 from custom controls. </p> </li>
       
    59 <li id="GUID-AD956F60-78C0-5A77-AE7E-FED2FAA096E8-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-4"><p>Remove all use of the <codeph>CCoeBrushAndPenContext</codeph> and <codeph>MCoeControlBrushContext</codeph> APIs. </p> </li>
       
    60 <li id="GUID-8519E952-7A86-5CE5-BE18-2DA081AA16B9-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-5"><p>Remove all calls to <codeph>MCoeControlContext</codeph> ’s <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph>. </p> </li>
       
    61 <li id="GUID-C27D37C8-7E49-5A62-B7F9-966D66FF1DB5-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-6"><p>Remove all code that
       
    62 clears the area surrounding the controls’ actual graphical representation. </p> </li>
       
    63 <li id="GUID-1A5941C7-74BC-584C-9733-609EF79CEC19-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-7"><p>Change
       
    64 the draw code of compound controls so that the parent of children correctly
       
    65 updates the area behind the children. </p> </li>
       
    66 </ul> <p>This stage 7 will not work for window-owning controls as the Window
       
    67 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-GENID-1-8-1-3-1-1-7-1-9-1.dita#GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1/GUID-FF7DB067-24AD-50C3-BF52-952F836609B0-GENID-1-8-1-3-1-1-7-1-9-1-2-18">how
       
    68 to write a control</xref>. </p> </section>
       
    69 </conbody></concept>