<?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-57CA8A13-05C6-4AFE-9804-E2EA2453143A" xml:lang="en"><title>Compound
controls in the view architecture</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p><xref href="GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita">Compound controls</xref> are
controls that contain other controls. To create a compound control, you must
do the following:</p>
<ul>
<li><p>construct the control in the parent control (that owns the
window in which the child control appears). An example of an implementation
is as follows:</p>
<itemgroup>
<codeblock id="GUID-87D5DA2C-DF12-40CA-8F39-CA9B61500F8F" xml:space="preserve">void CMyViewContainer::ConstructL(const TRect&amp; aRect)
    {
    CreateWindowL();

    iLabel = new (ELeave) CEikLabel;
    iLabel-&gt;SetContainerWindowL( *this );
    iLabel-&gt;SetTextL( _L("MyView 1\n\nSelect local view\nswitching from menu") );

    SetRect(aRect);
    ActivateL();
    }</codeblock>
<p>, where</p>
<p><parmname>iLabel = new (ELeave) CEikLabel;</parmname> creates a <xref href="GUID-086B6DC9-E348-39C8-A9CB-686383CEA6EF.dita"><apiname>CEikLabel</apiname></xref> class
that supports the display of text in the parent window.</p>
<p><xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-A39BAD7E-BAF2-3A4B-BE4F-2A86718EB190"><apiname>CCoeControl::SetContainerWindowL()</apiname></xref> assigns the non-window-owning
control to the window-owning control.</p>
<p><xref href="GUID-086B6DC9-E348-39C8-A9CB-686383CEA6EF.dita#GUID-086B6DC9-E348-39C8-A9CB-686383CEA6EF/GUID-879C7EC4-EDE0-3E2E-A827-CEAFB84154F7"><apiname>CEikLabel::SetTextL()</apiname></xref> sets a text for the label.</p>
<p>The other methods are the standard methods for creating a window for
the window-owning control.</p>
</itemgroup>
</li>
<li><p>add a method to the owning control that returns the number
of controls in the compound control. An example of an implementation is as
follows:</p>
<itemgroup>
<codeblock id="GUID-048B5DCE-124A-4530-89AD-842DCA2F3FFC" xml:space="preserve">TInt CMyViewAppContainer::CountComponentControls() const
    {
    return KNumberOfControls; // return nbr of controls inside this compound control
    }</codeblock>
<p>, where</p>
<p><parmname>CMyViewAppContainer::CountComponentControls()</parmname> overrides <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-6F8D41E5-9B2C-3CEB-9F2F-9E2567D5BE39"><apiname>CCoeControl::CountComponentControls()</apiname></xref> to
return the number of controls in the compound control.</p>
<p><parmname>KNumberOfControls</parmname> is a <parmname>TInt</parmname> constant
for the number of controls in the application. Other approaches could be used.</p>
</itemgroup>
</li>
<li><p>Add a method to the owning control that returns each of the
controls by a zero-based index. An example of an implementation is as follows:</p>
<itemgroup>
<codeblock id="GUID-3A8A5312-117E-466F-A5BC-6B7AF0A75B9C" xml:space="preserve">CCoeControl* CContainerContainer::ComponentControl(
    TInt aIndex)  const
    {
        switch ( aIndex )
        {
        case 0:
            return iLabel; // return a pointer to the 
                             //iLabel
        default:
            return NULL;
        }
    }
</codeblock>
<p>, where</p>
<p><parmname>CCoeControl* CContainerContainer::ComponentControl(TInt aIndex)</parmname> gets
an indexed component of a compound control.  There are 2 ways to implement
a compound control:</p>
<ul>
<li><p>override the function.</p></li>
</ul>
<ul>
<li><p>use the <xref href="GUID-2D8BFBA2-79AC-364D-875D-E863CD4A2FE1.dita"><apiname>CCoeControlArray</apiname></xref> functionality
(see the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-40A8481A-F12C-3A5A-B84A-710301940585"><apiname>CCoeControl::InitComponentArrayL()</apiname></xref> method). </p>
</li>
</ul>
<note>
<p> Within a compound control, each component control is identified by
an index, where the index depends on the order the controls were added: the
first is given an index of <parmname>0</parmname>, the next an index of <parmname>1</parmname>,
and so on. </p>
</note>
<p>All child controls should be accessible by <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-B727C7DA-6DEF-339D-A31E-A292BD800A3B"><apiname>CCoeControl::ComponentControl()</apiname></xref> at
any time, regardless of whether they are visible or not. The visibility of
a control should be adjusted using the <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-159A51CE-4AEF-367B-9182-F33489D08BE2"><apiname>CCoeControl::MakeVisible()</apiname></xref> method.</p>
</itemgroup>
</li>
</ul>
<p><parmname>CCoeControl* CContainerContainer::ComponentControl(TInt aIndex)</parmname> and <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita#GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160/GUID-6F8D41E5-9B2C-3CEB-9F2F-9E2567D5BE39"><apiname>CCoeControl::CountComponentControls()</apiname></xref> work in conjunction with each other. The Symbian platform can query the
control as to how many components it has and then request a pointer to each
of the component's controls. Controls can be added or removed at run time
using these two methods. The framework uses this information to draw the container. </p>
<p>The compound control usually owns the child controls and therefore it
is responsible of their construction and destruction. The compound control
should also set the positions and sizes of its child controls; it must ensure
that all child controls are inside the compound control rectangle and visible
child rectangles do not overlap each other.</p>
</conbody></concept>