1 /*

     2 * Copyright (c) 2008 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:  interface for layout policy

    15 *

    16 */

    17 

    18 

    19 #ifndef I_ALFGRIDLAYOUTMANAGER

    20 #define I_ALFGRIDLAYOUTMANAGER

    21 

    22 #include <alf/ialfinterfacebase.h>

    23 #include <alf/alftypes.h>

    24 

    25 class CAlfLayout;

    26 class CAlfControl;

    27 

    28 namespace Alf

    29     {

    30 

    31 class CAlfWidgetControl;

    32 

    33 namespace ialfgridlayoutpolicy

    34     {

    35      static const IfId Ident =

    36         {

    37         0, "gridlayoutpolicy"

    38         };

    39     }

    40     

    41 using Alf::CAlfWidgetControl;

    42 

    43 

    44 

    45 /**

    46  * The interface for grid layout policy

    47  *

    48  * Provides grid specific layout APIs

    49  * 

    50  * @code

    51  * // Create layout manager interface.

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

    53  *

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

    55  * IAlfGridLayoutPolicy* layoutPolicy = IAlfInterfaceBase::makeInterface<IAlfGridLayoutPolicy>(layoutManager);

    56  *

    57  * if(layoutPreferences != 0)

    58  *     {

    59  *     int rows = layoutPolicy->dimensionCount(EAlfGridDimensionRow);

    60  *     }

    61  * @endcode

    62  *

    63  * @lib alfwidgetmodel.lib

    64  * @since S60 ?S60_version

    65  * @status Draft

    66  */

    67 class IAlfGridLayoutPolicy : public IAlfInterfaceBase

    68     {

    69 public:

    70        

    71     static inline const IfId& type()

    72         {       

    73         return ialfgridlayoutpolicy::Ident;

    74         }

    75         

    76     virtual inline ~IAlfGridLayoutPolicy() {}

    77     

    78 public:

    79     /* Each dimension corresponds to a different axis for the grid blocks */

    80     enum gridLayoutDimension

    81         {

    82         EGridDimensionColumn = 0,

    83         EGridDimensionRow

    84         };

    85 

    86 public:

    87     

    88     /**

    89      * Sets the number and weights of blocks in this grid layout in the direction of the specified

    90      * dimension. Each block's weight will be set to equal the supplied value, the result

    91      * of which is that all blocks will be equally spaced, whatever the units. 

    92      *

    93      * @see appendWeight; for more information on how weights are used to calculate layout positions.

    94      *

    95      * @note This API could be useful if then subsequent calls to @c replaceWeight are made to 

    96      * change specific values, depending on how many of the values are different. 

    97      * @note Calling this with aCount set to 0 will clear all of the existing weights in the direction

    98      * of the specified dimension.

    99      * @note this is the same as using metrics with unit type EAlfUnitWeight.

   100      *

   101      * @param aDim the dimension along which to fill

   102      * @param aCount The number of lines of blocks to fill

   103      * @param aWeight the weights to be used for all blocks

   104      * @throw AlfVisualException

   105      */    

   106     virtual void fillWeights(gridLayoutDimension aDim, int aCount, const TAlfMetric& aWeight) = 0;

   107 

   108     /**

   109      * Add a new line of blocks to this grid layout at the last position in the direction of the 

   110      * specified dimension. It will have the supplied weight. Weights can be any metric value, 

   111      * hence different units can be used for each block. In particular, EAlfUnitWeight can be used 

   112      * to represent weight values in aribtrary proportional units.

   113      *

   114      * In the case of proportional weights, the effect of this will be to cause the other blocks to 

   115      * resize according to the new total weight.

   116      *

   117      * @note If non-relative coordinates are specified (e.g., real pixels), the combined blocks might not 

   118      *      fill the entire layout area. However, weights will always stretch to fill all available space 

   119      *      after the fixed units have been determined. Therefore, depending on circumstances it may

   120      *      be better to use EAlfUnitWeight

   121      * @note For example [2 weights, 1 weight, 2 weights] in a layout of 100 pixels would result 

   122      *      in [40 pixels, 20 pixels, 40 pixels]. 

   123      * @note For example [10 pixels, 1 weight, 15 pixels] in a layout of 100 pixels would result 

   124      *      in [10 pixels, 75 pixels, 15 pixels]. 

   125      *

   126      * @param aDim the dimension to which the weight corresponds

   127      * @param aWeight the weight to be used for the block in the specified dimension, 

   128      *          replacing any previously existing weight for that block

   129      * @throw AlfVisualException

   130      */

   131     virtual void appendWeight(gridLayoutDimension aDim, const TAlfMetric& aWeight) = 0;

   132 

   133     /**

   134      * Add a new line of blocks to this grid layout at the specified position in the direciton of 

   135      * the specified dimension. It will have the supplied weight. In the case of proportional 

   136      * weights, the effect of this will be to cause the other blocks to resize according to the new 

   137      * total weight. It will also mean that many child visuals will now occupy different blocks within

   138      * the grid according to how the blocks wrap.

   139      *

   140      * @note will leave if the specified position is greater than the number of objects currently in the array, 

   141      * so check first by calling @c preferredDimensionCount

   142      * @see appendWeight for more information on how weights are used to calculate layout positions.

   143      *

   144      * @param aDim the dimension to which the weight corresponds

   145      * @param aWeight the weight to be used for the block in the specified dimension, 

   146      *          replacing any previously existing weight for that block

   147      * @param aPos the index of the block

   148      * @throw AlfVisualException

   149      */

   150     virtual void insertWeight(gridLayoutDimension aDim, const TAlfMetric& aWeight, int aPos) = 0;

   151     

   152     /**

   153      * Sets the weight of a specific line of blocks in this grid layout, in the direction of the supplied dimension.

   154      * In the case of proportional weights, the effect of this will be to cause the 

   155      * other blocks to resize according to the new total weight. 

   156      *

   157      * @see appendWeight for more information on how weights are used to calculate layout positions.

   158      *

   159      * @param aDim the dimension to which the weight corresponds

   160      * @param aWeight the weight to be used for the block in the specified dimension, 

   161      *          replacing any previously existing weight for that cell

   162      * @param aPos the index of the cell

   163      * @throw AlfVisualException

   164      */

   165     virtual void replaceWeight(gridLayoutDimension aDim, const TAlfMetric& aWeight, int aPos) = 0;

   166 

   167     /**

   168      * Remove a line of blocks from this grid layout at the specified position in the 

   169      * specified dimension. In the case of proportional weights, the effect of this will 

   170      * be to cause the other blocks to resize according to the new total weight. It will also mean 

   171      * that many child visuals will now occupy different blocks within the grid according to how 

   172      * the blocks wrap.

   173      *

   174      * @see appendWeight for more information on how weights are used to calculate layout positions.

   175      *

   176      * @param aDim the dimension to which the weight corresponds

   177      * @param aPos the index of the cell

   178      * @throw AlfVisualException

   179      */

   180     virtual void removeWeight(gridLayoutDimension aDim, int aPos) = 0;

   181 

   182     /**

   183      * Returns the weight of a specific line of blocks in this grid layout, in the

   184      * specified dimension. 

   185      *

   186      * @see appendWeight for more information on how weights are used to calculate layout positions.

   187      *

   188      * @param aDim the dimension to which the weight corresponds

   189      * @param aPos the index of the cell

   190      * @return the weight being used for the cell in the specified dimension, will be 0 magnitude if not set

   191      * @throw AlfVisualException

   192      */

   193     virtual TAlfMetric weight(gridLayoutDimension aDim, int aPos) const = 0;

   194         

   195     /**

   196      * Return the number of lines of blocks in this grid, along the specified dimension

   197      *

   198      * @param aDim the dimension along which to count

   199      * @return The number of lines of blocks in this grid.

   200      */        

   201     virtual int count(gridLayoutDimension aDim) const = 0;

   202     

   203 public:

   204 // from base class IAlfInterfaceBase

   205     

   206     /**

   207      * Interface getter. 

   208      * @see IAlfInterfaceBase::MakeInterface

   209      *

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

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

   212      *         supported or available.

   213      */    

   214     virtual IAlfInterfaceBase* makeInterface( const IfId& aType ) = 0;

   215     };

   216 

   217     } // namespace Alf

   218 

   219 #endif // I_ALFGRIDLAYOUTMANAGER