/*

* Copyright (c) 2006 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:   Anchor layout definition.

*

*/

#ifndef C_ALFANCHORLAYOUT_H

#define C_ALFANCHORLAYOUT_H

#include <alf/alflayout.h> 

/** for internal use only */

enum TAlfAnchorBitmask

    { 

    EAlfAnchorBitmaskHorizontal = 0x000F,

    EAlfAnchorBitmaskVertical = 0x00F0

    };

/** for internal use only */

enum TAlfAnchorBitmaskShift

   {

    EAlfAnchorBitmaskShiftHorizontal = 0,

    EAlfAnchorBitmaskShiftVertical = 4

    };

/** for internal use only */

enum TAlfAnchorAxis

    {

    EAlfAnchorAxisHorizontal = 0,

    EAlfAnchorAxisVertical = 1

    };

/** for internal use only */

enum TAlfAnchorProximity

    {

    EAlfAnchorProximityNone = 0,    

    EAlfAnchorProximitySize,

    EAlfAnchorProximityNear,

    EAlfAnchorProximityCenter,

    EAlfAnchorProximityFar

    };

/** 

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

 * defined by an anchor.

 *

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

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

 * position of the child.

 */

enum TAlfAnchorType

    {

    EAlfAnchorTypeNone = EAlfAnchorProximityNone,

    EAlfAnchorTypeWidth = EAlfAnchorProximitySize << EAlfAnchorBitmaskShiftHorizontal,

    EAlfAnchorTypeLeft = EAlfAnchorProximityNear << EAlfAnchorBitmaskShiftHorizontal,

    EAlfAnchorTypeHCenter = EAlfAnchorProximityCenter << EAlfAnchorBitmaskShiftHorizontal,

    EAlfAnchorTypeRight = EAlfAnchorProximityFar << EAlfAnchorBitmaskShiftHorizontal,

    EAlfAnchorTypeHeight = EAlfAnchorProximitySize << EAlfAnchorBitmaskShiftVertical,

    EAlfAnchorTypeTop = EAlfAnchorProximityNear << EAlfAnchorBitmaskShiftVertical,

    EAlfAnchorTypeVCenter = EAlfAnchorProximityCenter << EAlfAnchorBitmaskShiftVertical,

    EAlfAnchorTypeBottom = EAlfAnchorProximityFar << EAlfAnchorBitmaskShiftVertical,

    EAlfAnchorTypeSize = EAlfAnchorTypeHeight | EAlfAnchorTypeWidth,

    EAlfAnchorTypeTopLeft = EAlfAnchorTypeTop | EAlfAnchorTypeLeft,

    EAlfAnchorTypeTopCenter = EAlfAnchorTypeTop | EAlfAnchorTypeHCenter,

    EAlfAnchorTypeTopRight = EAlfAnchorTypeTop | EAlfAnchorTypeRight,

    EAlfAnchorTypeCenterLeft = EAlfAnchorTypeVCenter | EAlfAnchorTypeLeft,

    EAlfAnchorTypeCenter = EAlfAnchorTypeVCenter | EAlfAnchorTypeHCenter,

    EAlfAnchorTypeCenterRight = EAlfAnchorTypeVCenter | EAlfAnchorTypeRight,

    EAlfAnchorTypeBottomLeft = EAlfAnchorTypeBottom | EAlfAnchorTypeLeft,

    EAlfAnchorTypeBottomCenter = EAlfAnchorTypeBottom | EAlfAnchorTypeHCenter,

    EAlfAnchorTypeBottomRight = EAlfAnchorTypeBottom | EAlfAnchorTypeRight

    };

/** 

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

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

 */

