Control -contexts

Prior to Symbian OS v9.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 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.

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

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 <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. 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. 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. 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. 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>. The -following section describes how code written for older versions of Symbian -platform must be updated. The following changes need to be made -to existing code: <ul> -<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">Remove all code referring -to the <codeph>CCoeControl::iContext</codeph> variable. </li> -<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">Remove all calls to <codeph>CCoeControl’s - SetControlContext()</codeph>, <codeph>CopyControlContextFrom()</codeph> and <codeph>ControlContext()</codeph>. </li> -<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">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. </li> -<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">Remove all use of the <codeph>CCoeBrushAndPenContext</codeph> and <codeph>MCoeControlBrushContext</codeph> APIs. </li> -<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">Remove all calls to <codeph>MCoeControlContext</codeph> ’s <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph>. </li> -<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">Remove all code that -clears the area surrounding the controls’ actual graphical representation. </li> -<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">Change -the draw code of compound controls so that the parent of children correctly -updates the area behind the children. </li> -</ul> 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-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 -to write a control</xref>. </section> -</conbody></concept> \ No newline at end of file