diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_core_toolkit_api/inc/uiacceltk/HuiGridLayout.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_core_toolkit_api/inc/uiacceltk/HuiGridLayout.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,499 @@ +/* +* Copyright (c) 2006-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: Definition for CHuiGridLayout. Grid layouts allow specifying +* the placement of child visuals within a fixed grid. +* +*/ + + + +#ifndef __HUIGRIDLAYOUT_H__ +#define __HUIGRIDLAYOUT_H__ + + +#include +#include + + +/* Forward declarations */ +class CHuiEnv; +class THuiMetric; + +/* Each dimension corresponds to a different axis for the grid blocks */ +enum THuiGridDimension + { + EHuiGridColumn = 0, + EHuiGridRow, + + EHuiGridSize + }; + +/** + * These flags specify where pixel error is distributed in grid layout calculations. + * + * If none of these flags are set, then the pixel positions of all children are calculated + * using reals, then floored to the nearest pixel. If, however, the children must all be + * the same pixel size, then the following flags can be set. They place extra pixels into + * the layout's paddings to make up the difference. + * The flags for increasing and decreasing paddings are + * mutually exclusive, but you can apply inner and outer padding flags at the same time. This + * will result in the error being distributed between inner and outer paddings in the same + * proportion as inner to outer padding. Eg: if inner padding is 10 and outer padding is 20, twice + * as many error pixels will be distributed to the outer padding. + * + * @see SetLayoutModeFlags + */ +enum THuiGridLayoutModeFlags + { + /** Automatically increases innerpaddings if needed */ + EHuiGridIncreaseInnerPadding = 0x1, // default + + /** Automatically decreases innerpaddings if needed */ + EHuiGridDecreaseInnerPadding = 0x2, // default + + /** Automatically increases outerpaddings if needed */ + EHuiGridIncreaseOuterPadding = 0x4, // default + + /** Automatically decreases outerpaddings if needed */ + EHuiGridDecreaseOuterPadding = 0x8, // default + }; + +/** + * CHuiGridLayout is a layout that allows visuals to be positioned within a + * grid. + * + * To use this class, a grid layout is created of a desired width and height. + * Then, when visuals are added to grid layout, they will populate the grid. + * By default, all slots in a grid layout are of a uniform size, but the weighting + * of individual rows and columns can be modified, and can be specified using + * metric units. + * Slots will resize automatically as the grid layout size changes. + * + * The standard application grid is one example of a grid layout. + * + */ +class CHuiGridLayout : public CHuiLayout + { +public: + + /* Constructors and destructor. */ + + /** + * Construct a new grid layout and give its ownership to a control. + * + * @note Default expansion direction is vertical. See SetExpanding() to + * changed the direction. + * @note the columns and rows will be initialized with unit weights equal to 1, so that blocks + * will all share even proportions of the available area to start with. + * @note in order to use a mixture of metric weights, or to set different weights, set rows + * and columns to zero when calling this method, then use e.g. @c AppendWeightL to + * subsequently populate the weights. + * + * @param aOwnerControl Owner control. + * @param aColumns Number of columns in the grid. + * @param aRows Number of rows in the grid. + * @param aParentLayout Parent layout for the new grid layout. + */ + IMPORT_C static CHuiGridLayout* AddNewL(CHuiControl& aOwnerControl, + TInt aColumns, TInt aRows, + CHuiLayout* aParentLayout = 0); + + IMPORT_C CHuiGridLayout(MHuiVisualOwner& aOwner); + + /** From CHuiLayout, deriving class must implement base call */ + IMPORT_C void ConstructL(); + IMPORT_C ~CHuiGridLayout(); + + /* Methods inherited from CHuiLayout. */ + IMPORT_C void SetSize(const THuiRealSize& aSize, TInt aTransitionTime=0); + IMPORT_C TInt ChildOrdinal(TInt aIndex); + IMPORT_C TBool ChildPos(TInt aOrdinal, TPoint& aPos); + IMPORT_C TBool ChildSize(TInt aOrdinal, TSize& aSize); + IMPORT_C TInt ChildRect(TInt aOrdinal, THuiRealRect& aRect); + IMPORT_C THuiXYMetric BaseUnit() const; + IMPORT_C void RemoveAndDestroyAllD(); + IMPORT_C CHuiVisual* FindTag(const TDesC8& aTag); + IMPORT_C TInt Count() const; + IMPORT_C CHuiVisual& Visual(TInt aIndex) const; + IMPORT_C void SetPos(const THuiRealPoint& aPos, TInt aTransitionTime = 0); + IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0); + IMPORT_C TBool PrepareDrawL(); + IMPORT_C void Draw(CHuiGc& aGc) const; + IMPORT_C void DrawSelf(CHuiGc& aGc, const TRect& aDisplayRect) const; + IMPORT_C TBool Changed() const; + IMPORT_C void ReportChanged(); + IMPORT_C void ClearChanged(); + IMPORT_C void NotifySkinChangedL(); + IMPORT_C void ExpandRectWithContent(TRect& aRect) const; + IMPORT_C void VisualExtension(const TUid& aExtensionUid, TAny** aExtensionParams); + +public: // new methods + + /** + * Sets the number of columns in this grid layout. + * All weights are set to 1 (ie. each column is of an equal + * width). + * + * @param aColumnCount The number of columns. + */ + IMPORT_C void SetColumnsL(TInt aColumnCount); + + /** + * Sets the number of rows in this grid layout. + * All weights are set to 1 (ie. each column is of an equal + * height). + * + * @param aRowCount The number of rows. + */ + IMPORT_C void SetRowsL(TInt aRowCount); + + /** + * Sets the number and weights of columns in this grid layout. + * The caller specifies an array of relative weights to use for each + * column. + * Weights can be any integer, ie a column of weight 30 would + * be twice the width of a column of weight 15. + * + * @note this is equivalent to using metrics with unit type EHuiUnitWeight. + * + * @param aWeights An array containing weights for each column. + */ + IMPORT_C void SetColumnsL(const RArray& aWeights); + + /** + * Sets the number and weights of rows in this grid layout. + * The caller specifies an array of relative weights to use for each + * row. + * Weights can be any integer, ie a row of weight 30 would + * be twice the height of a row of weight 15. + * + * @note this is the same as using metrics with unit type EHuiUnitWeight. + * + * @param aWeights An array containing weights for each row. + */ + IMPORT_C void SetRowsL(const RArray& aWeights); + + + /** + * Sets the number and weights of blocks in this grid layout in the direction of the specified + * dimension. Each block's weight will be set to equal the supplied value, the result + * of which is that all blocks will be equally spaced, whatever the units. + * + * @since S60 3.2 + * + * @see AppendWeightL for more information on how weights are used to calculate layout positions. + * + * @note This API could be useful if then subsequent calls to @c ReplaceWeightL are made to + * change specific values, depending on how many of the values are different. + * @note Calling this with aCount set to 0 will clear all of the existing weights in the direction + * of the specified dimension. + * @note this is the same as using metrics with unit type EHuiUnitWeight. + * + * @param aDim the dimension along which to fill + * @param aCount The number of lines of blocks to fill + * @param aWeight the weights to be used for all blocks + */ + IMPORT_C void FillWeightsL(THuiGridDimension aDim, TInt aCount, const THuiMetric& aWeight); + + /** + * Add a new line of blocks to this grid layout at the last position in the direction of the + * specified dimension. It will have the supplied weight. Weights can be any metric value, + * hence different units can be used for each block. In particular, EHuiUnitWeight can be used + * to represent weight values in aribtrary proportional units. + * + * In the case of proportional weights, the effect of this will be to cause the other blocks to + * resize according to the new total weight. + * + * @since S60 3.2 + * + * @note If non-relative coordinates are specified (e.g., real pixels), the combined blocks might not + * fill the entire layout area. However, weights will always stretch to fill all available space + * after the fixed units have been determined. Therefore, depending on circumstances it may + * be better to use EHuiUnitWeight + * @note For example [2 weights, 1 weight, 2 weights] in a layout of 100 pixels would result + * in [40 pixels, 20 pixels, 40 pixels]. + * @note For example [10 pixels, 1 weight, 15 pixels] in a layout of 100 pixels would result + * in [10 pixels, 75 pixels, 15 pixels]. + * + * @param aDim the dimension to which the weight corresponds + * @param aWeight the weight to be used for the block in the specified dimension, + * replacing any previously existing weight for that block + */ + IMPORT_C void AppendWeightL(THuiGridDimension aDim, const THuiMetric& aWeight); + + /** + * Add a new line of blocks to this grid layout at the specified position in the direciton of + * the specified dimension. It will have the supplied weight. In the case of proportional + * weights, the effect of this will be to cause the other blocks to resize according to the new + * total weight. It will also mean that many child visuals will now occupy different blocks within + * the grid according to how the blocks wrap. + * + * @since S60 3.2 + * + * @note will leave if the specified position is greater than the number of objects currently in the array, + * so check first by calling @c Count + * @see AppendWeightL for more information on how weights are used to calculate layout positions. + * + * @param aDim the dimension to which the weight corresponds + * @param aWeight the weight to be used for the block in the specified dimension, + * replacing any previously existing weight for that block + * @param aPos the index of the block + */ + IMPORT_C void InsertWeightL(THuiGridDimension aDim, const THuiMetric& aWeight, TInt aPos); + /** + * Sets the weight of a specific line of blocks in this grid layout, in the direction of the supplied dimension. + * In the case of proportional weights, the effect of this will be to cause the + * other blocks to resize according to the new total weight. + * + * @since S60 3.2 + * + * @see AppendWeightL for more information on how weights are used to calculate layout positions. + * + * @param aDim the dimension to which the weight corresponds + * @param aWeight the weight to be used for the block in the specified dimension, + * replacing any previously existing weight for that cell + * @param aPos the index of the cell + */ + IMPORT_C void ReplaceWeightL(THuiGridDimension aDim, const THuiMetric& aWeight, TInt aPos); + + /** + * Remove a line of blocks from this grid layout at the specified position in the + * specified dimension. In the case of proportional weights, the effect of this will + * be to cause the other blocks to resize according to the new total weight. It will also mean + * that many child visuals will now occupy different blocks within the grid according to how + * the blocks wrap. + * + * @since S60 3.2 + * + * @see AppendWeightL for more information on how weights are used to calculate layout positions. + * + * @param aDim the dimension to which the weight corresponds + * @param aPos the index of the cell + */ + IMPORT_C void RemoveWeightL(THuiGridDimension aDim, TInt aPos); + + /** + * Returns the weight of a specific line of blocks in this grid layout, in the + * specified dimension. + * + * @since S60 3.2 + * + * @see AppendWeightL for more information on how weights are used to calculate layout positions. + * + * @param aDim the dimension to which the weight corresponds + * @param aPos the index of the cell + * @return the weight being used for the cell in the specified dimension, will be 0 magnitude if not set + */ + IMPORT_C THuiMetric Weight(THuiGridDimension aDim, TInt aPos) const; + + /** + * Return the number of lines of blocks in this grid, along the specified dimension. + * + * @since S60 3.2 + * + * @param aDim the dimension along which to count + * @return The number of lines of blocks in this grid. + */ + IMPORT_C TInt DimensionCount(THuiGridDimension aDim) const; + + /** + * Sets the expansion flags to the given bitfield, made up of + * bits from CHuiLayout::TExpansionFlags. + * + * With EExpandVertically, the filling starts from + * top left corner (right if mirrored) and a row is filled + * full before moving to the next row. If there are more items + * than rows*colums, they are layouted accordingly below the grid + * content area. + * + * With EExpandHorizontally, the filling starts from + * top left corner (right if mirrored) and a column is filled + * full before moving to the next column. If there are more items + * than rows*colums, they are layouted accordingly on the right + * side (left if mirrored) of the content area of the grid. + * + * @param aFlags Determines the expansion direction. + * + */ + IMPORT_C void SetExpanding(TInt aFlags); + + /** + * Return the number of rows in this grid. + * + * @return The number of rows in this grid. + */ + IMPORT_C TInt RowCount() const; + + /** + * Return the number of columns in this grid. + * + * @return The number of columns in this grid. + */ + IMPORT_C TInt ColumnCount() const; + + /** + * Calculates the (x,y) position of a child in the grid. Returns the block + * position, where block (0, 0) is in the top left corner (top right corner + * when the layout is mirrored). + * + * @param aOrdinal Ordinal of a child. + * + * @return Block position of the child. + */ + IMPORT_C TPoint OrdinalToBlock(TInt aOrdinal) const; + + /** + * Sets flag(s) which alter the children's pixel error distribution within the grid layout. + * + * This method allows the client to force all items in the grid layout to be the same + * pixel size. The floating point error that this introduces is distributed between the various + * paddings of the layout. + * + * Example of use that allows outer paddings to be automatically adjusted: + * \code + * iGridLayout->SetLayoutModeFlags(EHuiGridRow, EHuiGridAdjustOuterPadding); + * \endcode + * + * Note that some flags are mutually exclusive, and will clear some existing flags if set. + * + * @param aDim the dimension to which the given flag(s) affect. + * @param aGridLayoutModeFlags Flags to be set or cleared + * @see TAlfGridLayoutModeFlags, ClearLayoutModeFlags + */ + IMPORT_C void SetLayoutModeFlags(THuiGridDimension aDim, TUint aGridLayoutModeFlags); + + /** + * Clears flag(s) which alter the children's pixel error distribution within the grid layout. + * + * @param aDim the dimension to which the given flag(s) affect. + * @param aGridLayoutModeFlags Flags to be cleared + * @see TAlfGridLayoutModeFlags, SetLayoutModeFlags + */ + IMPORT_C void ClearLayoutModeFlags(THuiGridDimension aDim, TUint aGridLayoutModeFlags); + + /** + * Return flag(s) which alter the children's pixel error distribution within the grid layout. + * + * @param aDim the dimension to return the flags for. + */ + IMPORT_C TUint LayoutModeFlags(THuiGridDimension aDim); + +public: // RnD utilities + + IMPORT_C void GetClassName(TDes& aName) const; + IMPORT_C void DumpTree() const; + IMPORT_C void GetInstanceName(TDes& aName) const; + IMPORT_C TType Type() const; + IMPORT_C TInt SessionId() const; + IMPORT_C void SetSessionId(TInt aSessionId); + + +private: + + /* Private methods */ + + /** + * Checks if the grid filling order is from top right corner instead + * the top left (default) + * + * @return ETrue if the fillig is started from top right. + */ + TBool UseRightToLeftFillingOrder() const; + + /** + * Calculates the size and position along the specified axis according to the current weights. + * The non-weights are resolved into pixels and the remainder after subtracting from InnerSize + * is shared between the other cells that are specified using weight metrics. + * + * @note that this calculation assumes that the inner paddings have already been subtracted + * from the inner size, and that they will be added back in when calculating the actual + * position in base units. + * @note when called repeatedly by UpdateChildrenLayout, all the cells will be calculated for + * each time UpdateChildLayout is called. + * + * @param aDim the dimension along which to calculate + * @param aIndex the block being calculated + * @param aAvailablePixels the space available within the grid layout, after the paddings and + * inner paddings have already been subtracted + * @param aPos the resulting position in pixels of the block along the axis (replaces contents) + * @param aSize the resulting size in pixels of the block along the axis (replaces contents) + * @param aFloorPixelPos the total width assuming every item width is floored. + * @param aCeilingPixelPos the total width assuming every item width is ceilinged. + */ + void CalculateCellInPixelsReal( + THuiGridDimension aDim, + TInt aIndex, + TReal32 aAvailablePixels, + TReal32& aPos, + TReal32& aSize, + TInt& aFloorPixelPos, + TInt& aCeilingPixelPos) const; + + /** + * Calculates the size and position along the specified axis according to the current weights. + * The non-weights are resolved into pixels and the remainder after subtracting from InnerSize + * is shared between the other cells that are specified using weight metrics. + * Returns integer pixel values, taking into account the TAlfGridLayoutModeFlags for error rounding. + * + * @param aDim the dimension along which to calculate + * @param aIndex the block being calculated + * @param aAvailablePixels the space available within the grid layout, after the paddings and + * inner paddings have already been subtracted + * @param aPos the resulting position in pixels of the block along the axis (replaces contents) + * @param aSize the resulting size in pixels of the block along the axis (replaces contents) + * @see CalculateCellInPixelsReal + */ + void CalculateCellInPixels( + THuiGridDimension aDim, + TInt aIndex, + TReal32 aAvailablePixels, + TInt& aPos, + TInt& aSize) const; + + /** + * Calculate inner/outer distribution of padding. + * Interpolates between the previously calculated positions for + * inner padding and outer padding of the child, according to the + * proportion between inner and outer padding size. + * + * @param aDim the dimension along which to calculate + * @param aInnerPadPos the calculated position if inner padding is applied + * @param aOuterPadPos the calculated position if outer padding is applied + */ + TReal32 CHuiGridLayout::ProportionalInnerOuterPadding( + THuiGridDimension aDim, + TReal32 aInnerPadPos, + TReal32 aOuterPadPos) const; + + /** + * Retrieve the weight and pixel size from a metric. + * Returns one or the other depending on what type the metric is. + * Zeroes unused params. + * + * @param aDim the dimension along which to calculate + * @param aMetric The metric to examine + * @param aWeight Contains weight from metric. + * @param aPix Contains pixel size from metric. + */ + void WeightFromMetric(THuiGridDimension aDim, THuiMetric& aMetric, TReal32& aWeight, TInt& aPix) const; + +private: + // Private data structure. Owned. + struct TGridLayoutPrivateData; + TGridLayoutPrivateData* iGridLayoutData; + + TAny* iSpare; + }; + +#endif // __HUIGRIDLAYOUT_H__