enum TAlfAnchorAttachmentOrigin

    {

    EAlfAnchorAttachmentOriginNone = EAlfAnchorTypeNone,

    EAlfAnchorAttachmentOriginLeft = EAlfAnchorTypeLeft,

    EAlfAnchorAttachmentOriginHCenter = EAlfAnchorTypeHCenter,

    EAlfAnchorAttachmentOriginRight = EAlfAnchorTypeRight,

    EAlfAnchorAttachmentOriginTop = EAlfAnchorTypeTop,

    EAlfAnchorAttachmentOriginVCenter = EAlfAnchorTypeVCenter,

    EAlfAnchorAttachmentOriginBottom = EAlfAnchorTypeBottom,

    EAlfAnchorAttachmentOriginTopLeft = EAlfAnchorTypeTopLeft, 

    EAlfAnchorAttachmentOriginTopCenter = EAlfAnchorTypeTopCenter, 

    EAlfAnchorAttachmentOriginTopRight = EAlfAnchorTypeTopRight, 

    EAlfAnchorAttachmentOriginCenterLeft = EAlfAnchorTypeCenterLeft,

    EAlfAnchorAttachmentOriginCenter = EAlfAnchorTypeCenter, 

    EAlfAnchorAttachmentOriginCenterRight = EAlfAnchorTypeCenterRight, 

    EAlfAnchorAttachmentOriginBottomLeft = EAlfAnchorTypeBottomLeft, 

    EAlfAnchorAttachmentOriginBottomCenter = EAlfAnchorTypeBottomCenter, 

    EAlfAnchorAttachmentOriginBottomRight = EAlfAnchorTypeBottomRight

    };

/** 

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

 * anchor in the same layout.

 */

enum TAlfAnchorAttachmentType

    {

    EAlfAnchorAttachToParent = -1

    };

/** 

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

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

 *                        TAlfAnchorAttachmentOrigin instead with new APIs

 */

enum TAlfAnchor

    {

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

    EAlfAnchorTopLeft,

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

    EAlfAnchorBottomRight

    };

/** 

 * Anchor origins.

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

 *                        TAlfAnchorAttachmentOrigin instead with new APIs

 */

enum TAlfAnchorOrigin

    {

    EAlfAnchorOriginLeft,

    EAlfAnchorOriginHCenter,

    EAlfAnchorOriginRight,

    EAlfAnchorOriginTop,

    EAlfAnchorOriginVCenter,

    EAlfAnchorOriginBottom

    };

/** 

 *Anchor metric types, for offsets and sizes.

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

 *                        TAlfMetric instead with new APIs

 */

enum TAlfAnchorMetric

    {

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

    EAlfAnchorMetricAbsolute,

    /** 

     * Use the size of the visual 

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

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

     * use EAlfAnchorOriginLeft with EAlfAnchorMetricRelativeToSize, the 

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

     * the center origins (EAlfAnchorOriginHCenter or EAlfAnchorOriginVCenter),

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

     */

    EAlfAnchorMetricRelativeToSize

    };

class TAlfTimedPoint;

class CAlfControl;

/**

 * CAlfAnchorLayout is a layout that allows visuals to be positioned with 

 * flexible relative anchor points. 

 *

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

 * are added to it using calls to the Attach() methods. The visuals

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

 *

 *  @lib alfclient.lib

 *  @since S60 v3.2

 */

