1 /*

     2 * Copyright (c) 2006-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:   Layout base class

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_ALFGRIDLAYOUT_H

    21 #define C_ALFGRIDLAYOUT_H

    22 

    23 #include <alf/alflayout.h>

    24 

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

    26 enum TAlfGridDimension 

    27     {

    28     EAlfGridColumn,

    29     EAlfGridRow

    30     };

    31 

    32 /**

    33  * These flags specify where pixel error is distributed in grid layout calculations.

    34  * 

    35  * If none of these flags are set, then the pixel positions of all children are calculated

    36  * using reals, then floored to the nearest pixel. If, however, the children must all be

    37  * the same pixel size, then the following flags can be set. They place extra pixels into

    38  * the layout's paddings to make up the difference.

    39  * The flags for increasing and decreasing paddings are

    40  * mutually exclusive, but you can apply inner and outer padding flags at the same time. This

    41  * will result in the error being distributed between inner and outer paddings in the same

    42  * proportion as inner to outer padding. Eg: if inner padding is 10 and outer padding is 20, twice

    43  * as many error pixels will be distributed to the outer padding.

    44  * @see SetLayoutModeFlags

    45  */

    46 enum TAlfGridLayoutModeFlags

    47     {

    48     /** Automatically increases innerpaddings if needed. Clears EAlfGridDecreaseInnerPadding if set.*/

    49     EAlfGridIncreaseInnerPadding = 0x1,

    50  

    51     /** Automatically decreases innerpaddings if needed. Clears EAlfGridIncreaseInnerPadding if set.*/

    52     EAlfGridDecreaseInnerPadding = 0x2,

    53     

    54     /** Automatically increases outerpaddings if needed. Clears EAlfGridDecreaseOuterPadding if set.*/    

    55     EAlfGridIncreaseOuterPadding = 0x4,

    56 

    57     /** Automatically decreases outerpaddings if needed. Clears EAlfGridIncreaseOuterPadding if set.*/    

    58     EAlfGridDecreaseOuterPadding = 0x8,

    59     

    60     EAlfGridFlagAll = 0xF

    61     };

    62 

    63 /**

    64  * Grid layout class.

    65  *

    66  * To use this class, a grid layout is created of a desired width and height.

    67  * Then, when visuals are added to grid layout, they will populate the grid.

    68  * By default, all slots in a grid layout are of a uniform size, but the weighting

    69  * of individual rows and columns can be modified, and can be specified using

    70  * metric units.

    71  * Slots will resize automatically as the grid layout size changes.

    72  *

    73  * The standard application grid is one example of a grid layout.

    74  * 

    75  * Usage:

    76  *

    77  * @code

    78  * // Create a new 3x4 grid layout visual.

    79  * CAlfGridLayout* grid = CAlfGridLayout::AddNewL( control, 3, 4 );

    80  * 

    81  * // Add a single text visual into the grid.

    82  * CAlfTextVisual* text = CAlfTextVisual::AddNewL( control, grid );

    83  * 

    84  * // Make the text visual visible; if no text is specified, nothing is drawn.

    85  * text->SetTextL(_L("T"));

    86  * 

    87  * //Setting grid dimentions with weight

    88  * RArry<TInt> col;

    89  * col.AppendL( 1 );

    90  * col.AppendL( 2 );

    91  * 

    92  * //sets no of columns to 2 and width of second column

    93  * //is double of that of first

    94  * grid->SetColumns( col );

    95  * 

    96  * @endcode

    97  * @lib alfclient.lib

    98  * @since S60 v3.2

    99  */

   100 class CAlfGridLayout : public CAlfLayout

   101     {

   102 public:

   103 

   104 	/* Constructors and destructor. */

   105 

   106     /**

   107      * Construct a new grid layout and give its ownership to a control.

   108      *

   109      * @note the columns and rows will be initialized with equal unit weights, so that blocks will all share 

   110      * even proportions of the available area to start with.

   111      * @note in order to use a mixture of metric weights, or to set different weights, set rows 

   112      * and columns to zero when calling this method, then use e.g. @c AppendWeightL to 

   113      * subsequently populate the weights.

   114      * 

   115      * @param aOwnerControl  Owner control.

   116      * @param aColumns       Number of columns in the grid.

   117      * @param aRows          Number of rows in the grid.

   118      * @param aParentLayout  Parent layout for the new grid layout.

   119      */

   120     IMPORT_C static CAlfGridLayout* AddNewL(CAlfControl& aOwnerControl, 

   121                                             TInt aColumns, TInt aRows,

   122                                             CAlfLayout* aParentLayout = 0);

   123 

   124 	/**

   125 	 * Constructor.

   126 	 */

   127 	IMPORT_C CAlfGridLayout();

   128 

   129 	/**

   130 	 * From CAlfLayout. Second-phase constructor.

   131 	 */

   132 	IMPORT_C void ConstructL(CAlfControl& aOwner);

   133 

   134 	/**

   135 	 * Virtual destructor.

   136 	 */

   137 	IMPORT_C ~CAlfGridLayout();

   138 

   139 

   140 	/* Methods. */    

   141 

   142     /**

   143      * Sets amount of columns.

   144      *

   145      * @param aColumnCount Amount of columns.

   146      */

   147     IMPORT_C void SetColumnsL(TInt aColumnCount);

   148     

   149     /**

   150      * Sets amount of rows.

   151      *

   152      * @param aRowCount Amount of rows.

   153      */

   154     IMPORT_C void SetRowsL(TInt aRowCount);

   155     

   156     /**

   157      * Sets the number and weights of columns in this grid layout.

   158      * The caller specifies an array of relative weights to use for each

   159      * column.

   160      * Weights can be any integer, ie a column of weight 30 would

   161      * be twice the width of a column of weight 15.

   162      *

   163      * @note this is equivalent to using metrics with unit type EAlfUnitWeight.

   164      *

   165      * @param aWeights An array containing weights for each column.

   166      */    

   167     IMPORT_C void SetColumnsL(const RArray<TInt>& aWeights);

   168     

   169     /**

   170      * Sets the number and weights of rows in this grid layout.

   171      * The caller specifies an array of relative weights to use for each

   172      * row.

   173      * Weights can be any integer, ie a row of weight 30 would

   174      * be twice the height of a row of weight 15.

   175      *

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

   177      *

   178      * @param aWeights An array containing weights for each row.

   179      */    

   180     IMPORT_C void SetRowsL(const RArray<TInt>& aWeights);

   181 

   182     /**

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

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

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

   186      *

   187      * @since S60 3.2

   188      *

   189      * @see @c AppendWeightL for more information on how weights are used to calculate layout positions.

   190      *

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

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

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

   194      * of the specified dimension.

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

   196      *

   197      * @param aDim the dimension along which to fill

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

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

   200      */    

   201     IMPORT_C void FillWeightsL(TAlfGridDimension aDim, TInt aCount, const TAlfMetric& aWeight);

   202 

   203     /**

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

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

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

   207      * to represent weight values in aribtrary proportional units.

   208      *

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

   210      * resize according to the new total weight.

   211      *

   212      * @since S60 3.2

   213      *

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

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

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

   217      *      be better to use EAlfUnitWeight

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

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

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

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

   222      *

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

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

   225      *          replacing any previously existing weight for that block

   226      */

   227     IMPORT_C void AppendWeightL(TAlfGridDimension aDim, const TAlfMetric& aWeight);

   228 

   229     /**

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

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

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

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

   234      * the grid according to how the blocks wrap.

   235      *

   236      * @since S60 3.2

   237      *

   238      * @see @c AppendWeightL for more information on how weights are used to calculate layout positions.

   239      *

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

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

   242      *          replacing any previously existing weight for that block

   243      * @param aPos the index of the block

   244      */

   245     IMPORT_C void InsertWeightL(TAlfGridDimension aDim, const TAlfMetric& aWeight, TInt aPos);

   246 

   247     /**

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

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

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

   251      *

   252      * @since S60 3.2

   253      *

   254      * @see @c AppendWeightL for more information on how weights are used to calculate layout positions.

   255      *

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

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

   258      *          replacing any previously existing weight for that cell

   259      * @param aPos the index of the cell

   260      */

   261     IMPORT_C void ReplaceWeightL(TAlfGridDimension aDim, const TAlfMetric& aWeight, TInt aPos);

   262 

   263     /**

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

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

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

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

   268      * the blocks wrap.

   269      *

   270      * @since S60 3.2

   271      *

   272      * @see @c AppendWeightL for more information on how weights are used to calculate layout positions.

   273      *

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

   275      * @param aPos the index of the cell

   276      */

   277     IMPORT_C void RemoveWeightL(TAlfGridDimension aDim, TInt aPos);

   278 

   279     /**

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

   281      * specified dimension. 

   282      *

   283      * @since S60 3.2

   284      *

   285      * @see @c AppendWeightL for more information on how weights are used to calculate layout positions.

   286      *

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

   288      * @param aPos the index of the cell

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

   290      */

   291     IMPORT_C TAlfMetric Weight(TAlfGridDimension aDim, TInt aPos) const;

   292     

   293     /**

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

   295      *

   296      * @since S60 3.2

   297      *

   298      * @param aDim the dimension along which to count

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

   300      */        

   301     IMPORT_C TInt DimensionCount(TAlfGridDimension aDim) const;

   302     

   303         

   304     /**

   305      * ! Deprecated, use leaving method instead

   306      */

   307     void SetColumns(TInt aColumnCount)

   308         {

   309         TRAP_IGNORE(SetColumnsL(aColumnCount))

   310         }

   311     

   312     /**

   313      * ! Deprecated, use leaving method instead

   314      */

   315     void SetRows(TInt aRowCount)

   316         {

   317         TRAP_IGNORE(SetRowsL(aRowCount))

   318         }

   319     

   320     /**

   321      * ! Deprecated, use leaving method instead

   322      */

   323     void SetColumns(const RArray<TInt>& aWeights)

   324         {

   325         TRAP_IGNORE(SetColumnsL(aWeights))

   326         }

   327     

   328     /**

   329      * ! Deprecated, use leaving method instead

   330      */

   331     void SetRows(const RArray<TInt>& aWeights)

   332         {

   333         TRAP_IGNORE(SetRowsL(aWeights))

   334         }

   335     

   336     /**

   337      * Sets flags to control expanding behaviour.

   338      *

   339      * @param aFlags Flags

   340      */

   341     IMPORT_C void SetExpanding(TInt aFlags);

   342         

   343     /**

   344      * Gets amount of rows.

   345      *

   346      * @return Amount of rows.

   347      */

   348     IMPORT_C TInt RowCount() const;

   349         

   350     /**

   351      * Gets amount of columns.

   352      *

   353      * @return Amount of columns.

   354      */

   355     IMPORT_C TInt ColumnCount() const;

   356 

   357     /**

   358      * Calculates the position of a child in the grid. Returns the block

   359      * position, where block (0, 0) is in the top left corner.

   360      *

   361      * @param aOrdinal  Ordinal of a child.

   362      *

   363      * @return  Block position of the child.

   364      */    

   365     IMPORT_C TPoint OrdinalToBlock(TInt aOrdinal) const;

   366     

   367     /**

   368      * Sets flag(s) which alter the children's pixel error distribution within the grid layout.

   369      *

   370      * This method allows the client to force all items in the grid layout to be the same

   371      * pixel size. The floating point error that this introduces is distributed between the various

   372      * paddings of the layout.

   373      * 

   374      * Example of use that allows outer paddings to be automatically adjusted:

   375      * \code

   376      * iGridLayout->SetLayoutModeFlags(EHuiGridRow, EHuiGridAdjustOuterPadding); 

   377      * \endcode

   378      *

   379      * Note that some flags are mutually exclusive, and will clear some existing flags if set.

   380      *

   381      * @param aDim the dimension to which the given flag(s) affect.

   382      * @param aGridLayoutModeFlags Flags to be set or cleared

   383      * @see TAlfGridLayoutModeFlags, ClearLayoutModeFlags

   384      */        

   385     IMPORT_C void SetLayoutModeFlags(TAlfGridDimension aDim, TUint aGridLayoutModeFlags);

   386 

   387     /**

   388      * Clears flag(s) which alter the children's pixel error distribution within the grid layout.

   389      *

   390      * @param aDim the dimension to which the given flag(s) affect.

   391      * @param aGridLayoutModeFlags Flags to be cleared

   392      * @see TAlfGridLayoutModeFlags, SetLayoutModeFlags

   393      */        

   394     IMPORT_C void ClearLayoutModeFlags(TAlfGridDimension aDim, TUint aGridLayoutModeFlags);    

   395     

   396     /**

   397      * Return flag(s) which alter the children's pixel error distribution within the grid layout.

   398      *

   399      * @param aDim the dimension to return the flags for.

   400      */

   401     IMPORT_C TInt LayoutModeFlags(TAlfGridDimension aDim);

   402     

   403     /**

   404      * From CAlfVisual

   405      * @see CAlfVisual

   406      */

   407     IMPORT_C void RemoveAndDestroyAllD();

   408     IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);

   409     IMPORT_C CAlfVisual* FindTag(const TDesC8& aTag);

   410     

   411     /**

   412      * From CAlfLayout

   413      * @see CAlfLayout

   414      */

   415     IMPORT_C TAlfXYMetric BaseUnit() const;

   416 

   417 protected:

   418     /**

   419      * From CAlfVisual

   420      * @see CAlfVisual

   421      */

   422     IMPORT_C void DoRemoveAndDestroyAllD();

   423     IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   424           

   425 private:

   426     

   427     // Private structure. Owned.

   428     struct TGridLayoutPrivateData;

   429     TGridLayoutPrivateData* iGridLayoutData;

   430 

   431     };

   432 

   433 

   434 #endif // C_ALFGRIDLAYOUT_H