|
1 /* |
|
2 * Copyright (c) 2006-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: Defines CHuiLayout class. Layouts are visuals that manage |
|
15 * the placement of a set of child visuals. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 |
|
21 #ifndef __HUILAYOUT_H__ |
|
22 #define __HUILAYOUT_H__ |
|
23 |
|
24 |
|
25 #include <e32base.h> |
|
26 #include <uiacceltk/HuiVisual.h> |
|
27 #include <uiacceltk/huimetric.h> |
|
28 |
|
29 /* Forward declarations */ |
|
30 class CHuiEnv; |
|
31 class CHuiControl; |
|
32 |
|
33 |
|
34 /** Layout types. */ |
|
35 enum THuiLayoutType |
|
36 { |
|
37 EHuiLayoutTypeLayout, |
|
38 EHuiLayoutTypeFlow, |
|
39 EHuiLayoutTypeGrid, |
|
40 EHuiLayoutTypeApp, |
|
41 EHuiLayoutTypeAnchor |
|
42 }; |
|
43 |
|
44 /** |
|
45 * Layouts are visuals that manage the placement of a set of child visuals |
|
46 * (or other layouts). |
|
47 * |
|
48 * Layouts are responsible for setting the positions and sizes of their |
|
49 * child visuals. Each layout can define a position, a size, or both |
|
50 * (or neither) for their children. |
|
51 * |
|
52 * Layouts use the children's ordinal numbers to determine where each of |
|
53 * them should be placed. For example, a grid layout could define that the |
|
54 * top row contains children with ordinals 0..3, from left to right. The |
|
55 * second row could then contain the children 4..7. When the order of the |
|
56 * child visuals changes within their parent layout, the parent layout |
|
57 * will recalculate the positions and sizes of the affected children. |
|
58 * |
|
59 * When the size of a layout changes, it will immediately recalculate the |
|
60 * layout of its children. The transition time that is specified in the |
|
61 * size transition of the layout is used when setting the targets of the |
|
62 * children's new positions and sizes. |
|
63 * |
|
64 * Layouts are able to notify their controls when their size is changed. |
|
65 * These notifications are needed because the size of a layout is not known |
|
66 * until the display is refreshed. This means that the <strong>size of a layout |
|
67 * is not available when your controls ConstructL is executed</strong>, unless |
|
68 * it is explicitly set. The notifications are also handy because they allow |
|
69 * the controls to respond to dynamic screen size changes. So unless if the |
|
70 * whole screen is not used for the layout, the notifications are the only way |
|
71 * to do calculations based on the layout size. |
|
72 * |
|
73 * To make the control receive layout update notifications call: |
|
74 * |
|
75 * <code> |
|
76 * layout->SetFlags(EHuiVisualFlagLayoutUpdateNotification); |
|
77 * </code> |
|
78 * |
|
79 * .. and override VisualLayoutUpdated() method in your control. |
|
80 * |
|
81 * @see SetSize() |
|
82 * @see SetFlags() |
|
83 * @see CHuiControl::VisualLayoutUpdated() |
|
84 * |
|
85 * Each layout defines its own local coordinate system used for interpreting |
|
86 * the positions and sizes of its child visuals. The base unit of the |
|
87 * coordinate system is defined with the SetBaseUnit() method, which sets a |
|
88 * THuiXYMetric to use as the basis for all coordinate calculations. The default |
|
89 * metric is [1px, 1px] which corresponds to pixels on the display. |
|
90 * |
|
91 * The local coordinate system of a layout can be mirrored horizontally and/or |
|
92 * vertically by using a negative magnitude in the relevant THuiMetric of the |
|
93 * base unit. Note that this will only affect the local coordinate system |
|
94 * of the layout: the contents of the child visuals or child layouts will not |
|
95 * be mirrored. Visual mirroring should be done with a CHuiTransformation, |
|
96 * and child layouts can be mirrored by further application of the negative |
|
97 * base unit metrics. In order to enable a layout to automatically mirror the |
|
98 * horizontal component of the base unit based on locale mirroring, set the visual flag |
|
99 * @c EHuiVisualFlagAutomaticLocaleMirroringEnabled, note that it is necessary |
|
100 * to set this flag for each layout for which this feature is required. |
|
101 * |
|
102 * To create to a fully scalable UI, the appropriate base unit metrics and |
|
103 * layout visuals must be used. For example, the EHuiUnitS60 metric unit is |
|
104 * dependent on the platform-specified measurement units for layout. |
|
105 * CHuiGridLayout and CHuiAnchorLayout provide support for pixel-independent |
|
106 * placement of their children. |
|
107 * |
|
108 * @see CHuiAnchorLayout |
|
109 * @see CHuiGridLayout |
|
110 * |
|
111 * Applications that need more complex layouts should derive their own |
|
112 * CHuiLayout based classes that implement the necessary layout calculations. |
|
113 * In many cases, however, a combination of some of the built-in layout classes |
|
114 * such as anchor and grid layouts will be sufficient. |
|
115 */ |
|
116 class CHuiLayout : public CHuiVisual |
|
117 { |
|
118 public: |
|
119 |
|
120 enum TExpansionFlags |
|
121 { |
|
122 /** Not expanding in any direction. */ |
|
123 EExpandNone = 0, |
|
124 |
|
125 /** Expands horizontally. */ |
|
126 EExpandHorizontally = 1, |
|
127 |
|
128 /** Expands vertically. */ |
|
129 EExpandVertically = 2 |
|
130 }; |
|
131 |
|
132 |
|
133 /** @beginAPI */ |
|
134 |
|
135 /* Constructors and destructor. */ |
|
136 |
|
137 /** |
|
138 * Construct a new basic layout and give its ownership to a control. |
|
139 * Note that CHuiLayout has no real layout functionality: its children |
|
140 * must be laid out manually. |
|
141 * |
|
142 * @param aOwnerControl Owner control. |
|
143 * @param aParentLayout Parent layout for the new layout. |
|
144 */ |
|
145 IMPORT_C static CHuiLayout* AddNewL(CHuiControl& aOwnerControl, |
|
146 CHuiLayout* aParentLayout = 0); |
|
147 |
|
148 /** |
|
149 * Constructor. |
|
150 */ |
|
151 IMPORT_C CHuiLayout(MHuiVisualOwner& aOwner); |
|
152 |
|
153 /** |
|
154 * Destructor. |
|
155 */ |
|
156 IMPORT_C ~CHuiLayout(); |
|
157 |
|
158 /** |
|
159 * Second-phase constructor from CHuiVisual, must be called in deriving class |
|
160 */ |
|
161 IMPORT_C void ConstructL(); |
|
162 |
|
163 |
|
164 |
|
165 /* Methods. */ |
|
166 |
|
167 /** |
|
168 * From CHuiVisual. Removes this layout from its owner and and destroys the layout. |
|
169 * Also removes the entire hierarchy of child visuals and destroys all |
|
170 * of them. |
|
171 */ |
|
172 IMPORT_C void RemoveAndDestroyAllD(); |
|
173 |
|
174 /** |
|
175 * From CHuiVisual. Finds a visual whose tag descriptor contains a specific tag. |
|
176 * Checks self first, then looks through the child visuals. |
|
177 * |
|
178 * CHuiLayout::FindTag() extends upon the basic implementation |
|
179 * in CHuiVisual::FindTag() by adding recursive visual hierarchy |
|
180 * searching. |
|
181 * |
|
182 * @param aTag Tag to look for. If this tag is found as a part of a |
|
183 * visual's colon-separated tag descriptor, it is treated |
|
184 * as a match and the visual is returned. |
|
185 * The tag to look for cannot contain separator characters (:). |
|
186 * |
|
187 * @return Visual whose tag descriptor matches the tag. <code>NULL</code>, |
|
188 * if no such visual could be found. If a visual is returned, |
|
189 * it will either be this visual or one of its descendants. |
|
190 * |
|
191 * @see CHuiVisual::Tag() |
|
192 * @see CHuiVisual::SetTagL() |
|
193 * @see CHuiVisual::IsTagged() |
|
194 * @see CHuiVisual::FindTag() |
|
195 */ |
|
196 IMPORT_C CHuiVisual* FindTag(const TDesC8& aTag); |
|
197 |
|
198 /** |
|
199 * Append a new visual to the layout. If the visual is already a member of |
|
200 * some other layout, it will be removed from the old layout first. |
|
201 * |
|
202 * @param aVisual Visual to append. |
|
203 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
204 * |
|
205 * @todo Add a method for appending multiple visuals in one set, so that |
|
206 * they only cause a single layout update. |
|
207 */ |
|
208 IMPORT_C void AppendL(CHuiVisual* aVisual, TInt aLayoutTransitionTime = 0); |
|
209 |
|
210 /** |
|
211 * Insert a new visual to the layout, at specified position (position 0 is the first, |
|
212 * Count() -1 is the last). If the visual is already a member of |
|
213 * some other layout, it will be removed from the old layout first. |
|
214 * |
|
215 * @param aVisual Visual to append. |
|
216 * @param TInt Position to insert. This is the new ordinal number of the visual. |
|
217 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
218 */ |
|
219 IMPORT_C void InsertL(CHuiVisual* aVisual, TInt aPosition, TInt aLayoutTransitionTime = 0); |
|
220 |
|
221 /** |
|
222 * Remove a visual from the layout. |
|
223 * |
|
224 * @param aVisual Visual to remove. |
|
225 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
226 * @todo Add a method for removing multiple visuals in one set, so that |
|
227 * they only cause a single layout update. |
|
228 */ |
|
229 IMPORT_C void Remove(CHuiVisual* aVisual, TInt aLayoutTransitionTime = 0); |
|
230 |
|
231 /** |
|
232 * From CHuiVisual. Returns the number of child visuals in the layout. |
|
233 */ |
|
234 IMPORT_C TInt Count() const; |
|
235 |
|
236 /** |
|
237 * From CHuiVisual. Returns a child visual. |
|
238 * |
|
239 * @param aIndex Index of the child visual. |
|
240 * |
|
241 * @return Reference to a child visual. |
|
242 */ |
|
243 IMPORT_C CHuiVisual& Visual(TInt aIndex) const; |
|
244 |
|
245 /** |
|
246 * Finds a visual's index. |
|
247 * |
|
248 * @param aVisual Visual to look for. |
|
249 * |
|
250 * @return Index of the visual, or <code>KErrNotFound</code>. |
|
251 */ |
|
252 IMPORT_C TInt FindVisual(const CHuiVisual* aVisual) const; |
|
253 |
|
254 |
|
255 /** |
|
256 * From CHuiVisual. Sets the position of the layout. |
|
257 * @param aPos Target position, in the local coordinate system as |
|
258 * defined by the parent layout (or the display, |
|
259 * if there is no parent). |
|
260 * @param aTransitionTime Transition time in milliseconds. |
|
261 */ |
|
262 IMPORT_C void SetPos(const THuiRealPoint& aPos, TInt aTransitionTime = 0); |
|
263 |
|
264 /** |
|
265 * From CHuiVisual. Change the size of the layout. Children's positions and sizes are |
|
266 * updated accordingly. Each layout class is responsible for determining |
|
267 * how to update children's layout. |
|
268 * |
|
269 * @param aSize Size to set the layout to. |
|
270 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
271 */ |
|
272 IMPORT_C void SetSize(const THuiRealSize& aSize, TInt aTransitionTime = 0); |
|
273 |
|
274 /** |
|
275 * From CHuiVisual. Update the layout of all children. Subclasses can call this to |
|
276 * recalculate the layout of all children. |
|
277 * |
|
278 * @param aTransitionTime Time for layout transition. |
|
279 */ |
|
280 IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0); |
|
281 |
|
282 |
|
283 /** |
|
284 * New virtual method. Update the layout of one child visual. |
|
285 * |
|
286 * @param aIndex Child visual index. |
|
287 * @param aTransitionTime Time for layout transition. |
|
288 */ |
|
289 IMPORT_C virtual void UpdateChildLayout(TInt aIndex, TInt aTransitionTime = 0); |
|
290 |
|
291 /** |
|
292 * Sets the inner padding of the layout. This is typically the amount |
|
293 * of empty space between child visuals in the layout. |
|
294 * |
|
295 * @param aInnerPadding Inner padding (e.g., column, row separation). |
|
296 */ |
|
297 IMPORT_C void SetInnerPadding(const TPoint& aInnerPadding); |
|
298 |
|
299 /** |
|
300 * Sets the inner padding of the layout. This is typically the amount |
|
301 * of empty space between child visuals in the layout. |
|
302 * |
|
303 * @note as paddings are relative to the layout visual, if relative units are required, |
|
304 * it is advisable to use EHuiUnitRelativeToMySize so that the paddings are relative |
|
305 * to the size of this layout visual |
|
306 * |
|
307 * @param aInnerPadding Inner padding, using metrics. |
|
308 */ |
|
309 IMPORT_C void SetInnerPadding(const THuiXYMetric& aInnerPadding); |
|
310 |
|
311 /** |
|
312 * Returns the current inner padding. |
|
313 */ |
|
314 IMPORT_C const THuiXYMetric& InnerPadding() const; |
|
315 |
|
316 /** |
|
317 * Returns the inner horizontal padding. |
|
318 * @deprecated This is useless, use InnerPaddingInBaseUnits() instead. |
|
319 */ |
|
320 IMPORT_C TInt HorizontalInnerPadding() const; |
|
321 |
|
322 /** |
|
323 * Returns the inner vertical padding. |
|
324 * @deprecated This is useless, use InnerPaddingInBaseUnits() instead. |
|
325 */ |
|
326 IMPORT_C TInt VerticalInnerPadding() const; |
|
327 |
|
328 /** |
|
329 * Returns the inner padding converted to the base units of this layout. |
|
330 * These can be summed with the positions and sizes of the layout's children. |
|
331 */ |
|
332 IMPORT_C THuiRealPoint InnerPaddingInBaseUnits() const __SOFTFP; |
|
333 |
|
334 /** |
|
335 * Enables or disables scrolling in the layout. An offset |
|
336 * for the origin of the layout can be defined using |
|
337 * ScrollOffset() - method and manipulating the THuiTimedPoint |
|
338 * returned by that method. |
|
339 * |
|
340 * Scroll offset, unlike other layout parameters, is not directly applied |
|
341 * to layout children when UpdateChildrenLayout() is called. Instead, the |
|
342 * scroll offset is taken into consideration when individual child visual |
|
343 * display rectangles are calculated. This way the scroll offset is directly |
|
344 * applied to dirty rectangle calculations as well as to visual content |
|
345 * rectangle calculations when visuals are drawn. |
|
346 * |
|
347 * @param aScrolling <code>ETrue</code> to enable scrolling, |
|
348 * <code>EFalse</code> to disable. |
|
349 */ |
|
350 IMPORT_C void EnableScrollingL(TBool aScrolling = ETrue); |
|
351 |
|
352 /** |
|
353 * Indicates whether scrolling is enabled in this layout. |
|
354 * @see EnableScrolling() |
|
355 * |
|
356 * @return ETrue if scrolling is enabled, EFalse otherwise. |
|
357 */ |
|
358 IMPORT_C TBool Scrolling() const; |
|
359 |
|
360 /** |
|
361 * Returns the scroll offset of the layout. The scroll offset is in |
|
362 * layout's base units. The scroll offset has to be enabled before this |
|
363 * method is called. |
|
364 * @see EnableScrollingL() |
|
365 * |
|
366 * @return Reference to timed point that defines the scroll offset. |
|
367 * |
|
368 * @panic THuiPanic::ELayoutNotScrolling Scrolling is not enabled. |
|
369 */ |
|
370 IMPORT_C THuiTimedPoint& ScrollOffset(); |
|
371 IMPORT_C const THuiTimedPoint& ScrollOffset() const; |
|
372 |
|
373 /** |
|
374 * Specifies the scroll offset of this layout. The scroll offset |
|
375 * is defined in layout's base units. The scroll offset has to be |
|
376 * enabled before this method is called. |
|
377 * @see BaseUnit() |
|
378 * @see EnableScrollingL() |
|
379 * |
|
380 * @param aOffset Offset in layout's base units. |
|
381 * @param aTransitionTime Time when the offset is to be reached in milliseconds. |
|
382 */ |
|
383 IMPORT_C void SetScrollOffsetInBaseUnits(const THuiRealPoint& aOffset, TInt aTransitionTime = 0); |
|
384 |
|
385 /** |
|
386 * Determines the virtual size of the layout. The virtual size may be |
|
387 * larger than the actual size. The virtual size is updated automatically |
|
388 * when the layout's children are positioned. |
|
389 * |
|
390 * @return Virtual size. |
|
391 * |
|
392 * @panic THuiPanic::ELayoutNotScrolling Scrolling is not enabled. |
|
393 */ |
|
394 IMPORT_C TSize VirtualSize() const; |
|
395 |
|
396 /** |
|
397 * Layout is calculated according the ordinals. The effective ordinal |
|
398 * may not be the same as the real child ordinal, because some visuals |
|
399 * are laid out manually. |
|
400 * |
|
401 * @return Effective ordinal for the child visual. |
|
402 * |
|
403 * @panic THuiPanic::ELayoutChildVisualNotFound aVisual is not a child |
|
404 * of this layout. |
|
405 */ |
|
406 IMPORT_C TInt EffectiveLayoutOrdinal(const CHuiVisual& aVisual) const; |
|
407 |
|
408 /** |
|
409 * Moves the given child visual to specific position in the layout's list |
|
410 * of child visuals. Affects the drawing order (last child is drawn last), |
|
411 * and possibly the final laid out position and size of the visual. |
|
412 * This is due to that many layout implementations calculate the |
|
413 * positioning of their children based on child's order number |
|
414 * in the list. |
|
415 * |
|
416 * Causes layout recalculation. |
|
417 * |
|
418 * @param aVisual Child visual to move. |
|
419 * @param aPosition New position (and ordinal number) |
|
420 * in the child list (0 = first, Count()-1 = last). |
|
421 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
422 * @see MoveVisualToBack() |
|
423 * @see MoveVisualToFront() |
|
424 */ |
|
425 IMPORT_C void Reorder(CHuiVisual& aVisual, TInt aPosition, TInt aLayoutTransitionTime = 0); |
|
426 |
|
427 /** |
|
428 * Moves a child visual to the front of the other children. In other words |
|
429 * the visual is drawn last (on top of the other child visuals). In practise |
|
430 * this affects the order of the visuals whithin this layout so that the |
|
431 * visual is moved at the end of the list. |
|
432 * |
|
433 * Causes layout recalculation. |
|
434 * |
|
435 * @param aVisual Child visual to move. |
|
436 * @see MoveVisualToBack() |
|
437 * @see Reorder() |
|
438 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
439 * |
|
440 * @see MoveVisualToFront() - Use this instead! |
|
441 */ |
|
442 IMPORT_C void MoveVisualToFront(CHuiVisual& aVisual, TInt aLayoutTransitionTime = 0); |
|
443 |
|
444 |
|
445 /** |
|
446 * Moves a child visual behind the other children (in drawing order). |
|
447 * In other words the visual is drawn first (the other child visuals will |
|
448 * be drawn on top of this visual). |
|
449 * |
|
450 * In practise this affects the order |
|
451 * of the visuals whithin this layout so that the visual is moved at |
|
452 * the beginning of the list (ordinal 0). |
|
453 * |
|
454 * @param aVisual Child visual to move. |
|
455 * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds. |
|
456 * @see MoveVisualToFront() |
|
457 * @see Reorder() |
|
458 */ |
|
459 IMPORT_C void MoveVisualToBack(CHuiVisual& aVisual, TInt aLayoutTransitionTime = 0); |
|
460 |
|
461 /** |
|
462 * Notifies children of the change in the environment's skin. |
|
463 */ |
|
464 IMPORT_C void NotifySkinChangedL(); |
|
465 |
|
466 /** |
|
467 * Sets the transition time for the recalculation of this layout's |
|
468 * contents. This is used when a visual is added or removed or when |
|
469 * the order of the children is changed. |
|
470 * |
|
471 * You need to set the EHuiVisualFlagManualTransitionTime flag of this |
|
472 * visual before this setting has any effect. This flag overrides the |
|
473 * layout transition time hierarchy and uses a local value instead. |
|
474 * |
|
475 * @param aTransitionTime Transition time in milliseconds. |
|
476 * |
|
477 * @see CHuiLayout::SetTransitionTime() |
|
478 * @see CHuiVisual::SetFlag() |
|
479 * @see EHuiVisualFlagManualTransitionTime |
|
480 */ |
|
481 IMPORT_C void SetTransitionTime(TInt aTransitionTime); |
|
482 |
|
483 /** |
|
484 * Returns the transition time of this layout. |
|
485 * |
|
486 * @return Transition time in milliseconds, or |
|
487 * KHuiLayoutDefaultTransitionTime. |
|
488 * |
|
489 * @see CHuiLayout::SetTransitionTime() |
|
490 * @see CHuiVisual::SetFlag() |
|
491 * @see EHuiVisualFlagManualTransitionTime |
|
492 */ |
|
493 IMPORT_C TInt TransitionTime() const; |
|
494 |
|
495 /** |
|
496 * Determines the layout ordinal for a child visual. The child's placement |
|
497 * depends on the ordinal number. |
|
498 * |
|
499 * @param aIndex Index of the child visual. |
|
500 */ |
|
501 IMPORT_C virtual TInt ChildOrdinal(TInt aIndex); |
|
502 |
|
503 /** |
|
504 * From CHuiVisual. Prepares all children of this layout for |
|
505 * drawing. The preparation is done in drawing |
|
506 * order. |
|
507 * |
|
508 * Actually this default implementation is not |
|
509 * leaving, since it traps the prepare errors |
|
510 * inside and handles the errors by calling |
|
511 * the visual owners "prepare draw failed" |
|
512 * -callback. |
|
513 * |
|
514 * @return ETrue if the prepare succeeded, or EFail if |
|
515 * the prepare failed. Failing to prepare a draw |
|
516 * terminates the screen refresh and drawing |
|
517 * for the current frame. |
|
518 * |
|
519 * @see MHuiVisualOwner::VisualPrepareDrawFailed() |
|
520 */ |
|
521 IMPORT_C TBool PrepareDrawL(); |
|
522 /** |
|
523 * From CHuiVisual. Draws (renders) this layout. |
|
524 * |
|
525 * The default implementataion applies transformations |
|
526 * (affects the positions of the layout), draws brushes |
|
527 * and of course children. |
|
528 * |
|
529 * Layout clipping is not affected by transformation. |
|
530 * |
|
531 * @todo Clipping doesn't work if there is a transformation? |
|
532 * @todo No need to draw children that won't be visible. |
|
533 */ |
|
534 IMPORT_C void Draw(CHuiGc& aGc) const; |
|
535 |
|
536 /** |
|
537 * From CHuiVisual. Called to inform the display that a dirty region has to be defined. |
|
538 * |
|
539 * Forward the notification request to all the child visuals. |
|
540 * Scrolling causes changed reports from the layout itself. |
|
541 */ |
|
542 IMPORT_C void ReportChanged(); |
|
543 |
|
544 /** From CHuiVisual */ |
|
545 IMPORT_C void ClearChanged(); |
|
546 |
|
547 /** From CHuiVisual */ |
|
548 IMPORT_C TBool Changed() const; |
|
549 |
|
550 /** From CHuiVisual */ |
|
551 IMPORT_C void DumpTree() const; |
|
552 |
|
553 /** |
|
554 * Defines the base unit used for positioning and sizing children |
|
555 * within this layout. For example, the actual X position of a child is |
|
556 * determined by <tt>aBaseUnit.iX * childX</tt>. The effect of the |
|
557 * base unit is limited to the children of this layout -- the |
|
558 * grandchildren use the base units of their parents, not this base unit. |
|
559 * |
|
560 * @note It is recommended to use EHuiUnitNormalized if proportional base units are |
|
561 * required. For example, EHuiUnitRelativeToMySize would not make sense as a base |
|
562 * unit. |
|
563 * |
|
564 * @param aMetric Metric that will be used for both X and Y axes. |
|
565 */ |
|
566 IMPORT_C void SetBaseUnit(const THuiMetric& aBaseUnit); |
|
567 |
|
568 /** |
|
569 * Defines the base unit used for positioning and sizing children |
|
570 * within this layout. For example, the actual X position of a child is |
|
571 * determined by <tt>aBaseUnit.iX * childX</tt>. The effect of the |
|
572 * base unit is limited to the children of this layout -- the |
|
573 * grandchildren use the base units of their parents, not this base unit. |
|
574 * |
|
575 * @param aMetric Metric to use as the base unit. |
|
576 */ |
|
577 IMPORT_C void SetBaseUnit(const THuiXYMetric& aBaseUnit); |
|
578 |
|
579 /** |
|
580 * Returns the layout's base measurement unit. The positions and sizes |
|
581 * of the children of this layout are interpreted as multiples of this |
|
582 * base unit. For example, the actual X position of a child is |
|
583 * determined by <tt>aBaseUnit.iX * childX</tt>. |
|
584 * |
|
585 * The effect of the base unit is limited to the children of this layout |
|
586 * -- the grandchildren use the base units of their parents, not this |
|
587 * base unit. |
|
588 * |
|
589 * @note that if the visual flag @c EHuiVisualFlagAutomaticLocaleMirroringEnabled |
|
590 * is set, the value returned by this method will change based on the current platform |
|
591 * locale mirroring in the X-axis. So for example if the current layout is mirrored, then |
|
592 * the value returned by this method will have the X magnitude set to the negative |
|
593 * of the value that was set using @c SetBaseUnit. |
|
594 * |
|
595 * @return Metric used as the base unit for child coordinates and sizes. |
|
596 */ |
|
597 IMPORT_C virtual THuiXYMetric BaseUnit() const; |
|
598 |
|
599 |
|
600 /** @endAPI */ |
|
601 |
|
602 |
|
603 /** |
|
604 * Calculate the bounding rectangle for the layout. The rectangle is |
|
605 * calculated in the base units of the layout, i.e. it is calculated |
|
606 * using unconverted the child coordinates and sizes. |
|
607 * |
|
608 * @return Bounding rectangle: the smallest rectangle inside which |
|
609 * all the children of this layout can fit. |
|
610 */ |
|
611 THuiRealRect BoundingRect() const; |
|
612 |
|
613 /** |
|
614 * Calculate the size of the inner area (bounds without outer padding). |
|
615 * The size is calculated in the base units of this layout, so that |
|
616 * children can be positioned within the layout based on this size. |
|
617 * |
|
618 * @return Width and height of the inner area, in base units of |
|
619 * this layout. |
|
620 */ |
|
621 IMPORT_C THuiRealSize InnerSize() const __SOFTFP; |
|
622 |
|
623 /** |
|
624 * Calculates the top left corner of the inner area (bounds without |
|
625 * outer padding). The point is calculated in the base units of this |
|
626 * layout, so that the children can be positioned within the layout |
|
627 * based on this point. |
|
628 * |
|
629 * @return Top left corner point of the inner area, in base units |
|
630 * of this layout. |
|
631 */ |
|
632 IMPORT_C THuiRealPoint InnerTopLeft() const __SOFTFP; |
|
633 |
|
634 /** @beginAPI */ |
|
635 |
|
636 /** |
|
637 * New virtual method. Determines the size of a child visual according to the layout. |
|
638 * The child size is determined using the base units of the layout. |
|
639 * Derived layout classes should refer to InnerSize() and InnerTopLeft() |
|
640 * to determine the area suitable for placing children into. |
|
641 * |
|
642 * @param aOrdinal Layout ordinal of the child visual. |
|
643 * @param aSize New target size for the child. This goes to |
|
644 * CHuiVisual::SetSize() with no conversions. |
|
645 * |
|
646 * @return <code>ETrue</code>, if a new size was determined. Otherwise, |
|
647 * <code>EFalse</code> is returned and no size changes are |
|
648 * needed. |
|
649 */ |
|
650 IMPORT_C virtual TBool ChildSize(TInt aOrdinal, TSize& aSize); |
|
651 |
|
652 /** |
|
653 * New virtual method. Determines the position of a child visual according to the layout. |
|
654 * The child position is determined using the base units of the layout. |
|
655 * Derived layout classes should refer to InnerSize() and InnerTopLeft() |
|
656 * to determine the area suitable for placing children into. |
|
657 * |
|
658 * @param aOrdinal Layout ordinal of the child visual. |
|
659 * @param aPos New position for the child. This goes to |
|
660 * CHuiVisual::SetPos() with no conversions. |
|
661 * |
|
662 * @return <code>ETrue</code>, if a new position was determined. |
|
663 * Otherwise, <code>EFalse</code> is returned and no position |
|
664 * changes are needed. |
|
665 */ |
|
666 IMPORT_C virtual TBool ChildPos(TInt aOrdinal, TPoint& aPos); |
|
667 |
|
668 |
|
669 enum EHuiLayoutChildRect |
|
670 { |
|
671 THuiLayoutChildRectNotImplemented = -1, |
|
672 THuiLayoutChildRectUpdateNotNeeded = 0, |
|
673 THuiLayoutChildRectPosUpdateNeeded = 1, |
|
674 THuiLayoutChildRectSizeUpdateNeeded = 2, |
|
675 THuiLayoutChildRectLayoutUpdateNeeded = THuiLayoutChildRectPosUpdateNeeded | THuiLayoutChildRectSizeUpdateNeeded |
|
676 }; |
|
677 |
|
678 /** |
|
679 * New virtual method. Determines the position and size of a child visual according to the layout. |
|
680 * The child position is determined using the base units of the layout. |
|
681 * Derived layout classes should refer to InnerSize() and InnerTopLeft() |
|
682 * to determine the area suitable for placing children into. |
|
683 * |
|
684 * @param aOrdinal Layout ordinal of the child visual. |
|
685 * @param aRect New position for the child. This is used to set |
|
686 * the child size and position with no conversions. |
|
687 * |
|
688 * @return one of the values belonging to EHuiLayoutChildRect as follows: |
|
689 * THuiLayoutChildRectNotImplemented - method not implemented, ChildPos and ChildSize to be called as previously |
|
690 * THuiLayoutChildRectUpdateNotNeeded - method is implemented, but aRect was not calculated; child pos/size are not modified |
|
691 * THuiLayoutChildRectPosUpdateNeeded - method is implemented, but only iTl was calculated (pos) |
|
692 * THuiLayoutChildRectSizeUpdateNeeded - method is implemented, but only size was calculated (iTl will be returned as 0) |
|
693 * THuiLayoutChildRectLayoutUpdateNeeded - method is implemented and aRect was calculated |
|
694 * |
|
695 */ |
|
696 IMPORT_C virtual TInt ChildRect(TInt aOrdinal, THuiRealRect& aRect); |
|
697 |
|
698 |
|
699 /** @endAPI */ |
|
700 |
|
701 |
|
702 public: // From CHuiVisual. |
|
703 |
|
704 |
|
705 IMPORT_C TReal32 BrushOpacity() const __SOFTFP; |
|
706 |
|
707 IMPORT_C THuiRealRect BrushRect() const __SOFTFP; |
|
708 |
|
709 IMPORT_C CHuiSkin& BrushSkin() const; |
|
710 |
|
711 protected: |
|
712 /** |
|
713 * From CHuiVisual. Overridden by subclasses to draw the content of the visual. |
|
714 * By default DrawSelf does not draw anything. |
|
715 */ |
|
716 IMPORT_C void DrawSelf(CHuiGc& aGc, const TRect& aDisplayRect) const; |
|
717 |
|
718 /** |
|
719 * Calculate the metric reference for this layout, relative to this layout's |
|
720 * base units. |
|
721 * |
|
722 * @param aLayout this parameter is no longer used, an alternative method is provided that does not take this parameter |
|
723 * @param aMetric the metric for which we need a reference value |
|
724 */ |
|
725 IMPORT_C THuiRealPoint MetricReferenceForLayoutInPixels(const CHuiLayout* aLayout, const THuiXYMetric& aMetric) const __SOFTFP; |
|
726 IMPORT_C THuiRealPoint MetricReferenceForLayoutInPixels(const THuiXYMetric& aMetric) const __SOFTFP; |
|
727 |
|
728 IMPORT_C void ExpandRectWithContent(TRect& aRect) const; |
|
729 |
|
730 /** ! From HuiVisual */ |
|
731 IMPORT_C void VisualExtension(const TUid& aExtensionUid, TAny** aExtensionParams); |
|
732 |
|
733 TBool EffectIsAppliedToChildren() const; |
|
734 |
|
735 public: // RnD utilities from CHuiVisual |
|
736 IMPORT_C void GetInstanceName(TDes& aName) const; |
|
737 IMPORT_C void GetClassName(TDes& aName) const; |
|
738 IMPORT_C TType Type() const; |
|
739 IMPORT_C TInt SessionId() const; |
|
740 IMPORT_C void SetSessionId(TInt aSessionId); |
|
741 |
|
742 private: |
|
743 |
|
744 TBool HasActiveChilderen() const; |
|
745 void DrawStoredBitmap(CHuiGc &aGc) const; |
|
746 protected: |
|
747 struct THuiLayoutPrivateData; |
|
748 THuiLayoutPrivateData* iHuiLayoutPrivateData; // owned |
|
749 }; |
|
750 |
|
751 #endif // __HUILAYOUT_H__ |