/*
* 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 I_ALFLAYOUTMANAGER
#define I_ALFLAYOUTMANAGER

#include <alf/ialfinterfacebase.h>
#include <alf/alftypes.h>

class CAlfLayout;
class CAlfControl;

namespace duiuimodel
    {
class DuiNode;
    }
using namespace duiuimodel;

namespace Alf
    {

class CAlfWidgetControl;
class AlfCustomInitDataBase;

namespace ialflayoutmanager
    {
     static const IfId Ident =
        {
        0, "ialflayoutmanager"
        };
    } 

/**
 * 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
 */
class IAlfLayoutManager : public IAlfInterfaceBase
    {
public:
       
    static inline const IfId& type()
        {       
        return ialflayoutmanager::Ident;
        }
        
    virtual inline ~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.
     * @throw AlfVisualException(EInvalidArrayIndex), if aLayoutIndex is out of bounds
     *        AlfVisualException(ECanNotCreateVisual), if the layout creation failed.
     */    
    virtual void createLayout(CAlfWidgetControl& aOwner, 
        CAlfLayout* aParentLayout, int aLayoutIndex) = 0;
    
    /**
     * Returns the layout used by this layoutmanager.
     *
     * @return layout used by this layoutmanager.
     * @throw AlfVisualException(EInvalidVisual), if layout is not created.
     */
    virtual CAlfLayout& getLayout()const  = 0;
    
    /**
     * Notifies the layout manager, that the child control's layout
     * must be updated
     * 
     * @param aControl control, which size has changed.
     * @throw AlfVisualException(EInvalidVisual), if layout is not created.
     */    
    virtual void updateChildLayout(CAlfWidgetControl* aControl) = 0;
    
    /**
     * Notifies the layout manager, that all the child control's layouts
     * must be updated.
     * @throw AlfVisualException(EInvalidVisual), if layout is not created.
     */    
    virtual void updateChildrenLayout() = 0;
    
    /**
     * Notifies the layout manager, that the control's has been
     * removed from the layout.
     * 
     * @param aControl control, which has been removed from the layout.
     * @throw AlfVisualException(EInvalidVisual), if layout is not created.
     */    
    virtual void childRemoved(CAlfWidgetControl* aControl) = 0;
    
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.
     */    
    virtual IAlfInterfaceBase* makeInterface( const IfId& aType ) = 0;
    };
    
/**
 * Placeholder for information required to instantiate an layoutmanager
 * via the widget factory mechanism.
 * A pointer to this structure is casted to a void pointer and sent to the
 * factory plugin.
 * @lib alfwidgetmodel.lib
 * @since S60 ?S60_version
 */
struct AlfLayoutManagerInitData
    {
    /**
     * Event handler instance ID.This uniquely identifies every event handler instance.
     */
    char* mLayoutManagerId;
    
    /**
     * Pointer to node in declaration containing information for the widget.
     */
    DuiNode* mNode;

    /**
     * Pointer to custom data passed via factory mechanism
     * Not Owned.
     */
    AlfCustomInitDataBase* mCustomData;
    };


    } // namespace Alf

#endif // I_ALFLAYOUTMANAGER