<?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, which is the

control that owns the window in which the 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-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="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCEikLabel.html" format="application/java-archive"><parmname>CEikLabel</parmname></xref> object,

which is a class that supports the display of text in the parent window.</p>

<p><xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aSetContainerWindowL%28const%20CCoeControl%20%26amp%3b%29" format="application/java-archive"><parmname>CCoeControl::SetContainerWindowL</parmname></xref> assigns

the non-window-owning control to the window-owning control</p>

<p><xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCEikLabel.html#bcf1d51ebf4177465387f76584078f0c" format="application/java-archive"><parmname>CEikLabel::SetTextL</parmname></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="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aCountComponentControls%28%29const" format="application/java-archive"><parmname>CCoeControl::CountComponentControls</parmname></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. One way is to override this function. The other way is

to use the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlArrayClass.html#_top%20title=" format="application/java-archive"><parmname>CCoeControlArray</parmname></xref> functionality (see the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aInitComponentArrayL%28%29" format="application/java-archive"><parmname>CCoeControl::InitComponentArrayL</parmname></xref> method).

 Note: 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>

<p>All child controls should be accessible by <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aComponentControl%28TInt%29const" format="application/java-archive"><parmname>CCoeControl::ComponentControl</parmname></xref> at any time, regardless

of whether they are visible or not. The visibility of a control should be

adjusted using the <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aMakeVisible%28TBool%29" format="application/java-archive"><parmname>CCoeControl::MakeVisible</parmname></xref> method.</p>

</itemgroup>

</li>

</ul>

<p><parmname>CCoeControl* CContainerContainer::ComponentControl(TInt aIndex)</parmname> and <xref href="jar:GUID-35228542-8C95-4849-A73F-2B4F082F0C44.jar!/sdk/doc_source/reference/reference-cpp/Control_Environment/CCoeControlClass.html#%3a%3aCCoeControl%3a%3aCountComponentControls%28%29const" format="application/java-archive"><parmname>CCoeControl::CountComponentControls</parmname></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>