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 CHuiAnchorLayout. Anchor layouts allow specifying the 

    15 *                placement of child visuals using anchors, that can be relative or absolute

    16 *                coordinates and attached to a specific edge of the layout.

    17 *

    18 */

    19 

    20 

    21 

    22 #ifndef __HUIANCHORLAYOUT_H__

    23 #define __HUIANCHORLAYOUT_H__

    24 

    25 

    26 #include <e32base.h>

    27 #include <uiacceltk/HuiLayout.h>

    28 #include <uiacceltk/HuiTimedPoint.h>

    29 

    30 

    31 /* Forward declarations */

    32 class CHuiEnv;

    33 class CHuiLayout;

    34 class CHuiControl;

    35 

    36 

    37 /** for internal use only */

    38 enum THuiAnchorBitmask

    39     { 

    40     EHuiAnchorBitmaskHorizontal = 0x000F,

    41     EHuiAnchorBitmaskVertical = 0x00F0

    42     };

    43 

    44 /** for internal use only */

    45 enum THuiAnchorBitmaskShift

    46    {

    47     EHuiAnchorBitmaskShiftHorizontal = 0,

    48     EHuiAnchorBitmaskShiftVertical = 4

    49     };

    50 

    51 /** for internal use only */

    52 enum THuiAnchorAxis

    53     {

    54     EHuiAnchorAxisHorizontal = 0,

    55     EHuiAnchorAxisVertical = 1

    56     };

    57 

    58 /** for internal use only */

    59 enum THuiAnchorProximity

    60     {

    61     EHuiAnchorProximityNone = 0,    

    62     EHuiAnchorProximitySize,

    63     EHuiAnchorProximityNear,

    64     EHuiAnchorProximityCenter,

    65     EHuiAnchorProximityFar

    66     };

    67 

    68 /** 

    69  * Anchor type. Used to determine which edge or corner of a child visual is 

    70  * defined by an anchor.

    71  *

    72  * @note that if width or height are used as one anchor, they must be combined 

    73  * with an appropriate anchor in order to unambiguously determine the size and 

    74  * position of the child.

    75  */

    76 enum THuiAnchorType

    77     {

    78     EHuiAnchorTypeNone = EHuiAnchorProximityNone,

    79     

    80     EHuiAnchorTypeWidth = EHuiAnchorProximitySize << EHuiAnchorBitmaskShiftHorizontal,

    81     EHuiAnchorTypeLeft = EHuiAnchorProximityNear << EHuiAnchorBitmaskShiftHorizontal,

    82     EHuiAnchorTypeHCenter = EHuiAnchorProximityCenter << EHuiAnchorBitmaskShiftHorizontal,

    83     EHuiAnchorTypeRight = EHuiAnchorProximityFar << EHuiAnchorBitmaskShiftHorizontal,

    84     

    85     EHuiAnchorTypeHeight = EHuiAnchorProximitySize << EHuiAnchorBitmaskShiftVertical,

    86     EHuiAnchorTypeTop = EHuiAnchorProximityNear << EHuiAnchorBitmaskShiftVertical,

    87     EHuiAnchorTypeVCenter = EHuiAnchorProximityCenter << EHuiAnchorBitmaskShiftVertical,

    88     EHuiAnchorTypeBottom = EHuiAnchorProximityFar << EHuiAnchorBitmaskShiftVertical,

    89     

    90     

    91     EHuiAnchorTypeSize = EHuiAnchorTypeHeight | EHuiAnchorTypeWidth,

    92 

    93     EHuiAnchorTypeTopLeft = EHuiAnchorTypeTop | EHuiAnchorTypeLeft,

    94     EHuiAnchorTypeTopCenter = EHuiAnchorTypeTop | EHuiAnchorTypeHCenter,

    95     EHuiAnchorTypeTopRight = EHuiAnchorTypeTop | EHuiAnchorTypeRight,

    96 

    97     EHuiAnchorTypeCenterLeft = EHuiAnchorTypeVCenter | EHuiAnchorTypeLeft,

    98     EHuiAnchorTypeCenter = EHuiAnchorTypeVCenter | EHuiAnchorTypeHCenter,

    99     EHuiAnchorTypeCenterRight = EHuiAnchorTypeVCenter | EHuiAnchorTypeRight,

   100     

   101     EHuiAnchorTypeBottomLeft = EHuiAnchorTypeBottom | EHuiAnchorTypeLeft,

   102     EHuiAnchorTypeBottomCenter = EHuiAnchorTypeBottom | EHuiAnchorTypeHCenter,

   103     EHuiAnchorTypeBottomRight = EHuiAnchorTypeBottom | EHuiAnchorTypeRight

   104     };

   105 

   106 /** 

   107  * Anchor origin, relative to a particular edge or corner. Direction is 

   108  * measured along positive x and y axes, as modified by the metric used.

   109  */

   110 enum THuiAnchorAttachmentOrigin

   111     {

   112     EHuiAnchorAttachmentOriginNone = EHuiAnchorTypeNone,

   113     

   114     EHuiAnchorAttachmentOriginLeft = EHuiAnchorTypeLeft,

   115     EHuiAnchorAttachmentOriginHCenter = EHuiAnchorTypeHCenter,

   116     EHuiAnchorAttachmentOriginRight = EHuiAnchorTypeRight,

   117     

   118     EHuiAnchorAttachmentOriginTop = EHuiAnchorTypeTop,

   119     EHuiAnchorAttachmentOriginVCenter = EHuiAnchorTypeVCenter,

   120     EHuiAnchorAttachmentOriginBottom = EHuiAnchorTypeBottom,

   121     

   122     EHuiAnchorAttachmentOriginTopLeft = EHuiAnchorTypeTopLeft, 

   123     EHuiAnchorAttachmentOriginTopCenter = EHuiAnchorTypeTopCenter, 

   124     EHuiAnchorAttachmentOriginTopRight = EHuiAnchorTypeTopRight, 

   125 

   126     EHuiAnchorAttachmentOriginCenterLeft = EHuiAnchorTypeCenterLeft,

   127     EHuiAnchorAttachmentOriginCenter = EHuiAnchorTypeCenter, 

   128     EHuiAnchorAttachmentOriginCenterRight = EHuiAnchorTypeCenterRight, 

   129     

   130     EHuiAnchorAttachmentOriginBottomLeft = EHuiAnchorTypeBottomLeft, 

   131     EHuiAnchorAttachmentOriginBottomCenter = EHuiAnchorTypeBottomCenter, 

   132     EHuiAnchorAttachmentOriginBottomRight = EHuiAnchorTypeBottomRight

   133     };

   134     

   135 /** 

   136  * Type of attachment point used when attaching an anchor to another

   137  * anchor in the same layout.

   138  */

   139 enum THuiAnchorAttachmentType

   140     {

   141     EHuiAnchorAttachToParent = -1

   142     };

   143     

   144     

   145 /** 

   146  * Determines which corner of a child visual is positioned by the anchor

   147  * @deprecated, only retained for use with deprecated SetAnchor routines, use

   148  *                        THuiAnchorAttachmentOrigin instead with new APIs

   149  */

   150 enum THuiAnchor

   151     {

   152     /** Anchor that defines the top left corner of a visual. */

   153     EHuiAnchorTopLeft,

   154 

   155     /** Anchor that defines the bottom right corner of a visual. */

   156     EHuiAnchorBottomRight

   157     };

   158 

   159 

   160 /** 

   161  * Anchor origins.

   162  * @deprecated, only retained for use with deprecated SetAnchor routines, use

   163  *                        THuiAnchorAttachmentOrigin instead with new APIs

   164  */

   165 enum THuiAnchorOrigin

   166     {

   167     EHuiAnchorOriginLeft,

   168     EHuiAnchorOriginHCenter,

   169     EHuiAnchorOriginRight,

   170     EHuiAnchorOriginTop,

   171     EHuiAnchorOriginVCenter,

   172     EHuiAnchorOriginBottom

   173     };

   174 

   175 

   176 /** 

   177  *Anchor metric types, for offsets and sizes.

   178  * @deprecated, only retained for use with deprecated SetAnchor routines, use

   179  *                        THuiMetric instead with new APIs

   180  */

   181 enum THuiAnchorMetric

   182     {

   183     /** Use absolute pixel coordinates to specify the values. */        

   184     EHuiAnchorMetricAbsolute,

   185     /** 

   186      * Use the size of the visual 

   187      * either normalized between 0.0 (at origin) and 1.0 (farthest away edge)

   188      * or -0.5 (min) and +0.5 (0.0 being always at the origin). For example if you 

   189      * use EHuiAnchorOriginLeft with EHuiAnchorMetricRelativeToSize, the 

   190      * left edge is at 0.0, and the right edge at 1.0. But if you use any of 

   191      * the center origins (EHuiAnchorOriginHCenter or EHuiAnchorOriginVCenter),

   192      * then the left/top edge is at -0.5 and right/top edge is at +0.5.

   193      */

   194     EHuiAnchorMetricRelativeToSize

   195     };

   196 

   197 

   198 /**

   199  * CHuiAnchorLayout is a layout that allows visuals to be positioned with 

   200  * flexible relative anchor points. 

   201  *

   202  * To use this class, an anchor layout is created, and then a number of anchor

   203  * points are added to it using calls to the SetAnchor() method. The visuals

   204  * inside the layout will be stretched between these anchor points.

   205  *

   206  * By default, each child is set to cover the entire anchor layout area.

   207  * @todo This seems to be incorrect. Default behaviour seems to be that

   208  * a child is invisible until its anchor points have been set.

   209  * 

   210  * @see CHuiAnchorLayout::SetAnchor() for more information about anchors.

   211  */

   212 NONSHARABLE_CLASS(CHuiAnchorLayout) : public CHuiLayout

   213     {

   214 public:

   215 

   216     /* Constructors and destructor. */

   217 

   218     /**

   219      * Construct a new anchor layout and give its ownership to a control.

   220      *

   221      * @param aOwnerControl  Owner control.

   222      * @param aParentLayout  Parent layout for the new anchor layout.

   223      */

   224     IMPORT_C static CHuiAnchorLayout* AddNewL(CHuiControl& aOwnerControl,

   225                                               CHuiLayout* aParentLayout = 0);

   226 

   227     /**

   228      * Constructor.

   229      */

   230     CHuiAnchorLayout(MHuiVisualOwner& aOwner);

   231 

   232     /**

   233      * Second-phase constructor.

   234      */

   235     void ConstructL();

   236 

   237     /**

   238      * Destructor.

   239      */

   240     IMPORT_C virtual ~CHuiAnchorLayout();

   241 

   242 

   243     /* Methods. */

   244 

   245     /**

   246      * Resets all the anchors.

   247      */

   248     IMPORT_C void Reset();

   249 

   250     /**

   251      * Anchors a child visual's corner to specific position within this layout.

   252      *

   253      * @deprecated, use new @c Attach APIs with THuiMetric support.

   254      * See the relevant API documentation for an example of how to migrate your code

   255      *

   256      * Each child can have two anchors: the top left and bottom right corners 

   257      * of the child visual. These anchors can be fastened to any point within 

   258      * this layout, as specified by the other parameters.

   259      *

   260      * In a typical case you set two anchors (both EHuiAnchorTopLeft and 

   261      * EHuiAnchorBottomRight), which specifies both size and position for the 

   262      * child. However it is also possible to set only the EHuiAnchorTopLeft 

   263      * anchor, which only positions the child without affecting it's size.

   264      * 

   265      * @see RemoveAnchor() to remove an achor definition.

   266      * 

   267      * @note  After updating anchors, you should call 

   268      *        CHuiLayout::UpdateChildrenLayout(), to cause the anchors to be 

   269      *        applied to child positions and/or sizes.

   270      * 

   271      * For example the following code will anchor child visual number 0 in 

   272      * the middle of the layout, with a 25% border around the outside:

   273      *

   274      * \code

   275      *      // set top left corner position of 1st child ..

   276      *	    iLayout->SetAnchor(EHuiAnchorTopLeft, 0,

   277      *	        EHuiAnchorOriginLeft, 

   278      *          EHuiAnchorOriginTop,

   279      *          EHuiAnchorMetricRelativeToSize, // With EHuiAnchorOriginLeft means that 0.0 goes to left edge, and 1.0 to the right

   280      *          EHuiAnchorMetricRelativeToSize, // With EHuiAnchorOriginTop means that 0.0 goes to top edge, and 1.0 to the bottom

   281      *          THuiTimedPoint(0.25, 0.25));

   282      *      // .. and set the bottom right corner also to fix the size

   283      * 	    iLayout->SetAnchor(EHuiAnchorBottomRight, 0,

   284      *	        EHuiAnchorOriginRight, 

   285      *          EHuiAnchorOriginBottom,

   286      *   	EHuiAnchorMetricRelativeToSize, 

   287      *          EHuiAnchorMetricRelativeToSize,

   288      *          THuiTimedPoint(-0.25, -0.25)); 

   289      * \endcode

   290      *

   291      * @todo  Specifying a transition in the timed point may be useless:

   292      *        layouts are evaluated pretty seldom.

   293      *

   294      * @param aAnchor       Type of the anchor (either EHuiAnchorTopLeft for the 

   295      *                      top left corner or EHuiAnchorBottomRight for bottom right

   296      *                      corner).

   297      * @param aOrdinal      Ordinal of the child visual that this anchor applies to.

   298      * @param aHorizOrigin  Horizontal origin for the anchor position (aPosition). 

   299      *                      Defines the point inside the layout on which the 

   300      *                      evaluation of the child's placement is based. May be 

   301      *                      EHuiAnchorOriginLeft (left edge), 

   302      *                      EHuiAnchorOriginHCenter (center) or

   303      *                      EHuiAnchorOriginRight (right edge).

   304      * @param aVertOrigin   Vertical origin for the anchor position (aPosition). 

   305      *                      Defines the point inside the layout on which the 

   306      *                      evaluation of the child's placement is based. Possible options 

   307      *                      are EHuiAnchorOriginTop (top), EHuiAnchorOriginVCenter 

   308      *                      (center) and EHuiAnchorOriginBottom (bottom).

   309      * @param aHorizMetric  Specifies the metric to use to define the

   310      *                      horizontal position: EHuiAnchorMetricAbsolute to use 

   311      *                      absolute pixels or EHuiAnchorMetricRelativeToSize to 

   312      *                      use normalized values relative to layout size.

   313      * @param aVertMetric   Specifies the metric used in the vertical position:

   314      *                      EHuiAnchorMetricAbsolute to use absolute pixels or 

   315      *                      EHuiAnchorMetricRelativeToSize to use normalized 

   316      *                      values relative to layout size.     

   317      * @param aPosition     The achor position as an offset from the origin point, 

   318      *                      applied using the metric specified with aHorizMetric 

   319      *                      and aVertMetric.

   320      * @return                   Error code

   321      *

   322      */

   323     IMPORT_C TInt SetAnchor(THuiAnchor aAnchor, TInt aOrdinal,

   324                             THuiAnchorOrigin aHorizOrigin,

   325                             THuiAnchorOrigin aVertOrigin,

   326                             THuiAnchorMetric aHorizMetric,

   327                             THuiAnchorMetric aVertMetric,

   328                             const THuiTimedPoint& aPosition);

   329     /**

   330      * Convenience method for setting top left and bottom right anchors in a single call.

   331      *

   332      * This method sets size-relative anchors for a single child visual.

   333      *

   334      * @param aOrdinal           Ordinal of child visual to set anchors for.

   335      * @param aTlHorizOrigin     Horizontal origin for the top left anchor position (aPosition). 

   336      *                           Defines the point inside the layout on which the 

   337      *                           evaluation of the child's placement is based. May be 

   338      *                           EHuiAnchorOriginLeft (left edge), 

   339      *                           EHuiAnchorOriginHCenter (center) or

   340      *                           EHuiAnchorOriginRight (right edge).

   341      * @param aTlVertOrigin      Vertical origin for the top left anchor position (aPosition). 

   342      *                           Defines the point inside the layout on which the 

   343      *                           evaluation of the child's placement is based. Possible options 

   344      *                           are EHuiAnchorOriginTop (top), EHuiAnchorOriginVCenter 

   345      *                           (center) and EHuiAnchorOriginBottom (bottom).

   346      * @param aTopLeftOffset     The achor position as an offset from the origin point, 

   347      * @param aBrHorizOrigin     Horizontal origin for the bottom right anchor position (aPosition). 

   348      *                           Defines the point inside the layout on which the 

   349      *                           evaluation of the child's placement is based. May be 

   350      *                           EHuiAnchorOriginLeft (left edge), 

   351      *                           EHuiAnchorOriginHCenter (center) or

   352      *                           EHuiAnchorOriginRight (right edge).

   353      * @param aBrVertOrigin      Vertical origin for the bottom right anchor position (aPosition). 

   354      *                           Defines the point inside the layout on which the 

   355      *                           evaluation of the child's placement is based. Possible options 

   356      *                       	 are EHuiAnchorOriginTop (top), EHuiAnchorOriginVCenter 

   357      *                           (center) and EHuiAnchorOriginBottom (bottom).     

   358      * @param aBottomRightOffset The achor position as an offset from the origin point,      

   359      * @return                   Error code

   360      *

   361      * @see CHuiAnchorLayout::SetAnchor() for more information about anchors.

   362      */

   363     IMPORT_C TInt SetRelativeAnchorRect(TInt aOrdinal,

   364                                         THuiAnchorOrigin aTlHorizOrigin,

   365                                         THuiAnchorOrigin aTlVertOrigin,

   366                                         const THuiRealPoint& aTopLeftOffset,

   367                                         THuiAnchorOrigin aBrHorizOrigin,

   368                                         THuiAnchorOrigin aBrVertOrigin,

   369                                         const THuiRealPoint& aBottomRightOffset);

   370                                   

   371     /**

   372      * Undefines an anchor.

   373      * @see SetAnchor()

   374      * @deprecated instead use @c Detach and see relevant API documentation for

   375      *      example code

   376      */

   377     IMPORT_C void RemoveAnchor(THuiAnchor aAnchor, TInt aOrdinal);

   378 

   379                                   

   380     /**

   381      * Anchors one or more edges of a child visual to a specific position 

   382      * within this layout. When combined together, a correctly specified group 

   383      * of anchors provide sufficient information for the anchor layout to 

   384      * determine the size and position of the child visual.

   385      *

   386      * Each child can have up to four anchors, each of which correspond to an 

   387      * edge. A corner anchor is equivalent to supplying two similar orthogonal 

   388      * edge anchors, so typically it is easier to use corners. Therefore, each 

   389      * child can have up to two corner anchors, or a mixture of corners and 

   390      * edges. Alternatively, four similar edges can be specified in one call by 

   391      * supplying a box metric.

   392      *

   393      * In a typical case you set two different corner anchors (for example both 

   394      * EHuiAnchorTypeTopLeft and EHuiAnchorTypeBottomRight), taking care

   395      * to ensure that they are sufficiently orthogonal in order to define all needed

   396      * coordinates. However it is also possible to set only one corner anchor, 

   397      * which only positions the child without affecting it's size. Alternatively,

   398      * one anchor can be specified as a corner, and then the other can be 

   399      * specified as EHuiAnchorTypeSize; similarly the coordinates along

   400      * one axis can be specified by an appropriate combination of edge and 

   401      * width or height anchors.

   402      *

   403      * The position of each anchor relative to this layout is determined

   404      * by the choice of origin (i.e. which point of the layout the 

   405      * child's is attached to), and the offset position, which is specified

   406      * using a THuiMetric or related type. All available features of 

   407      * THuiMetric may be used to affect the resulting position, providing the 

   408      * benefit that different metrics can be used for each child. Also note 

   409      * that the metric used will override the base unit that has been set in 

   410      * this layout.

   411      * 

   412      * @note if called again to specify the same anchor types

   413      *      that have been previous set, those definitions will be updated. 

   414      *      However, in order to change type, it is necessary to detach a 

   415      *      previously defined anchor first, as there can only be a maximum 

   416      *      of two anchors along each axis (for a given child).

   417      * @note that size anchor type and attachment origins are not 

   418      *      currenly supported. 

   419      * @note that center anchor type is not currently supported.

   420      * @note if an anchor of similar type has already been defined it will be 

   421      *      replaced, however in general it is easier to manage anchors by 

   422      *      removing them all and starting again.

   423      * @note  After updating anchors, you should call 

   424      *      @c CHuiLayout::UpdateChildrenLayout(), to cause the anchors to be 

   425      *      applied to child positions and/or sizes.

   426      * 

   427      * @see @c Detach() to remove achor definitions for a given ordinal

   428      *

   429      * For example the following code will anchor three child visuals 0, 1, 2  in 

   430      * the middle of the layout, with a 25% border around the outside, such that 

   431      * they all occupy the same position:

   432      *

   433      * \code

   434      *      // using edges...

   435      *	    iLayout->Attach(0, 

   436      *          EHuiAnchorTypeLeft,

   437      *          THuiXYMetric(0.25, EHuiMetricNormalized),

   438      *          EHuiAnchorAttachmentOriginLeft);

   439      *	    iLayout->Attach(0, 

   440      *          EHuiAnchorTypeRight,

   441      *          THuiXYMetric(-0.25, EHuiMetricNormalized),

   442      *          EHuiAnchorAttachmentOriginRight);

   443      *	    iLayout->Attach(0, 

   444      *          EHuiAnchorTypeTop,

   445      *          THuiXYMetric(0.25, EHuiMetricNormalized),

   446      *          EHuiAnchorAttachmentOriginTop);

   447      *	    iLayout->Attach(0, 

   448      *          EHuiAnchorTypeBottom,

   449      *          THuiXYMetric(-0.25, EHuiMetricNormalized),

   450      *          EHuiAnchorAttachmentOriginBottom);

   451      *

   452      *      // using corners...

   453      *	    iLayout->Attach(1, 

   454      *          EHuiAnchorTypeTopLeft,

   455      *          THuiXYMetric(0.25, EHuiMetricNormalized),

   456      *          EHuiAnchorAttachmentOriginTopLeft);

   457      * 	    iLayout->Attach(1, 

   458      *	        EHuiAnchorTypeBottomRight, 

   459      *         THuiXYMetric(-0.25, EHuiMetricNormalized),

   460      *	        EHuiAnchorAttachmentOriginBottomRight);

   461      * 

   462      *      // .. and using a box

   463      * 	    iLayout->Attach(2, THuiBoxMetric(

   464      *          THuiMetric(0.25, EHuiMetricNormalized),

   465      *          THuiMetric(-0.25, EHuiMetricNormalized),

   466      *          THuiMetric(0.25, EHuiMetricNormalized),

   467      *          THuiMetric(-0.25, EHuiMetricNormalized)));

   468      * \endcode

   469      *

   470      * @param aOrdinal      Ordinal of the child visual that this anchor applies to

   471      * @param aType       Type of the anchor, which determines how and where the anchor attaches to this layout

   472      * @param aOffset     The anchor position as an offset from the origin point,

   473      *      specifying both the magnitude and units of the offset for the relevant axes.

   474      * @param aAttachmentOrigin  Origin for the anchor offset.

   475      *      Defines the point inside the layout from which the 

   476      *      evaluation of the child's placement is based. 

   477      * @param aAttachmentOrdinal    the ordinal of the anchor to which this anchor is attached, 

   478      *      use the default value of EHuiAnchorAttachToParent in order to attach to parent

   479      * @return Error code

   480      *

   481      */

   482     IMPORT_C TInt Attach(

   483         TInt aOrdinal,

   484         THuiAnchorType aType, 

   485         const THuiMetric& aOffset,

   486         THuiAnchorAttachmentOrigin aAttachmentOrigin,

   487         TInt aAttachmentOrdinal = EHuiAnchorAttachToParent);

   488 

   489     /** 

   490      * Attach a corner of a child visual  to a specific position 

   491      * within this layout. 

   492      *

   493      * @see Attach() for all API documentation

   494      */

   495     IMPORT_C TInt Attach(

   496         TInt aOrdinal,

   497         THuiAnchorType aType, 

   498         const THuiXYMetric& aOffset,

   499         THuiAnchorAttachmentOrigin aAttachmentOrigin = EHuiAnchorAttachmentOriginTopLeft,

   500         TInt aAttachmentOrdinal = EHuiAnchorAttachToParent);

   501 

   502     /** 

   503      * Attach all four edges of a child visual  to a specific position 

   504      * within this layout.

   505      *

   506      * @note, will detach all existing edges first. In case of error, all

   507      * edges that were successfull added before the error occurred will be 

   508      * detached.

   509      *

   510      * @see Attach() for all API documentation

   511      * @param aAttachmentOrigin if set to EHuiAnchorAttachmentOriginNone, each edge will 

   512      *        be attached to the corresponding edge

   513      */

   514     IMPORT_C TInt Attach(

   515         TInt aOrdinal,

   516         const THuiBoxMetric& aOffset,

   517         THuiAnchorAttachmentOrigin aAttachmentOrigin = EHuiAnchorAttachmentOriginNone,

   518         TInt aAttachmentOrdinal = EHuiAnchorAttachToParent);

   519 

   520 

   521     /**

   522      * Undefines all anchors for a specified ordinal. Has no effect if the specified ordinal

   523      * cannot be found.

   524      *

   525      * @see Attach()

   526      * 

   527      * @param aOrdinal the ordinal of the anchor to remove

   528      */

   529     IMPORT_C void Detach(TInt aOrdinal);

   530     

   531     /**

   532      * Undefines an anchor. Has no effect if the specified anchor type 

   533      * cannot be found. For example to detach a corner anchor with ordinal

   534      * equal to zero:

   535      *

   536      * \code

   537      *      iLayout->Detach(0, EAlfAnchorTypeTopLeft);

   538      * \endcode

   539      *

   540      * @see Attach()

   541      * @note can be used to separately remove the edges 

   542      * that were attached using different combinations of types, 

   543      * but try to be consistent in using either edges or corners to avoid 

   544      * confusion.

   545      * 

   546      * @param aOrdinal the ordinal of the anchor to remove

   547      * @param aType the edge relating to the anchor to remove

   548      */    

   549     IMPORT_C void Detach(TInt aOrdinal, THuiAnchorType aType);

   550     

   551     /**

   552      * Overridden version of size changing updates the layout of child visuals.

   553      *

   554      * @param aSize  New size for the layout.

   555      * @param aTransitionTime  Time for the transition to new size to take

   556      *               place.

   557      */

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

   559 

   560     /**

   561      * Determines the size of a child visual according to the layout.

   562      *

   563      * @note if an anchor is defined at the specified ordinal position, the

   564      *      metric belonging to the anchor will override the metric specified

   565      *      in this layout's base unit. 

   566      *

   567      * @param aOrdinal  Layout ordinal of the child visual.

   568      * @param aSize     New target size for the child.

   569      *

   570      * @return  <code>ETrue</code>, if a new size was determined. Otherwise,

   571      *          <code>EFalse</code> is returned and no size changes are

   572      *          needed.

   573      */

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

   575 

   576     /**

   577      * Determines the position of a child visual according to the layout. 

   578      *

   579      * @note if an anchor is defined at the specified ordinal position, the

   580      *      metric belonging to the anchor will override the metric specified

   581      *      in this layout's base unit. 

   582      *

   583      * @param aOrdinal  Layout ordinal of the child visual.

   584      * @param aPos      New position for the child.

   585      *

   586      * @return  <code>ETrue</code>, if a new position was determined.

   587      *          Otherwise, <code>EFalse</code> is returned and no position

   588      *          changes are needed.

   589      */

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

   591 

   592     /**

   593      * Determines the position and size of a child visual according to the layout.

   594      * The child position is determined using the base units of the layout. If a 

   595      * valid anchor has been defined then the size and or position of the 

   596      * corresponding child will be determined.

   597      *

   598      * @see CHuiLayout::ChildRect for full documentation

   599      */

   600     IMPORT_C virtual TInt ChildRect(TInt aOrdinal, THuiRealRect& aRect);

   601     

   602     /**

   603      * Returns the name of the class.

   604      *

   605      * @param aName  Name of the layout class.

   606      */

   607     void GetClassName(TDes& aName) const

   608         {

   609         aName = _L("CHuiAnchorLayout");

   610         }

   611 

   612 

   613 private: // internal data types

   614     struct TCornerAnchor;

   615     struct TAnchor_deprecated;

   616     struct TEdgeAnchor;

   617     struct TAnchor;

   618     struct TAxis;

   619 

   620 private: // methods

   621 

   622     /** 

   623      * Find the anchor at the given index in this layout's anchor list.

   624      *

   625      * @param aOrdinal Index into the anchor list.

   626      * @return Anchor at the requested ordinal. NULL if ordinal is out of range.

   627      *

   628      */

   629     const TAnchor* Anchor(TInt aOrdinal) const;

   630 

   631     /**

   632      * the axis structure specified

   633      * @param aAxis the index of the axis required

   634      * @return the axis specified

   635      */

   636     inline TAxis& Axis(THuiAnchorAxis aAxis) const;

   637 

   638     /**

   639      * Evaluate anchor along an axis

   640      *

   641      * @param aAxisId the axis id required

   642      * @param aAxis the axis

   643      * @param aNear outputs the near side value along the specified axis

   644      * @param aFar outputs the far side value along the specified axis

   645      * @return a value selected from CHuiLayout::EHuiLayoutChildRect, depending on which sides were updated

   646      */

   647     TInt EvaluateAxis(THuiAnchorAxis aAxisId, const TAxis& aAxis, TReal32& aNear, TReal32& aFar) const;

   648 

   649     /*

   650      * Get the metric reference for an anchor's offset along a specified axis

   651      *

   652      * @param aAxisID the axis needed

   653      * @param aEdge the edge

   654      * @return the metric reference value in pixels

   655      */

   656     TReal32 EdgeOffsetInPixels(THuiAnchorAxis aAxisId, const TEdgeAnchor& aEdge) const;

   657     

   658     /**

   659      * Calculate the actual pixel value for the supplied edge's position and size

   660      * relative to this layout.

   661      *

   662      * @param aAxisID the axis needed

   663      * @param aEdge the edge to be evaluated

   664      * @param aInnerPaddingPx the inner padding for this axis in pixels

   665      * @param aOffset the offset in pixels

   666      * @param aNearPx near coordinate of the inner rect

   667      * @param aNearCalculatedPx returns the near coordinate which will be modified if the edge was relevant

   668      * @param aFarPx far coordinate of the inner rect

   669      * @param aFarCalculatedPx returns the far coordinate which will be modified if the edge was relevant

   670      * @return a value selected from CHuiLayout::EHuiLayoutChildRect, depending on which sides were updated

   671      */

   672     TInt EvaluateEdgeAnchorInPixels(

   673         THuiAnchorAxis aAxisId,

   674         const TEdgeAnchor& aEdge,

   675         TReal32 aInnerPaddingPx,

   676         TReal32 aOffsetPx,

   677         TReal32 aNearPx, TReal32& aNearCalculatedPx, 

   678         TReal32 aFarPx, TReal32& aFarCalculatedPx) const;

   679 

   680     /**

   681      * Calculate the actual pixel value for the attached edge's position and size

   682      * relative to this layout.

   683      *

   684      * @param aAxisID the axis needed

   685      * @param aEdge the edge to be evaluated

   686      * @param aInnerPaddingPx the inner padding for this axis in pixels

   687      * @param aNearPx near coordinate of the inner rect

   688      * @param aNearCalculatedPx returns the near coordinate which will be modified if the edge was relevant

   689      * @param aFarPx far coordinate of the inner rect

   690      * @param aFarCalculatedPx returns the far coordinate which will be modified if the edge was relevant

   691      * @return a value selected from CHuiLayout::EHuiLayoutChildRect, depending on which sides were updated

   692      */

   693     TInt EvaluateEdgeAttachmentInPixels(

   694         THuiAnchorAxis aAxisId,

   695         const TEdgeAnchor& aEdge,

   696         TReal32 aInnerPaddingPx,

   697         TReal32 aNearPx, TReal32& aNearCalculatedPx, 

   698         TReal32 aFarPx, TReal32& aFarCalculatedPx) const;

   699 

   700     /**  

   701      * Detach edge

   702      *

   703      * @param aOrdinal the anchor to detach

   704      * @param aType the type of the edge to detach, must correspond to an edge

   705      *      type only (i.e. must not be a corner type).

   706      */

   707     void DetachEdge(TInt aOrdinal, THuiAnchorType aType);

   708 

   709     /*

   710      * Look for a cycle in the graph, starting with a specified edge

   711      *

   712      * @param aStartAxisId the axis of the specified starting edge

   713      * @param aStartAnchorProximity the proximity of the specified starting edge

   714      * @param aStartOrdinal the ordinal of the specified starting edge

   715      * @param aEdge the edge under consideration

   716      * @return ETrue if a cycle was found

   717      */

   718     TBool CheckForCycles(

   719         THuiAnchorAxis aStartAxisId,

   720         THuiAnchorProximity aStartAnchorProximity,

   721         TInt aStartOrdinal, 

   722         const TEdgeAnchor* aEdge) const;

   723 

   724 private: // helper methods for dealing with internal structures

   725 

   726     /** 

   727      * convert an edge into a proximity. 

   728      *

   729      * @note if the edge is of type EHuiAnchorEdgeNone, then 

   730      * EHuiAnchorProximityNone will be returned, and aAxis will not be modified.

   731      *

   732      * @param aType the type

   733      * @param aAxis output parameter specifying along which axis the edge was defined

   734      * @return the proximity

   735      */    

   736     THuiAnchorProximity ConvertTypeToProximity(THuiAnchorType aType, THuiAnchorAxis& aAxis) const;

   737 

   738     /** 

   739      * convert an attachment origin into a proximity. 

   740      *

   741      * @note if the edge is of type EHuiAnchorAttachmentOriginNone, then 

   742      * EHuiAnchorProximityNone will be returned, and aAxis will not be modified.

   743      *

   744      * @param aAttachmentOrigin the origin

   745      * @param aAxis output parameter specifying along which axis the edge was defined

   746      * @return the proximity

   747      */    

   748     THuiAnchorProximity ConvertAttachmentOriginToProximity(THuiAnchorAttachmentOrigin aAttachmentOrigin, THuiAnchorAxis& aAxis) const;

   749 

   750     /** 

   751      * split a corner up into its respective edges

   752      *

   753      * @param aCorner the corner to convert

   754      * @param aEdgeH the horizontal edge

   755      * @param aEdgeV the vertical edge

   756      */

   757     void ConvertCornerToEdges(THuiAnchorType aCorner, THuiAnchorType& aEdgeH, THuiAnchorType& aEdgeV) const;

   758     

   759     /** 

   760      * split a corner attachment origin up into its respective edge origins

   761      *

   762      * @param aCornerOrigin the corner origin to convert

   763      * @param aEdgeH the horizontal origin

   764      * @param aEdgeV the vertical origin

   765      */

   766     void ConvertCornerAttachmentOriginToEdgeAttachmentOrigins(THuiAnchorAttachmentOrigin aCornerOrigin, THuiAnchorAttachmentOrigin& aEdgeOriginH, THuiAnchorAttachmentOrigin& aEdgeOriginV) const;

   767     

   768 private: // helper methods for compatibility with deprecated APIs

   769 

   770     THuiAnchorType ConvertDeprecatedAnchorTypeToType(THuiAnchor aAnchor) const;

   771     

   772     THuiAnchorAttachmentOrigin ConvertDeprecatedOrginToAttachmentOrigin(THuiAnchorOrigin aOrigin) const;

   773     THuiAnchorAttachmentOrigin ConvertDeprecatedOriginsToAttachmentOrigin(THuiAnchorOrigin aHorizOrigin, THuiAnchorOrigin aVertOrigin) const;

   774     

   775     THuiMetric ConvertDeprecatedAnchorMetricAndTargetToHuiMetric(THuiAnchorMetric aMetric, TReal32 aTarget) const;  

   776     THuiXYMetric ConvertDeprecatedAnchorMetricsAndOffsetToHuiMetric(THuiAnchorMetric aHorizMetric, THuiAnchorMetric aVertMetric, const THuiTimedPoint& aOffset) const;

   777 

   778 private: // data

   779 

   780     struct THuiAnchorLayoutPrivateData;

   781     THuiAnchorLayoutPrivateData* iHuiAnchorLayoutPrivateData; // owned

   782     };

   783 

   784 #endif  // __HUIANCHORLAYOUT_H__

   785 

   786