<?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-97486385-88F7-4AF1-B880-D9A8AA4D7094" xml:lang="en"><title>Compound
controls in traditional 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 (main control
that owns the window in which the child control appears). The control should
be constructed in the constructor for the window. An example of an implementation
is as follows:</p>
<itemgroup>
<codeblock id="GUID-F5320B9F-2CC1-4190-B75A-AF303DC5EB8B" 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> object,
which is a 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> makes the <xref href="GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita">non-window-owning control</xref> a
child of 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-73DD2770-41FC-4B29-AA8A-4B9010654B64" 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-14C8180C-9A7E-4CA8-A631-EB2A0179352C" 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 two ways to implement
a compound control. One way is to override this function. The other way is
to 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>
<note>
<p>Within a compound control, each component control is identified by an
index. </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. You can adjust the
visibility of a control 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>