/*
* 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 <e32base.h>
#include <alf/alfmappingfunctions.h>
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