/*
* 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:  The interface for inquiring the layout preferences of a laid-out object
*
*/


#ifndef I_ALFLAYOUTPERENCES_H
#define I_ALFLAYOUTPERENCES_H

#include <alf/ialfinterfacebase.h>
#include <alf/alftypes.h>
#include <alf/alfmetric.h>
#include <osn/osntypes.h>

using namespace osncore;

namespace Alf
    {

class IAlfLayoutManager;

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

/**
 * The interface for finding the layout preferences for an Alf widget model 
 * presentation object.
 * 
 * This interface is called by layout managers (implementors of @c IAlfLayoutManager)
 * in order to find out information about their contained presentation objects.
 * 
 * It is implemented by presentation objects in order to report to the layout manager
 * what sizes objects prefer.
 * 
 * The layout manager is responsible for finding out layout preferences for all the
 * AlfElement instances in the next level down of containment - the "child" elements.
 * It calls @c makeInterface<IAlfLayoutPreferences> on these elements.
 * The layout manager uses its knowledge about how these child elements relate to 
 * each other geometrically to come up with a decision on how many child elements
 * can be shown, where they are to be positioned, and how big they should be.
 * @see IAlfLayoutManager
 * 
 * @c AlfElements that represent contained sets of visuals - those that take up 
 * space within the visual containment - should implement @c IAlfLayoutPreferences,
 * or defer its implementation to another presentation object which is capable 
 * of reporting layout preferences.
 *
 * The following units are allowed to be used in the returned parameter values:
 *  EAlfUnitPixel - pixels
 *  EAlfUnitDisplaySize - units relative to the display
 *  EAlfS60Unit - S60 layout specification units
 *
 * Other units do not make sense, since the metric is being passed
 * to a different layout context. Furthermore, the reason for this API
 * is for the implementing object to state its own, internal, preferences
 * without recourse to its containment. This implies the use of the more
 * absolute units.
 * 
 * The units used for the returned @c TAlfXYMetric objects are chosen independently 
 * by the implementations of each API. They do not have to be return the same units.
 *
 * @lib alfwidgetmodel.lib
 * @since S60 ?S60_version
 * @status Draft
 */
class IAlfLayoutPreferences : public IAlfInterfaceBase
    {
public:
    static inline const IfId& type()
        {
        return alflayoutpreferences::Ident;    
        }

    /**
     * Return the minimum desirable size of a presentation object.
     * 
     * Minimum size should mean the size at which the visual would start to become 
     * unreadable in the case of text, or too difficult to see with sufficient 
     * clarity in the case of graphics.
     * 
     * false is to be returned if the implementing presentation object does
     * not care how small it is made.
     *
     * @param aMinSize The minimum size that the object would like to be laid out to
     * @return false iff the object queried does not care about a minimum size
     */
    virtual bool getMinimumSize( TAlfXYMetric& aMinSize ) const = 0;

    /**
     * Return the maximum size desired by a presentation object.
     * 
     * There may often be no preference as to maximum size. The implementation
     * should then return false.
     * 
     * @param aMaxSize The maximum size that the object would like to be laid out to
     * @return false iff the object queried does not care about a maximum size
     */
    virtual bool getMaximumSize( TAlfXYMetric& aMaxSize ) const = 0;

    /**
     * Return the preferred size for a presentation object.
     * 
     * The preferred size is the optimum size of the object in the absence
     * of external factors.
     *
     * The value returned should greater than or equal in size to a value
     * returned by getMinimumSize()
     *
     * The value returned should less than or equal in size to a value
     * returned by getMaximumSize()
     *
     * @param aPreferredSize The size that the object would like to be laid out to
     * @return false iff the object queried does not have a preferred size
     */
    virtual bool getPreferredSize( TAlfXYMetric& aPreferredSize ) const = 0;
    
    /**
     * Set the preferred size into a presentation object.
     * 
     * The preferred size is being dictated by external code in this case.
     * This new value should over-ride any internal preferred size.
     *
     * Calling this API has several side-effects.  Subsequent calls to 
     * getPreferredSize should return @c true and return the new preferred
     * size.
     *
     * Subsequent calls to getMinimumSize must return either @c false, or return
     * @c true with a value less than or equal to the preferred size.
     *
     * Subsequent calls to getMaximumSize must return either @c false, or return
     * @c true with a value greater than or equal to the preferred size.
     *
     * @param aPreferredSize The new preferred size for the laid-out object
     */
    virtual void setPreferredSize( const TAlfXYMetric& aPreferredSize ) = 0;

    };

    } // namespace Alf
#endif // I_ALFLAYOUTPERENCES_H