diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_visual_api/inc/alf/alfanchorlayout.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfanchorlayout.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,569 @@ +/* +* 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 + +/** 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. + * + * @param aOrdinal the ordinal of the anchor to remove + * @param aType the edge relating to the anchor to remove + */ + IMPORT_C void Detach(TInt aOrdinal, TAlfAnchorType aType); + + /** + * From CAlfVisual + * @see CAlfVisual + */ + IMPORT_C void RemoveAndDestroyAllD(); + IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0); + IMPORT_C CAlfVisual* FindTag(const TDesC8& aTag); + + /** + * From CAlfLayout + * @see CAlfLayout + */ + IMPORT_C TAlfXYMetric BaseUnit() const; + + +protected: + /** + * From CAlfVisual + * @see CAlfVisual + */ + IMPORT_C void DoRemoveAndDestroyAllD(); + IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams); + + +private: + + // Private data structure. Owned. + struct TAnchorLayoutPrivateData; + TAnchorLayoutPrivateData* iAnchorLayoutData; + + }; + + + +#endif // C_ALFANCHORLAYOUT_H