1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  The interface for inquiring the layout preferences of a laid-out object

    15 *

    16 */

    17 

    18 

    19 #ifndef I_ALFLAYOUTPERENCES_H

    20 #define I_ALFLAYOUTPERENCES_H

    21 

    22 #include <alf/ialfinterfacebase.h>

    23 #include <alf/alftypes.h>

    24 #include <alf/alfmetric.h>

    25 #include <osn/osntypes.h>

    26 

    27 using namespace osncore;

    28 

    29 namespace Alf

    30     {

    31 

    32 class IAlfLayoutManager;

    33 

    34 namespace alflayoutpreferences

    35     {

    36      static const IfId Ident=

    37         {

    38         0,"alflayoutpreferences"

    39         };

    40     }

    41 

    42 /**

    43  * The interface for finding the layout preferences for an Alf widget model 

    44  * presentation object.

    45  * 

    46  * This interface is called by layout managers (implementors of @c IAlfLayoutManager)

    47  * in order to find out information about their contained presentation objects.

    48  * 

    49  * It is implemented by presentation objects in order to report to the layout manager

    50  * what sizes objects prefer.

    51  * 

    52  * The layout manager is responsible for finding out layout preferences for all the

    53  * AlfElement instances in the next level down of containment - the "child" elements.

    54  * It calls @c makeInterface<IAlfLayoutPreferences> on these elements.

    55  * The layout manager uses its knowledge about how these child elements relate to 

    56  * each other geometrically to come up with a decision on how many child elements

    57  * can be shown, where they are to be positioned, and how big they should be.

    58  * @see IAlfLayoutManager

    59  * 

    60  * @c AlfElements that represent contained sets of visuals - those that take up 

    61  * space within the visual containment - should implement @c IAlfLayoutPreferences,

    62  * or defer its implementation to another presentation object which is capable 

    63  * of reporting layout preferences.

    64  *

    65  * The following units are allowed to be used in the returned parameter values:

    66  *  EAlfUnitPixel - pixels

    67  *  EAlfUnitDisplaySize - units relative to the display

    68  *  EAlfS60Unit - S60 layout specification units

    69  *

    70  * Other units do not make sense, since the metric is being passed

    71  * to a different layout context. Furthermore, the reason for this API

    72  * is for the implementing object to state its own, internal, preferences

    73  * without recourse to its containment. This implies the use of the more

    74  * absolute units.

    75  * 

    76  * The units used for the returned @c TAlfXYMetric objects are chosen independently 

    77  * by the implementations of each API. They do not have to be return the same units.

    78  *

    79  * @lib alfwidgetmodel.lib

    80  * @since S60 ?S60_version

    81  * @status Draft

    82  */

    83 class IAlfLayoutPreferences : public IAlfInterfaceBase

    84     {

    85 public:

    86     static inline const IfId& type()

    87         {

    88         return alflayoutpreferences::Ident;    

    89         }

    90 

    91     /**

    92      * Return the minimum desirable size of a presentation object.

    93      * 

    94      * Minimum size should mean the size at which the visual would start to become 

    95      * unreadable in the case of text, or too difficult to see with sufficient 

    96      * clarity in the case of graphics.

    97      * 

    98      * false is to be returned if the implementing presentation object does

    99      * not care how small it is made.

   100      *

   101      * @param aMinSize The minimum size that the object would like to be laid out to

   102      * @return false iff the object queried does not care about a minimum size

   103      */

   104     virtual bool getMinimumSize( TAlfXYMetric& aMinSize ) const = 0;

   105 

   106     /**

   107      * Return the maximum size desired by a presentation object.

   108      * 

   109      * There may often be no preference as to maximum size. The implementation

   110      * should then return false.

   111      * 

   112      * @param aMaxSize The maximum size that the object would like to be laid out to

   113      * @return false iff the object queried does not care about a maximum size

   114      */

   115     virtual bool getMaximumSize( TAlfXYMetric& aMaxSize ) const = 0;

   116 

   117     /**

   118      * Return the preferred size for a presentation object.

   119      * 

   120      * The preferred size is the optimum size of the object in the absence

   121      * of external factors.

   122      *

   123      * The value returned should greater than or equal in size to a value

   124      * returned by getMinimumSize()

   125      *

   126      * The value returned should less than or equal in size to a value

   127      * returned by getMaximumSize()

   128      *

   129      * @param aPreferredSize The size that the object would like to be laid out to

   130      * @return false iff the object queried does not have a preferred size

   131      */

   132     virtual bool getPreferredSize( TAlfXYMetric& aPreferredSize ) const = 0;

   133     

   134     /**

   135      * Set the preferred size into a presentation object.

   136      * 

   137      * The preferred size is being dictated by external code in this case.

   138      * This new value should over-ride any internal preferred size.

   139      *

   140      * Calling this API has several side-effects.  Subsequent calls to 

   141      * getPreferredSize should return @c true and return the new preferred

   142      * size.

   143      *

   144      * Subsequent calls to getMinimumSize must return either @c false, or return

   145      * @c true with a value less than or equal to the preferred size.

   146      *

   147      * Subsequent calls to getMaximumSize must return either @c false, or return

   148      * @c true with a value greater than or equal to the preferred size.

   149      *

   150      * @param aPreferredSize The new preferred size for the laid-out object

   151      */

   152     virtual void setPreferredSize( const TAlfXYMetric& aPreferredSize ) = 0;

   153 

   154     };

   155 

   156     } // namespace Alf

   157 #endif // I_ALFLAYOUTPERENCES_H