<?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->SetContainerWindowL( *this );

    iLabel->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>