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:   Definition for CHuiGridLayout. Grid layouts allow specifying 

    15 *                the placement of child visuals within a fixed grid.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef __HUIGRIDLAYOUT_H__

    22 #define __HUIGRIDLAYOUT_H__

    23 

    24 

    25 #include <e32base.h>

    26 #include <uiacceltk/HuiLayout.h>

    27 

    28 

    29 /* Forward declarations */

    30 class CHuiEnv;

    31 class THuiMetric;

    32 

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

    34 enum THuiGridDimension

    35     {

    36     EHuiGridColumn = 0,

    37     EHuiGridRow,

    38     

    39     EHuiGridSize

    40     };

    41 

    42 /**

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

    44  * 

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

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

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

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

    49  * The flags for increasing and decreasing paddings are

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

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

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

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

    54  *

    55  * @see SetLayoutModeFlags

    56  */

    57 enum THuiGridLayoutModeFlags

    58     {

    59     /** Automatically increases innerpaddings if needed */

    60     EHuiGridIncreaseInnerPadding = 0x1,  // default

    61  

    62     /** Automatically decreases innerpaddings if needed */

    63     EHuiGridDecreaseInnerPadding = 0x2, // default  

    64     

    65     /** Automatically increases outerpaddings if needed */    

    66     EHuiGridIncreaseOuterPadding = 0x4,  // default

    67 

    68     /** Automatically decreases outerpaddings if needed */    

    69     EHuiGridDecreaseOuterPadding = 0x8,  // default

    70     };

    71     

    72 /**

    73  * CHuiGridLayout is a layout that allows visuals to be positioned within a 

    74  * grid.

    75  *

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

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

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

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

    80  * metric units.

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

    82  *

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

    84  * 

    85  */

    86 class CHuiGridLayout : public CHuiLayout

    87     	{

    88 public:

    89 

    90     /* Constructors and destructor. */

    91 

    92     /**

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

    94      *

    95      * @note Default expansion direction is vertical. See SetExpanding() to

    96      * changed the direction.

    97      * @note the columns and rows will be initialized with unit weights equal to 1, so that blocks 

    98      * will all share even proportions of the available area to start with.

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

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

   101      * subsequently populate the weights.

   102      * 

   103      * @param aOwnerControl  Owner control.

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

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

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

   107      */

   108     IMPORT_C static CHuiGridLayout* AddNewL(CHuiControl& aOwnerControl, 

   109                                             TInt aColumns, TInt aRows,

   110                                             CHuiLayout* aParentLayout = 0);

   111 

   112     IMPORT_C CHuiGridLayout(MHuiVisualOwner& aOwner);

   113 

   114     /** From CHuiLayout, deriving class must implement base call */

   115     IMPORT_C void ConstructL();

   116     IMPORT_C ~CHuiGridLayout();

   117 

   118     /* Methods inherited from CHuiLayout. */

   119     IMPORT_C void SetSize(const THuiRealSize& aSize, TInt aTransitionTime=0);

   120     IMPORT_C TInt ChildOrdinal(TInt aIndex);

   121     IMPORT_C TBool ChildPos(TInt aOrdinal, TPoint& aPos);

   122     IMPORT_C TBool ChildSize(TInt aOrdinal, TSize& aSize);

   123     IMPORT_C TInt ChildRect(TInt aOrdinal, THuiRealRect& aRect);

   124     IMPORT_C THuiXYMetric BaseUnit() const;

   125     IMPORT_C void RemoveAndDestroyAllD();

   126     IMPORT_C CHuiVisual* FindTag(const TDesC8& aTag);

   127     IMPORT_C TInt Count() const;

   128     IMPORT_C CHuiVisual& Visual(TInt aIndex) const;

   129     IMPORT_C void SetPos(const THuiRealPoint& aPos, TInt aTransitionTime = 0);

   130     IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);

   131     IMPORT_C TBool PrepareDrawL();

   132     IMPORT_C void Draw(CHuiGc& aGc) const;

   133     IMPORT_C void DrawSelf(CHuiGc& aGc, const TRect& aDisplayRect) const;

   134     IMPORT_C TBool Changed() const;

   135     IMPORT_C void ReportChanged();

   136     IMPORT_C void ClearChanged();

   137     IMPORT_C void NotifySkinChangedL();

   138     IMPORT_C void ExpandRectWithContent(TRect& aRect) const;

   139     IMPORT_C void VisualExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   140    

   141 public: // new methods   

   142         

   143     /**

   144      * Sets the number of columns in this grid layout.

   145      * All weights are set to 1 (ie. each column is of an equal

   146      * width).

   147      *

   148      * @param aColumnCount The number of columns.

   149      */

   150     IMPORT_C void SetColumnsL(TInt aColumnCount);

   151     

   152     /**

   153      * Sets the number of rows in this grid layout.

   154      * All weights are set to 1 (ie. each column is of an equal

   155      * height).     

   156      *

   157      * @param aRowCount The number of rows.

   158      */    

   159     IMPORT_C void SetRowsL(TInt aRowCount);

   160     

   161     /**

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

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

   164      * column.

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

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

   167      *

   168      * @note this is equivalent to using metrics with unit type EHuiUnitWeight.

   169      *

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

   171      */    

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

   173     

   174     /**

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

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

   177      * row.

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

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

   180      *

   181      * @note this is the same as using metrics with unit type EHuiUnitWeight.

   182      *

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

   184      */    

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

   186 

   187         

   188     /**

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

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

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

   192      *

   193      * @since S60 3.2

   194      *

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

   196      *

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

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

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

   200      * of the specified dimension.

   201      * @note this is the same as using metrics with unit type EHuiUnitWeight.

   202      *

   203      * @param aDim the dimension along which to fill

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

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

   206      */    

   207     IMPORT_C void FillWeightsL(THuiGridDimension aDim, TInt aCount, const THuiMetric& aWeight);

   208 

   209     /**

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

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

   212      * hence different units can be used for each block. In particular, EHuiUnitWeight can be used 

   213      * to represent weight values in aribtrary proportional units.

   214      *

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

   216      * resize according to the new total weight.

   217      *

   218      * @since S60 3.2

   219      *

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

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

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

   223      *      be better to use EHuiUnitWeight

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

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

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

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

   228      *

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

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

   231      *          replacing any previously existing weight for that block

   232      */

   233     IMPORT_C void AppendWeightL(THuiGridDimension aDim, const THuiMetric& aWeight);

   234 

   235     /**

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

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

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

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

   240      * the grid according to how the blocks wrap.

   241      *

   242      * @since S60 3.2

   243      *

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

   245      * so check first by calling @c Count

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

   247      *

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

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

   250      *          replacing any previously existing weight for that block

   251      * @param aPos the index of the block

   252      */

   253     IMPORT_C void InsertWeightL(THuiGridDimension aDim, const THuiMetric& aWeight, TInt aPos);

   254     /**

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

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

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

   258      *

   259      * @since S60 3.2

   260      *

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

   262      *

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

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

   265      *          replacing any previously existing weight for that cell

   266      * @param aPos the index of the cell

   267      */

   268     IMPORT_C void ReplaceWeightL(THuiGridDimension aDim, const THuiMetric& aWeight, TInt aPos);

   269 

   270     /**

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

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

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

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

   275      * the blocks wrap.

   276      *

   277      * @since S60 3.2

   278      *

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

   280      *

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

   282      * @param aPos the index of the cell

   283      */

   284     IMPORT_C void RemoveWeightL(THuiGridDimension aDim, TInt aPos);

   285 

   286     /**

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

   288      * specified dimension. 

   289      *

   290      * @since S60 3.2

   291      *

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

   293      *

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

   295      * @param aPos the index of the cell

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

   297      */

   298     IMPORT_C THuiMetric Weight(THuiGridDimension aDim, TInt aPos) const;

   299         

   300     /**

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

   302      *

   303      * @since S60 3.2

   304      *

   305      * @param aDim the dimension along which to count

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

   307      */        

   308     IMPORT_C TInt DimensionCount(THuiGridDimension aDim) const;

   309     

   310     /**

   311      * Sets the expansion flags to the given bitfield, made up of

   312      * bits from CHuiLayout::TExpansionFlags.

   313       *

   314      * With EExpandVertically, the filling starts from 

   315      * top left corner (right if mirrored) and a row is filled 

   316      * full before moving to the next row. If there are more items

   317      * than rows*colums, they are layouted accordingly below the grid

   318      * content area.

   319      * 

   320      * With EExpandHorizontally, the filling starts from 

   321      * top left corner (right if mirrored) and a column is filled 

   322      * full before moving to the next column. If there are more items

   323      * than rows*colums, they are layouted accordingly on the right

   324      * side (left if mirrored) of the content area of the grid.

   325      *

   326      * @param aFlags Determines the expansion direction.  

   327      *

   328      */

   329     IMPORT_C void SetExpanding(TInt aFlags);

   330     

   331     /**

   332      * Return the number of rows in this grid.

   333      *

   334      * @return The number of rows in this grid.

   335      */

   336     IMPORT_C TInt RowCount() const;

   337 

   338     /**

   339      * Return the number of columns in this grid.

   340      *

   341      * @return The number of columns in this grid.

   342      */        

   343     IMPORT_C TInt ColumnCount() const;

   344 

   345     /**

   346      * Calculates the (x,y) position of a child in the grid. Returns the block

   347      * position, where block (0, 0) is in the top left corner (top right corner

   348      * when the layout is mirrored).

   349      *

   350      * @param aOrdinal  Ordinal of a child.

   351      *

   352      * @return  Block position of the child.

   353      */    

   354     IMPORT_C TPoint OrdinalToBlock(TInt aOrdinal) const;

   355 

   356     /**

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

   358      *

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

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

   361      * paddings of the layout.

   362      * 

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

   364      * \code

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

   366      * \endcode

   367      *

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

   369      *

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

   371      * @param aGridLayoutModeFlags Flags to be set or cleared

   372      * @see TAlfGridLayoutModeFlags, ClearLayoutModeFlags

   373      */          

   374     IMPORT_C void SetLayoutModeFlags(THuiGridDimension aDim, TUint aGridLayoutModeFlags);

   375 

   376     /**

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

   378      *

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

   380      * @param aGridLayoutModeFlags Flags to be cleared

   381      * @see TAlfGridLayoutModeFlags, SetLayoutModeFlags

   382      */                

   383     IMPORT_C void ClearLayoutModeFlags(THuiGridDimension aDim, TUint aGridLayoutModeFlags);    

   384     

   385     /**

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

   387      *

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

   389      */

   390     IMPORT_C TUint LayoutModeFlags(THuiGridDimension aDim);

   391     

   392 public: // RnD utilities

   393 

   394     IMPORT_C void GetClassName(TDes& aName) const;

   395     IMPORT_C void DumpTree() const;

   396     IMPORT_C void GetInstanceName(TDes& aName) const;

   397     IMPORT_C TType Type() const;

   398     IMPORT_C TInt SessionId() const;

   399     IMPORT_C void SetSessionId(TInt aSessionId);

   400 

   401 

   402 private:

   403     

   404     /* Private methods */

   405     

   406     /**

   407      * Checks if the grid filling order is from top right corner instead 

   408      * the top left (default)

   409      * 

   410      * @return ETrue if the fillig is started from top right.

   411      */

   412     TBool UseRightToLeftFillingOrder() const;

   413 

   414     /**

   415      * Calculates the size and position along the specified axis according to the current weights. 

   416      * The non-weights are resolved into pixels and the remainder after subtracting from InnerSize 

   417      * is shared between the other cells that are specified using weight metrics.

   418      *

   419      * @note that this calculation assumes that the inner paddings have already been subtracted 

   420      * from the inner size, and that they will be added back in when calculating the actual 

   421      * position in base units.

   422      * @note when called repeatedly by UpdateChildrenLayout, all the cells will be calculated for 

   423      * each time UpdateChildLayout is called.

   424      *

   425      * @param aDim the dimension along which to calculate

   426      * @param aIndex the block being calculated

   427      * @param aAvailablePixels the space available within the grid layout, after the paddings and 

   428      *      inner paddings have already been subtracted

   429      * @param aPos the resulting position in pixels of the block along the axis (replaces contents)

   430      * @param aSize the resulting size in pixels of the block along the axis (replaces contents)

   431      * @param aFloorPixelPos the total width assuming every item width is floored.

   432      * @param aCeilingPixelPos the total width assuming every item width is ceilinged.

   433      */

   434     void CalculateCellInPixelsReal(

   435         THuiGridDimension aDim, 

   436         TInt aIndex, 

   437         TReal32 aAvailablePixels, 

   438         TReal32& aPos, 

   439         TReal32& aSize,

   440         TInt& aFloorPixelPos,

   441         TInt& aCeilingPixelPos) const;

   442 

   443     /**

   444      * Calculates the size and position along the specified axis according to the current weights. 

   445      * The non-weights are resolved into pixels and the remainder after subtracting from InnerSize 

   446      * is shared between the other cells that are specified using weight metrics.

   447      * Returns integer pixel values, taking into account the TAlfGridLayoutModeFlags for error rounding.

   448      *

   449      * @param aDim the dimension along which to calculate

   450      * @param aIndex the block being calculated

   451      * @param aAvailablePixels the space available within the grid layout, after the paddings and 

   452      *      inner paddings have already been subtracted

   453      * @param aPos the resulting position in pixels of the block along the axis (replaces contents)

   454      * @param aSize the resulting size in pixels of the block along the axis (replaces contents)

   455      * @see CalculateCellInPixelsReal

   456      */

   457     void CalculateCellInPixels(

   458         THuiGridDimension aDim, 

   459         TInt aIndex, 

   460         TReal32 aAvailablePixels, 

   461         TInt& aPos, 

   462         TInt& aSize) const;

   463 

   464     /** 

   465      * Calculate inner/outer distribution of padding.

   466      * Interpolates between the previously calculated positions for

   467      * inner padding and outer padding of the child, according to the

   468      * proportion between inner and outer padding size.

   469      *

   470      * @param aDim the dimension along which to calculate

   471      * @param aInnerPadPos the calculated position if inner padding is applied

   472      * @param aOuterPadPos the calculated position if outer padding is applied

   473      */

   474     TReal32 CHuiGridLayout::ProportionalInnerOuterPadding(  

   475         THuiGridDimension aDim,

   476         TReal32 aInnerPadPos,

   477         TReal32 aOuterPadPos) const;

   478 

   479     /**

   480      * Retrieve the weight and pixel size from a metric.

   481      * Returns one or the other depending on what type the metric is.

   482      * Zeroes unused params.

   483      *

   484      * @param aDim the dimension along which to calculate     

   485      * @param aMetric The metric to examine

   486      * @param aWeight Contains weight from metric.

   487      * @param aPix Contains pixel size from metric.

   488      */

   489     void WeightFromMetric(THuiGridDimension aDim, THuiMetric& aMetric, TReal32& aWeight, TInt& aPix) const;

   490 

   491 private:

   492     // Private data structure. Owned.

   493     struct TGridLayoutPrivateData;

   494     TGridLayoutPrivateData* iGridLayoutData;

   495     

   496     TAny* iSpare;

   497     };

   498 	

   499 #endif  // __HUIGRIDLAYOUT_H__