|
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" 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"><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"><p>Remove all code referring |
|
52 to the <codeph>CCoeControl::iContext</codeph> variable. </p> </li> |
|
53 <li id="GUID-3B13DB08-A7B9-5B2D-9A6D-FBA8D9B3A6B0"><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"><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"><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"><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"><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"><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.dita#GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290/GUID-FF7DB067-24AD-50C3-BF52-952F836609B0">how |
|
68 to write a control</xref>. </p> </section> |
|
69 </conbody></concept> |