diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_visual_api/inc/alf/alfcurvepath.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfcurvepath.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,284 @@ +/* +* Copyright (c) 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: Curve paths are composed of path segments +* and can be used as mapping functions, and in line visuals. +* +*/ + + + +#ifndef ALFCURVEPATH_H +#define ALFCURVEPATH_H + +#include +#include + +class CAlfEnv; +class CAlfGenComponent; + +/** + * Curve paths are composed of path segments + * and can be used as mapping functions, and to define the shape of line visuals. + * + * The curve path can be constructed from two primitives: arcs and lines. The arcs + * and lines can be defined through methods AppendArcL() and AppendLineL() respectively. + * + * Coordinate values used when defining arcs and lines have to match the base unit type + * of the visual associated with this curve path. So for instance, if this curve path + * is used to define a layout using CAlfCurvePathLayout the definition of arcs and + * lines have to match the base unit of the layout. If this path is used to define a + * CAlfLineVisual, the coordinate values has to be defined in terms of base units affecting + * the CAlfLineVisual. + * + * In the code example below a curve path is defined to a curve path layout. The curve + * path is constructed from two line segments and one arc segment and defines a path + * that starts from the bottom left corner of the layout and ends in the bottom right corner + * of the layout. The total length of the curve path is 4.0 units. Notice that the coordinates + * of the curve path are defined in base units of the layout. + * + * @code + * // Create a new curve path layout + * CAlfCurvePathLayout* layout = CAlfCurvePathLayout::AddNewL(*this); + * layout->SetBaseUnit(TAlfMetric(1.0f, EAlfUnitNormalized)); + + * // Construct the layout path + * CAlfCurvePath& path = layout->CurvePath(); + * path.AppendLineL(TAlfRealPoint(0.0f, 1.0f), TAlfRealPoint(0.0f, 0.5f), 1); + * path.AppendArcL(TAlfRealPoint(0.5f, 0.5f), TAlfRealSize(0.5f, 0.5f), 180.0f, 360.0f, 2); + * path.AppendLineL(TAlfRealPoint(1.0f, 0.5f), TAlfRealPoint(1.0f, 1.0f), 1); + * @endcode + * + * @lib alfclient.lib + * @since S60 v3.2 + */ +NONSHARABLE_CLASS( CAlfCurvePath ): public CBase, public MAlfMappingFunction + { + +public: + + /** + * Construct a new curve path. + * + * @param aEnv The current environment. + * @param aCurvePathProviderHandle Handle to the server side curve path provider. + * If 0, the server side will create a new instance of CHuiCurvePath. + * @return The new curve path. + * @see CAlfGenComponent + */ + IMPORT_C static CAlfCurvePath* NewL( + CAlfEnv& aEnv, + TInt aCurvePathProviderHandle = 0 ); + + /** + * Construct a new curve path, leave on cleanup stack. + * + * @param aEnv The current environment. + * @param aCurvePathProviderHandle Handle to the server side curve path provider. + * If 0, the server side will create a new instance of CHuiCurvePath. + * @return The new curve path. + * @see CAlfGenComponent + */ + IMPORT_C static CAlfCurvePath* NewLC( + CAlfEnv& aEnv, + TInt aCurvePathProviderHandle = 0 ); + + /** + * Destructor. + */ + IMPORT_C virtual ~CAlfCurvePath(); + + /** + * Resets the path by removing all segments. + */ + IMPORT_C void Reset(); + + /** + * Enables or disables looping of the path. Looping means that all + * positions are wrapped to the path, so that, e.g., positions past + * the end are wrapped to the beginning of the path. Looping is enabled by + * default. + */ + IMPORT_C void EnableLoop(TBool aEnable = ETrue); + + /** + * Determines if the path is looping. + */ + IMPORT_C TBool Loop() const; + + /** + * Sets the position that is at path location zero. + * + * @param aPosOrigin Added to positions when evaluating. + */ + IMPORT_C void SetOrigin(TReal32 aPosOrigin) __SOFTFP; + + /** + * Appends a line segment to the path. Note that the coordinate values should + * match to the metrics unit type of the visual that uses this class. + * @deprecated Use the AppendLineL() - method with real values instead. + * + * @param aStart Start point + * @param aEnd End point + * @param aLength Negative length means that the length will be the + * actual length of the line segment. + */ + IMPORT_C void AppendLineL( + const TPoint& aStart, + const TPoint& aEnd, + TReal32 aLength = -1) __SOFTFP; + + /** + * Appends a line segment to the path. Note that the coordinate values should + * match to the metrics unit type of the visual that uses this class. + * + * @param aStart Start point + * @param aEnd End point + * @param aLength Negative length means that the length will be the + * actual length of the line segment. + */ + IMPORT_C void AppendLineL( + const TAlfRealPoint& aStart, + const TAlfRealPoint& aEnd, + TReal32 aLength = -1) __SOFTFP; + + /** + * Appends a curve segment to the path. Note that the coordinate values should + * match to the metrics unit type of the visual that uses this class. The curve segment is defined + * as a segment of an ellipse. + * + * The span of the arc is defined in a range of degrees traversed on the + * ellipse. The direction of zero degrees points towards the positive x - axis and + * 180 degrees points towards negative x - axis. The degrees are specified in + * clockwise manner so that 90 degrees points towards the positive y - axis (down). + * + * @deprecated Use the AppendArcL(const TAlfRealPoint&, const TAlfRealSize&, TReal32, TReal32, TReal32) - method instead. + * + * @param aOrigin Origin of the arc ellipse. + * @param aSize Horiz and vert radii of the arc ellipse. + * @param aStartAngle Start angle of the arc in degrees. + * @param aEndAngle End angle of the arc in degrees. + * @param aLength Negative length means that the length will be the + * actual length of the arc. + */ + IMPORT_C void AppendArcL( + const TPoint& aOrigin, + const TSize& aSize, + TReal32 aStartAngle, + TReal32 aEndAngle, + TReal32 aLength = -1) __SOFTFP; + + /** + * Appends a curve segment to the path. Note that the coordinate values should + * match to the metrics unit type of the visual that uses this class. The curve segment is defined + * as a segment of an ellipse. + * + * The span of the arc is defined in a range of degrees traversed on the circle of an + * ellipse. The direction of zero degrees points towards the positive x - axis and + * 180 degrees points towards negative x - axis. The degrees are specified in + * clockwise manner so that 90 degrees points towards the positive y - axis (down). + * + * Image below depicts how a curve segment can be defined in the path. + * + * @image html CAlfCurvePath_ArcDefinition.png "Curve segment defined using AppendArcL()." + * + * @param aOrigin Origin of the arc ellipse. + * @param aSize Horiz and vert radii of the arc ellipse. + * @param aStartAngle Start angle of the arc in degrees. + * @param aEndAngle End angle of the arc in degrees. + * @param aLength Negative length means that the length will be the + * actual length of the arc. + */ + IMPORT_C void AppendArcL( + const TAlfRealPoint& aOrigin, + const TAlfRealSize& aSize, + TReal32 aStartAngle, + TReal32 aEndAngle, + TReal32 aLength = -1) __SOFTFP; + + /** + * Determines the total length of the path. + * + * @return Length of the curve. + */ + IMPORT_C TReal32 Length() const __SOFTFP; + + /** + * Evaluates a point along the curve path. + * + * @param aPos Position along the path. + * @param aPoint Returns the X and Y coordinates of the point on the path. + */ + IMPORT_C void Evaluate(TReal32 aPos, TAlfRealPoint& aPoint) const __SOFTFP; + + /** + * Get offset of the entire path. + * + * @return Offset + * @see SetOffset() + */ + IMPORT_C const TAlfTimedPoint& Offset() const; + + /** + * Set offset of the entire path. + * Sets the translation (ie. origin) of the path. Default is (0,0). + * + * @param aOffset Offset of the path. + */ + IMPORT_C void SetOffset( const TAlfTimedPoint& aOffset ); + + // From MAlfMappingFunction + + /** + * From MAlfMappingFunction + * Return mapping function ID. + * @return The mapping function identifier of this curve path. NULL if this class + * was constructed with an existing CAlfGenComponent. + * @see CAlfGenComponent::Identifier() + * @see NewL() + */ + IMPORT_C TInt MappingFunctionIdentifier() const; + + /** + * From MAlfMappingFunction + * Evaluate x/y component on a position on the path. + * @param aValue Position along the path to get the coordiantes of. + * @param aMode If equal to 0, evaluates X component, otherwise evaluates Y component. + * @return The x or y position evaluated for the given position on the curve. + */ + IMPORT_C TReal32 MapValue(TReal32 aValue, TInt aMode) const __SOFTFP; + +private: + + /** + * Constructor. + */ + CAlfCurvePath(); + + /** + * Second phase constructor. + */ + void ConstructL( + CAlfEnv& aEnv, + TInt aCurvePathProviderHandle ); + +private: // data + + /** Private data.*/ + struct TPrivateData; + + /** Private data.*/ + TPrivateData* iData; + }; + +#endif // ALFCURVEPATH_H