/*

* Copyright (c) 2007 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:  interface for layout managers

*

*/

#ifndef ALFLAYOUTMANAGER

#define ALFLAYOUTMANAGER

#include <osn/osndefines.h>

#include <osn/osntypes.h>

#include <memory>

#include <alf/ialflayoutmanager.h>

#include <alf/alflayout.h>

using std::auto_ptr;

namespace Alf

    {

class IAlfWidgetControl;

class AlfLayoutManagerImpl;

class IAlfLayoutPreferences;

/**

 * @class AlfLayoutManager alflayoutmanager.h "alf/alflayoutmanager.h"

 * The interface for layout managers

 *

 * Layout manager handles the layouting of child widgets in the container widget.

 * It uses IAlfLayoutPreferences-interface (@see IAlfLayoutPreferences) 

 * of child widgets as a guide for laying out the widgets. The layoutmanager 

 * is set to the IAlfHostApi- interface (@see IAlfHostApi::setBaseLayout)

 * createLayout-method should be the first call after creating the layoutmanager.

 *

 * Layout manager may also provide information about the layout preferences of its

 * children. If this is supported the layout manager will combine the layout preferences

 * of its children taking into consideration the technique used to lay out the children

 * using the layout manager. This will provide information about the whole display area

 * occupied by the layout manager. For instance vertical flow layout manager will provide

 * preferred size area of its children by summing their heights and providing the maximum

 * width among the children.

 *

 * @code

 * // Create layout manager interface.

 * IAlfLayoutManager* layoutManager = IAlfInterfaceBase::makeInterface<IAlfLayoutManager>(control);

 *

 * // See if layout preferences is supported in the given layout manager.

 * IAlfLayoutPreferences* layoutPreferences = IAlfInterfaceBase::makeInterface<IAlfLayoutPreferences>(layoutManager);

 *

 * if(layoutPreferences != 0)

 *     {

 *     TAlfXYMetric preferredSize;

 *     // This will report the preferred size of the layout by combining together preferred sizes of its children.

 *     bool result = layoutPreferences->getPreferredSize(preferredSize);

 *     }

 * @endcode

 *

 * @lib alfwidgetmodel.lib

 * @since S60 ?S60_version

 * @status Draft

 * @interfaces IAlfLayoutManager, IAlfLayoutPreferences

 */

class AlfLayoutManager : public IAlfLayoutManager

    {

public:

    /**

     * layout manager constructor

     *

     * @param aLayoutType type of layout used by this manager.

     */

    OSN_IMPORT AlfLayoutManager(TAlfLayoutType aLayoutType);

    /**

     * virtual destructor

     */

    OSN_IMPORT virtual ~AlfLayoutManager();

public:

    /**

     * @return the owner control of the layoutmanager.

     */        

    OSN_IMPORT CAlfWidgetControl& owner() const;

    /**

     * returns the control at aIndex.

     *

     * @param aIndex index for the control.

     * @return control at aIndex

     */

    OSN_IMPORT CAlfWidgetControl* getControl(int aIndex) const;

    /**

     * returns the count of controls inside layoutmanager.

     *

     * @return count of controls inside layoutmanager

     */

    OSN_IMPORT int count() const;

public:

    //from IAlfLayoutManager

    /**

     * creates the layout used by this layoutmanager.

     *

     * @param aOwner, owner-control of the the created layout.

     * @param aParentLayout parent for the created layout

     * @param aLayoutIndex index, where created visual should be placed in the parent layout.

     * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if aLayoutIndex is out of bounds.     

     * @exception osncore::AlfVisualException Thrown with error code osncore::ECanNotCreateVisual if the layout creation failed.

     */    

    OSN_IMPORT virtual void createLayout(CAlfWidgetControl& aOwner,

        CAlfLayout* aParentLayout, int aLayoutIndex);

    /**

     * from IAlfLayoutManager

     * Returns the layout used by this layoutmanager.

     *

     * @return layout used by this layoutmanager.

     * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.

     */

    OSN_IMPORT virtual CAlfLayout& getLayout() const;

    /**

     * from IAlfLayoutManager

     * Notifies the layout manager, that the child control's layout

     * must be updated

     * 

     * @param aControl control, which size has changed.

     * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.

     *

     */

    OSN_IMPORT virtual void updateChildLayout(CAlfWidgetControl* aControl);

    /**

     * from IAlfLayoutManager

     * Notifies the layout manager, that all the child control's layouts

     * must be updated.

     * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.     

     */

    OSN_IMPORT virtual void updateChildrenLayout();

    /**

     * from IAlfLayoutManager

     * Notifies the layout manager, that the control's has been

     * removed from the layout.

     * 

     * @param aControl control, which has been removed from the layout.

     * @exception osncore::AlfVisualException Thrown with error code osncore::EInvalidVisual if layout is not created.     

     */    

    OSN_IMPORT virtual void childRemoved(CAlfWidgetControl* aControl);

protected:

    /**

     * Notifies the layout manager, that the child control's layout

     * must be updated. Called in updateChildLayout for the updated control

     * and in updateChildrenLayout for all the controls in the layout.

     * 

     * @param aControl control, which size has changed.    

     */

    OSN_IMPORT virtual void doUpdateChildLayout(CAlfWidgetControl* aControl);

    /**

     * returns the rect of the control.

     *

     * @param aControl, control, which size is queried.

     * @param aRect will receive the rect of aControl, if return value is true.

     * @return true, if control rect was fetched, false, if the control hasn't 

     * got a visualization.

     */    

    OSN_IMPORT bool controlRect(

        CAlfWidgetControl& aControl, TAlfRealRect& aRect);

    /**

     * sets the size and position to the control

     *

     * @param aControl, control, which size and position is being set.

     * @param aRect, rect for aControl

     */        

    OSN_IMPORT void setControlRect(

        CAlfWidgetControl& aControl, const TAlfRealRect &aRect);

    /**

     * sets the position to the control

     *

     * @param aControl, control, which position is being set.

     * @param aPos, position for aControl

     */

    OSN_IMPORT void setControlPosition(

        CAlfWidgetControl& aControl, const TAlfRealPoint& aPos);

    /**

     * sets the size to control

     *

     * @param aControl, control, which size is being set.

     * @param aSize, new size for aControl.

     */        

    OSN_IMPORT void setControlSize(

        CAlfWidgetControl& aControl, const TAlfRealPoint &aSize);

    /**

     * returns layout preferences for aControl

     *

     * @return layout preferences for aControl.

     */

    OSN_IMPORT const IAlfLayoutPreferences* getLayoutPreferences(

        CAlfWidgetControl* aControl) const;

public:

// from base class IAlfInterfaceBase

    /**

     * Interface getter. 

     * @see IAlfInterfaceBase::MakeInterface

     *

     * @since S60 ?S60_version

     * @param aType The type id of the queried interface.

     * @return The queried interface, or NULL if the interface is not

     *         supported or available.

     */    

    OSN_IMPORT virtual IAlfInterfaceBase* makeInterface( const IfId& aType );

private: // data

    auto_ptr<AlfLayoutManagerImpl> mData;

    };

    } // namespace Alf

#endif // ALFLAYOUTMANAGER