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