diff -r 4ea6f81c838a -r 0e9bb658ef58 mmuifw_plat/alf_widgetmodel_api/inc/alf/ialflayoutpreferences.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmuifw_plat/alf_widgetmodel_api/inc/alf/ialflayoutpreferences.h Wed Sep 01 12:23:18 2010 +0100 @@ -0,0 +1,157 @@ +/* +* 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 +#include +#include +#include + +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 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