|
1 /* |
|
2 * Copyright (c) 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: Curve paths are composed of path segments |
|
15 * and can be used as mapping functions, and in line visuals. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 |
|
21 #ifndef ALFCURVEPATH_H |
|
22 #define ALFCURVEPATH_H |
|
23 |
|
24 #include <e32base.h> |
|
25 #include <alf/alfmappingfunctions.h> |
|
26 |
|
27 class CAlfEnv; |
|
28 class CAlfGenComponent; |
|
29 |
|
30 /** |
|
31 * Curve paths are composed of path segments |
|
32 * and can be used as mapping functions, and to define the shape of line visuals. |
|
33 * |
|
34 * The curve path can be constructed from two primitives: arcs and lines. The arcs |
|
35 * and lines can be defined through methods AppendArcL() and AppendLineL() respectively. |
|
36 * |
|
37 * Coordinate values used when defining arcs and lines have to match the base unit type |
|
38 * of the visual associated with this curve path. So for instance, if this curve path |
|
39 * is used to define a layout using CAlfCurvePathLayout the definition of arcs and |
|
40 * lines have to match the base unit of the layout. If this path is used to define a |
|
41 * CAlfLineVisual, the coordinate values has to be defined in terms of base units affecting |
|
42 * the CAlfLineVisual. |
|
43 * |
|
44 * In the code example below a curve path is defined to a curve path layout. The curve |
|
45 * path is constructed from two line segments and one arc segment and defines a path |
|
46 * that starts from the bottom left corner of the layout and ends in the bottom right corner |
|
47 * of the layout. The total length of the curve path is 4.0 units. Notice that the coordinates |
|
48 * of the curve path are defined in base units of the layout. |
|
49 * |
|
50 * @code |
|
51 * // Create a new curve path layout |
|
52 * CAlfCurvePathLayout* layout = CAlfCurvePathLayout::AddNewL(*this); |
|
53 * layout->SetBaseUnit(TAlfMetric(1.0f, EAlfUnitNormalized)); |
|
54 |
|
55 * // Construct the layout path |
|
56 * CAlfCurvePath& path = layout->CurvePath(); |
|
57 * path.AppendLineL(TAlfRealPoint(0.0f, 1.0f), TAlfRealPoint(0.0f, 0.5f), 1); |
|
58 * path.AppendArcL(TAlfRealPoint(0.5f, 0.5f), TAlfRealSize(0.5f, 0.5f), 180.0f, 360.0f, 2); |
|
59 * path.AppendLineL(TAlfRealPoint(1.0f, 0.5f), TAlfRealPoint(1.0f, 1.0f), 1); |
|
60 * @endcode |
|
61 * |
|
62 * @lib alfclient.lib |
|
63 * @since S60 v3.2 |
|
64 */ |
|
65 NONSHARABLE_CLASS( CAlfCurvePath ): public CBase, public MAlfMappingFunction |
|
66 { |
|
67 |
|
68 public: |
|
69 |
|
70 /** |
|
71 * Construct a new curve path. |
|
72 * |
|
73 * @param aEnv The current environment. |
|
74 * @param aCurvePathProviderHandle Handle to the server side curve path provider. |
|
75 * If 0, the server side will create a new instance of CHuiCurvePath. |
|
76 * @return The new curve path. |
|
77 * @see CAlfGenComponent |
|
78 */ |
|
79 IMPORT_C static CAlfCurvePath* NewL( |
|
80 CAlfEnv& aEnv, |
|
81 TInt aCurvePathProviderHandle = 0 ); |
|
82 |
|
83 /** |
|
84 * Construct a new curve path, leave on cleanup stack. |
|
85 * |
|
86 * @param aEnv The current environment. |
|
87 * @param aCurvePathProviderHandle Handle to the server side curve path provider. |
|
88 * If 0, the server side will create a new instance of CHuiCurvePath. |
|
89 * @return The new curve path. |
|
90 * @see CAlfGenComponent |
|
91 */ |
|
92 IMPORT_C static CAlfCurvePath* NewLC( |
|
93 CAlfEnv& aEnv, |
|
94 TInt aCurvePathProviderHandle = 0 ); |
|
95 |
|
96 /** |
|
97 * Destructor. |
|
98 */ |
|
99 IMPORT_C virtual ~CAlfCurvePath(); |
|
100 |
|
101 /** |
|
102 * Resets the path by removing all segments. |
|
103 */ |
|
104 IMPORT_C void Reset(); |
|
105 |
|
106 /** |
|
107 * Enables or disables looping of the path. Looping means that all |
|
108 * positions are wrapped to the path, so that, e.g., positions past |
|
109 * the end are wrapped to the beginning of the path. Looping is enabled by |
|
110 * default. |
|
111 */ |
|
112 IMPORT_C void EnableLoop(TBool aEnable = ETrue); |
|
113 |
|
114 /** |
|
115 * Determines if the path is looping. |
|
116 */ |
|
117 IMPORT_C TBool Loop() const; |
|
118 |
|
119 /** |
|
120 * Sets the position that is at path location zero. |
|
121 * |
|
122 * @param aPosOrigin Added to positions when evaluating. |
|
123 */ |
|
124 IMPORT_C void SetOrigin(TReal32 aPosOrigin) __SOFTFP; |
|
125 |
|
126 /** |
|
127 * Appends a line segment to the path. Note that the coordinate values should |
|
128 * match to the metrics unit type of the visual that uses this class. |
|
129 * @deprecated Use the AppendLineL() - method with real values instead. |
|
130 * |
|
131 * @param aStart Start point |
|
132 * @param aEnd End point |
|
133 * @param aLength Negative length means that the length will be the |
|
134 * actual length of the line segment. |
|
135 */ |
|
136 IMPORT_C void AppendLineL( |
|
137 const TPoint& aStart, |
|
138 const TPoint& aEnd, |
|
139 TReal32 aLength = -1) __SOFTFP; |
|
140 |
|
141 /** |
|
142 * Appends a line segment to the path. Note that the coordinate values should |
|
143 * match to the metrics unit type of the visual that uses this class. |
|
144 * |
|
145 * @param aStart Start point |
|
146 * @param aEnd End point |
|
147 * @param aLength Negative length means that the length will be the |
|
148 * actual length of the line segment. |
|
149 */ |
|
150 IMPORT_C void AppendLineL( |
|
151 const TAlfRealPoint& aStart, |
|
152 const TAlfRealPoint& aEnd, |
|
153 TReal32 aLength = -1) __SOFTFP; |
|
154 |
|
155 /** |
|
156 * Appends a curve segment to the path. Note that the coordinate values should |
|
157 * match to the metrics unit type of the visual that uses this class. The curve segment is defined |
|
158 * as a segment of an ellipse. |
|
159 * |
|
160 * The span of the arc is defined in a range of degrees traversed on the |
|
161 * ellipse. The direction of zero degrees points towards the positive x - axis and |
|
162 * 180 degrees points towards negative x - axis. The degrees are specified in |
|
163 * clockwise manner so that 90 degrees points towards the positive y - axis (down). |
|
164 * |
|
165 * @deprecated Use the AppendArcL(const TAlfRealPoint&, const TAlfRealSize&, TReal32, TReal32, TReal32) - method instead. |
|
166 * |
|
167 * @param aOrigin Origin of the arc ellipse. |
|
168 * @param aSize Horiz and vert radii of the arc ellipse. |
|
169 * @param aStartAngle Start angle of the arc in degrees. |
|
170 * @param aEndAngle End angle of the arc in degrees. |
|
171 * @param aLength Negative length means that the length will be the |
|
172 * actual length of the arc. |
|
173 */ |
|
174 IMPORT_C void AppendArcL( |
|
175 const TPoint& aOrigin, |
|
176 const TSize& aSize, |
|
177 TReal32 aStartAngle, |
|
178 TReal32 aEndAngle, |
|
179 TReal32 aLength = -1) __SOFTFP; |
|
180 |
|
181 /** |
|
182 * Appends a curve segment to the path. Note that the coordinate values should |
|
183 * match to the metrics unit type of the visual that uses this class. The curve segment is defined |
|
184 * as a segment of an ellipse. |
|
185 * |
|
186 * The span of the arc is defined in a range of degrees traversed on the circle of an |
|
187 * ellipse. The direction of zero degrees points towards the positive x - axis and |
|
188 * 180 degrees points towards negative x - axis. The degrees are specified in |
|
189 * clockwise manner so that 90 degrees points towards the positive y - axis (down). |
|
190 * |
|
191 * Image below depicts how a curve segment can be defined in the path. |
|
192 * |
|
193 * @image html CAlfCurvePath_ArcDefinition.png "Curve segment defined using AppendArcL()." |
|
194 * |
|
195 * @param aOrigin Origin of the arc ellipse. |
|
196 * @param aSize Horiz and vert radii of the arc ellipse. |
|
197 * @param aStartAngle Start angle of the arc in degrees. |
|
198 * @param aEndAngle End angle of the arc in degrees. |
|
199 * @param aLength Negative length means that the length will be the |
|
200 * actual length of the arc. |
|
201 */ |
|
202 IMPORT_C void AppendArcL( |
|
203 const TAlfRealPoint& aOrigin, |
|
204 const TAlfRealSize& aSize, |
|
205 TReal32 aStartAngle, |
|
206 TReal32 aEndAngle, |
|
207 TReal32 aLength = -1) __SOFTFP; |
|
208 |
|
209 /** |
|
210 * Determines the total length of the path. |
|
211 * |
|
212 * @return Length of the curve. |
|
213 */ |
|
214 IMPORT_C TReal32 Length() const __SOFTFP; |
|
215 |
|
216 /** |
|
217 * Evaluates a point along the curve path. |
|
218 * |
|
219 * @param aPos Position along the path. |
|
220 * @param aPoint Returns the X and Y coordinates of the point on the path. |
|
221 */ |
|
222 IMPORT_C void Evaluate(TReal32 aPos, TAlfRealPoint& aPoint) const __SOFTFP; |
|
223 |
|
224 /** |
|
225 * Get offset of the entire path. |
|
226 * |
|
227 * @return Offset |
|
228 * @see SetOffset() |
|
229 */ |
|
230 IMPORT_C const TAlfTimedPoint& Offset() const; |
|
231 |
|
232 /** |
|
233 * Set offset of the entire path. |
|
234 * Sets the translation (ie. origin) of the path. Default is (0,0). |
|
235 * |
|
236 * @param aOffset Offset of the path. |
|
237 */ |
|
238 IMPORT_C void SetOffset( const TAlfTimedPoint& aOffset ); |
|
239 |
|
240 // From MAlfMappingFunction |
|
241 |
|
242 /** |
|
243 * From MAlfMappingFunction |
|
244 * Return mapping function ID. |
|
245 * @return The mapping function identifier of this curve path. NULL if this class |
|
246 * was constructed with an existing CAlfGenComponent. |
|
247 * @see CAlfGenComponent::Identifier() |
|
248 * @see NewL() |
|
249 */ |
|
250 IMPORT_C TInt MappingFunctionIdentifier() const; |
|
251 |
|
252 /** |
|
253 * From MAlfMappingFunction |
|
254 * Evaluate x/y component on a position on the path. |
|
255 * @param aValue Position along the path to get the coordiantes of. |
|
256 * @param aMode If equal to 0, evaluates X component, otherwise evaluates Y component. |
|
257 * @return The x or y position evaluated for the given position on the curve. |
|
258 */ |
|
259 IMPORT_C TReal32 MapValue(TReal32 aValue, TInt aMode) const __SOFTFP; |
|
260 |
|
261 private: |
|
262 |
|
263 /** |
|
264 * Constructor. |
|
265 */ |
|
266 CAlfCurvePath(); |
|
267 |
|
268 /** |
|
269 * Second phase constructor. |
|
270 */ |
|
271 void ConstructL( |
|
272 CAlfEnv& aEnv, |
|
273 TInt aCurvePathProviderHandle ); |
|
274 |
|
275 private: // data |
|
276 |
|
277 /** Private data.*/ |
|
278 struct TPrivateData; |
|
279 |
|
280 /** Private data.*/ |
|
281 TPrivateData* iData; |
|
282 }; |
|
283 |
|
284 #endif // ALFCURVEPATH_H |