/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "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:

*

* Description:   Control group

*

*/

#ifndef C_ALFCONTROLGROUP_H

#define C_ALFCONTROLGROUP_H

#include <e32base.h>

class CAlfEnv;

class CAlfControl;

class CAlfTransformation;

class CAlfDisplay;

/**

 *  A control group class is used to group controls that belong together.

 *

 *  Control group contains CAlfControl - derived classes. Control group can be

 *  used to create logical compounds of several controls. For instance all controls

 *  belonging to the same UI view can be grouped into a single control group.

 *

 *  Control groups should be instantiated through CAlfEnv::NewControlGroupL().

 *  Usage:

 *  @code

 * //Create a new control group

 *  CAlfControlGroup& group = iEnv->NewControlGroupL( KControlGroupIdDefault );

 * 

 * //Create control instance and append it to group

 *  CMyControl* control = CMyControl::ConstructL(&iEnv);

 *  group.AppendL( control );

 * 

 *  //Show control group on display

 *  iDisplay->Roster().ShowL( group );

 *  @endcode 

 *  @lib alfclient.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( CAlfControlGroup ): public CBase

    {

public:

    /**

     * 1st phase constructor.

     */

    CAlfControlGroup();

    /**

     * 2nd phase constructor.

     * @param aResourceId Identifier.

     * @param aEnv The env.

     */

    void ConstructL( TInt aResourceId, CAlfEnv& aEnv );

    /**

     * Destructor.

     */

    virtual ~CAlfControlGroup();

    /**

     * Return the server side handle

     *

     * @return Handle to the server side CAlfSrvControlGroupSubSession object. 

     *         0 if not set.

     */

    TInt Identifier() const;

    /**

     * Binds a display to a control group. If a display is bound to a control group

     * it is being shown. Otherwise the control group is hidden. CAlfRoster uses

     * this method to notify control group about the display on which it is shown.

     * User should use methods in CAlfRoster to show or hide a control group.

     *

     * @see CAlfRoster

     *

     * @param aDisplay Pointer to a display on which this control group is shown,

     *                 or NULL if control group is hidden.

     */

    void BindDisplay(CAlfDisplay* aDisplay);

    /**

	 * Determines the identifier of the control group (from a resource file).

	 *

	 * @return  Resource identifier.

	 */

    IMPORT_C TInt ResourceId() const;

    /**

	 * Adds a new control into the group. The group takes ownership of the

	 * control.

	 *

	 * @param aControl  Control to insert into the group.

	 */ 

    IMPORT_C void AppendL( CAlfControl* aControl );

    /**

     * Removes a control from the control group.

     *

     * @param aControl  Control to remove from the group. The control's

     *                  ownership is transferred to the caller. Note that

     *                  controls should never be used unless they are

     *                  owned by a control group.

     *

     * @return  KErrNone, if successful. KErrNotFound, if the control is not

     *          in the group.

     */

    IMPORT_C TInt Remove(CAlfControl* aControl);

    /**

	 * Determines whether the group accepts input events.

	 *

	 * @return ETrue is accepts input.

	 */

    IMPORT_C TBool AcceptInput() const;

    /**

     * Sets the input event acceptance of the group.

     *

     * @param aAcceptInput  Accept input events.

     */

    IMPORT_C void SetAcceptInput( TBool aAcceptInput );

    /**

     * Finds control

     * @see CAlfEnv::FindControl()

     * @return  Pointer to the control, or <code>NULL</code> if the control

     *          is not in the group.

     */

    IMPORT_C CAlfControl* FindControl( TInt aId,  TBool aUserId = ETrue ) const;

    /**

     * Returns the number of controls within this group.

     * 

     * @return Number of controls.

     */

    IMPORT_C TInt Count() const;

    /**

     * Access a control within the group, by its index into the

     * internal list of controls. Will panic if an out-of-bounds

     * index is passed.

     * 

     * @param aIndex  Index of the control to return.

     * 

     * @return Reference to the requested control. Always

     *         returns a valid control.

     */

    IMPORT_C CAlfControl& Control( TInt aIndex ) const;

    /**

     * Enables or disables transformation of the control group.

     *

     * @param aIsTransformed ETrue for enabling.

     */

    IMPORT_C void EnableTransformationL( TBool aIsTransformed = ETrue );

    /**

     * Determines if the control group has a transformation.

     *

     * @return ETrue is transformation is enabled.

     */

    IMPORT_C TBool IsTransformed() const;

    /**

     * Returns the transformation of the control group.

     *

     * @return  Transformation steps.

     */

    IMPORT_C CAlfTransformation& Transformation();

private:

    // Private data. Owned.

    struct TPrivateData;

    TPrivateData* iData;

    };

#endif // C_ALFCONTROLGROUP_H