class CAlfAnchorLayout : public CAlfLayout

    {

public:

    /**

     * Two-phased constructor, which attach new object into the control.

     * @param aOwnerControl Control that owns this new obejct.

     * @param aParentLayout If given, the new object is set as child.

     */

    IMPORT_C static CAlfAnchorLayout* AddNewL(CAlfControl& aOwnerControl,

                                              CAlfLayout* aParentLayout = 0);

    /**

     * Constructor.

     */

    IMPORT_C CAlfAnchorLayout();

    /**

     * From CAlfLayout. Second-phase constructor.

     */

    IMPORT_C void ConstructL(CAlfControl& aOwner);

    /**

     * Virtual destructor.

     */

    IMPORT_C ~CAlfAnchorLayout();

    /**

     * Resets all the anchors.

     */

    IMPORT_C void Reset();

    /**

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

     *

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

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

     *

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

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

     * this layout, as specified by the other parameters.

     *

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

     * EAlfAnchorBottomRight), which specifies both size and position for the 

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

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

     * 

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

     * 

     * @note  After updating anchors, you should call 

     *        CAlfLayout::UpdateChildrenLayout(), to cause the anchors to be 

     *        applied to child positions and/or sizes.

     * 

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

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

     *

     * \code

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

     *	    iLayout->SetAnchor(EAlfAnchorTopLeft, 0,

     *	        EAlfAnchorOriginLeft, 

     *          EAlfAnchorOriginTop,

     *          EAlfAnchorMetricRelativeToSize, // With EAlfAnchorOriginLeft means that 0.0 goes to left edge, and 1.0 to the right

     *          EAlfAnchorMetricRelativeToSize, // With EAlfAnchorOriginTop means that 0.0 goes to top edge, and 1.0 to the bottom

     *          TAlfTimedPoint(0.25, 0.25));

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

     * 	    iLayout->SetAnchor(EAlfAnchorBottomRight, 0,

     *	        EAlfAnchorOriginRight, 

     *          EAlfAnchorOriginBottom,

     *   	EAlfAnchorMetricRelativeToSize, 

     *          EAlfAnchorMetricRelativeToSize,

     *          TAlfTimedPoint(-0.25, -0.25)); 

     * \endcode

     *

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

     *        layouts are evaluated pretty seldom.

     *

     * @param aAnchor       Type of the anchor (either EAlfAnchorTopLeft for the 

     *                      top left corner or EAlfAnchorBottomRight for bottom right

     *                      corner).

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

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

     *                      Defines the point inside the layout on which the 

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

     *                      EAlfAnchorOriginLeft (left edge), 

     *                      EAlfAnchorOriginHCenter (center) or

     *                      EAlfAnchorOriginRight (right edge).

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

     *                      Defines the point inside the layout on which the 

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

     *                      are EAlfAnchorOriginTop (top), EAlfAnchorOriginVCenter 

     *                      (center) and EAlfAnchorOriginBottom (bottom).

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

     *                      horizontal position: EAlfAnchorMetricAbsolute to use 

     *                      absolute pixels or EAlfAnchorMetricRelativeToSize to 

     *                      use normalized values relative to layout size.

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

     *                      EAlfAnchorMetricAbsolute to use absolute pixels or 

     *                      EAlfAnchorMetricRelativeToSize to use normalized 

     *                      values relative to layout size.     

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

     *                      applied using the metric specified with aHorizMetric 

     *                      and aVertMetric.

     * @return                   Error code

     *

     */

    IMPORT_C TInt SetAnchor(

        TAlfAnchor aAnchor, 

        TInt aOrdinal,

        TAlfAnchorOrigin aHorizOrigin,

        TAlfAnchorOrigin aVertOrigin,

        TAlfAnchorMetric aHorizMetric,

        TAlfAnchorMetric aVertMetric,

        const TAlfTimedPoint& aOffset);

    /**

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

	 *

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

	 *

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

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

     *                           Defines the point inside the layout on which the 

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

     *                           EAlfAnchorOriginLeft (left edge), 

     *                           EAlfAnchorOriginHCenter (center) or

     *                           EAlfAnchorOriginRight (right edge).

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

     *                           Defines the point inside the layout on which the 

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

     *                           are EAlfAnchorOriginTop (top), EAlfAnchorOriginVCenter 

     *                           (center) and EAlfAnchorOriginBottom (bottom).

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

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

     *                           Defines the point inside the layout on which the 

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

     *                           EAlfAnchorOriginLeft (left edge), 

     *                           EAlfAnchorOriginHCenter (center) or

     *                           EAlfAnchorOriginRight (right edge).

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

     *                           Defines the point inside the layout on which the 

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

     *                       	 are EAlfAnchorOriginTop (top), EAlfAnchorOriginVCenter 

     *                           (center) and EAlfAnchorOriginBottom (bottom).     

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

     * @return                   Error code.

     * 

	 *

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

	 */

    IMPORT_C TInt SetRelativeAnchorRect(TInt aOrdinal,

                                        TAlfAnchorOrigin aTlHorizOrigin,

                                        TAlfAnchorOrigin aTlVertOrigin,

                                        const TAlfRealPoint& aTopLeftOffset,

                                        TAlfAnchorOrigin aBrHorizOrigin,

                                        TAlfAnchorOrigin aBrVertOrigin,

                                        const TAlfRealPoint& aBottomRightOffset);

    /**

     * Undefines an anchor.

     * @see SetAnchor()

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

     *      example code

     */

    IMPORT_C void RemoveAnchor(TAlfAnchor aAnchor, TInt aOrdinal);

    /**

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

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

     * of anchors provide sufficient information for the anchor layout to 

     * determine the size and position of the child visual.

     *

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

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

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

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

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

     * supplying a box metric.

     *

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

     * EAlfAnchorTypeTopLeft and EAlfAnchorTypeBottomRight), taking care

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

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

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

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

     * specified as EAlfAnchorTypeSize; similarly the coordinates along

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

     * width or height anchors.

     *

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

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

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

     * using a TAlfMetric or related type. All available features of 

     * TAlfMetric may be used to affect the resulting position, providing the 

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

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

     * this layout.

     * 

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

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

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

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

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

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

     *      currenly supported. 

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

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

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

     *      removing them all and starting again.

     * @note  After updating anchors, you should call 

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

     *      applied to child positions and/or sizes.

     * 

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

     *

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

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

     * they all occupy the same position:

     *

     * \code

     *      // using edges...

     *	    iLayout->Attach(0, 

     *          EAlfAnchorTypeLeft,

     *          TAlfXYMetric(0.25, EAlfMetricNormalized),

     *          EAlfAnchorAttachmentOriginLeft);

     *	    iLayout->Attach(0, 

     *          EAlfAnchorTypeRight,

     *          TAlfXYMetric(-0.25, EAlfMetricNormalized),

     *          EAlfAnchorAttachmentOriginRight);

     *	    iLayout->Attach(0, 

     *          EAlfAnchorTypeTop,

     *          TAlfXYMetric(0.25, EAlfMetricNormalized),

     *          EAlfAnchorAttachmentOriginTop);

     *	    iLayout->Attach(0, 

     *          EAlfAnchorTypeBottom,

     *          TAlfXYMetric(-0.25, EAlfMetricNormalized),

     *          EAlfAnchorAttachmentOriginBottom);

     *

     *      // using corners...

     *	    iLayout->Attach(1, 

     *          EAlfAnchorTypeTopLeft,

     *          TAlfXYMetric(0.25, EAlfMetricNormalized),

     *          EAlfAnchorAttachmentOriginTopLeft);

     * 	    iLayout->Attach(1, 

     *	        EAlfAnchorTypeBottomRight, 

     *         TAlfXYMetric(-0.25, EAlfMetricNormalized),

     *	        EAlfAnchorAttachmentOriginBottomRight);

     * 

     *      // .. and using a box

     * 	    iLayout->Attach(2, TAlfBoxMetric(

     *          TAlfMetric(0.25, EAlfMetricNormalized),

     *          TAlfMetric(-0.25, EAlfMetricNormalized),

     *          TAlfMetric(0.25, EAlfMetricNormalized),

     *          TAlfMetric(-0.25, EAlfMetricNormalized)));

     * \endcode

     *

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

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

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

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

     * @param aAttachmentOrigin  Origin for the anchor offset.

     *      Defines the point inside the layout from which the 

     *      evaluation of the child's placement is based. 

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

     *      use the default value of EAlfAnchorAttachToParent in order to attach to parent

     * @return Error code

     *

     */

    IMPORT_C TInt Attach(

        TInt aOrdinal,

        TAlfAnchorType aType, 

        const TAlfMetric& aOffset,

        TAlfAnchorAttachmentOrigin aAttachmentOrigin,

        TInt aAttachmentOrdinal = EAlfAnchorAttachToParent);

    /** 

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

     * within this layout. 

     *

     * @see Attach() for all API documentation

     */

    IMPORT_C TInt Attach(

        TInt aOrdinal,

        TAlfAnchorType aType, 

        const TAlfXYMetric& aOffset,

        TAlfAnchorAttachmentOrigin aAttachmentOrigin = EAlfAnchorAttachmentOriginTopLeft,

        TInt aAttachmentOrdinal = EAlfAnchorAttachToParent);

    /** 

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

     * within this layout.

     *

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

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

     * detached.

     *

     * @see Attach() for all API documentation

     * @param aAttachmentOrigin if set to EAlfAnchorAttachmentOriginNone, each edge will 

     *        be attached to the corresponding edge

     */

    IMPORT_C TInt Attach(

        TInt aOrdinal,

        const TAlfBoxMetric& aOffset,

        TAlfAnchorAttachmentOrigin aAttachmentOrigin = EAlfAnchorAttachmentOriginTopLeft,

        TInt aAttachmentOrdinal = EAlfAnchorAttachToParent);

    /**

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

     * cannot be found.

     *

     * @see Attach()

     * 

     * @param aOrdinal the ordinal of the anchor to remove

     */

    IMPORT_C void Detach(TInt aOrdinal);

    /**

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

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

     * equal to zero:

     *

     * \code

     *      iLayout->Detach(0, EAlfAnchorTypeTopLeft);

     * \endcode

     *

     * @see Attach()

     * @note can be used to separately remove the edges 

     * that were attached using different combinations of types, 

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

     * confusion.

     *