class CAlfLayout : public CAlfVisual |
Base class for all layouts.
Layouts are responsible for setting the positions and sizes of their child visuals. Each layout can define a position, a size, or both (or neither) for their children.
Layouts use the children's ordinal numbers to determine where each of them should be placed. For example, a grid layout could define that the top row contains children with ordinals 0..3, from left to right. The second row could then contain the children 4..7. When the order of the child visuals changes within their parent layout, the parent layout will recalculate the positions and sizes of the affected children.
When the size of a layout changes, it will immediately recalculate the layout of its children. The transition time that is specified in the size transition of the layout is used when setting the targets of the children's new positions and sizes.
Layouts are able to notify their controls when their size is changed. These notifications are needed because the size of a layout is not known until the display is refreshed. This means that the size of a layout is not available when your controls ConstructL is executed , unless it is explicitly set. The notifications are also handy because they allow the controls to respond to dynamic screen size changes. So unless if the whole screen is not used for the layout, the notifications are the only way to do calculations based on the layout size.
To make the control receive layout update notifications call:
layout->SetFlags(EAlfVisualFlagLayoutUpdateNotification);
.. and override VisualLayoutUpdated() method in your control.
SetSize() SetFlags() CAlfControl::VisualLayoutUpdated() Each layout defines its own local coordinate system used for interpreting the positions and sizes of its child visuals. The base unit of the coordinate system is defined with the SetBaseUnit() method, which sets a TAlfXYMetric to use as the basis for all coordinate calculations. The default metric is [1px, 1px] which corresponds to pixels on the display.
The local coordinate system of a layout can be mirrored horizontally and/or vertically by using a negative magnitude in the relevant TAlfMetric of the base unit. Note that this will only affect the local coordinate system of the layout: the contents of the child visuals or child layouts will not be mirrored. Visual mirroring should be done with a CAlfTransformation, and child layouts can be mirrored by further application of the negative base unit metrics. In order to enable a layout to automatically mirror the horizontal component of the base unit based on locale mirroring, set the visual flag EAlfVisualFlagAutomaticLocaleMirroringEnabled , note that it is necessary to set this flag for each layout for which this feature is required.
To create to a fully scalable UI, the appropriate base unit metrics and layout visuals must be used. For example, the EAlfUnitS60 metric unit is dependent on the platform-specified measurement units for layout. CAlfGridLayout and CAlfAnchorLayout provide support for pixel-independent placement of their children.
CAlfAnchorLayout CAlfGridLayout Applications that need more complex layouts should derive their own CAlfLayout based classes that implement the necessary layout calculations. In many cases, however, a combination of some of the built-in layout classes such as anchor and grid layouts will be sufficient.
Protected Member Functions | |
---|---|
IMPORT_C void | DoRemoveAndDestroyAllD () |
IMPORT_C void | PropertyOwnerExtension (const TUid &, TAny **) |
Public Member Enumerations | |
---|---|
enum | TExpansionFlags { EExpandNone = 0, EExpandHorizontally = 1, EExpandVertically = 2 } |
Private Attributes | |
---|---|
TLayoutPrivateData * | iLayoutData |
IMPORT_C CAlfLayout * | AddNewL | ( | CAlfControl & | aOwner, |
CAlfLayout * | aParentLayout = 0 | |||
) | [static] |
2-phased constructor which also gives ownedship to control.
CAlfControl & aOwner | |
CAlfLayout * aParentLayout = 0 | If given, has the parent layout. |
IMPORT_C TInt | Append | ( | CAlfVisual * | aVisual, |
TBool | aConstructedWithParentInformation = EFalse, | |||
TInt | aLayoutTransitionTime = 0 | |||
) |
Append a new visual to the layout.
CAlfVisual * aVisual | Visual to append. |
TBool aConstructedWithParentInformation = EFalse | Whether visual already knows its parent |
TInt aLayoutTransitionTime = 0 |
IMPORT_C TAlfXYMetric | BaseUnit | ( | ) | const [virtual] |
Returns the layout's base measurement unit. The positions and sizes of the children of this layout are interpreted as multiples of this base unit. For example, the actual X position of a child is determined by aBaseUnit.iX * childX .
The effect of the base unit is limited to the children of this layout -- the grandchildren use the base units of their parents, not this base unit.
that if the visual flag EAlfVisualFlagAutomaticLocaleMirroringEnabled is set, the value returned by this method will change based on the current platform locale mirroring in the X-axis. So for example if the current layout is mirrored, then the value returned by this method will have the X magnitude set to the negative of the value that was set using SetBaseUnit .
IMPORT_C TInt | ChildOrdinal | ( | TInt | aIndex | ) |
Determines the layout ordinal for a child visual. The child's placement depends on the ordinal number.
TInt aIndex | Index of the child visual. |
IMPORT_C TBool | ChildPos | ( | TInt | aOrdinal, |
TPoint & | aPos | |||
) |
Determines the position of a child visual according to the layout.
IMPORT_C TBool | ChildSize | ( | TInt | aOrdinal, |
TSize & | aSize | |||
) |
Determines the size of a child visual according to the layout.
IMPORT_C void | ConstructL | ( | CAlfControl & | aOwner | ) | [virtual] |
From CAlfVisual . Second-phase constructor.
CAlfControl & aOwner |
IMPORT_C void | DoRemoveAndDestroyAllD | ( | ) | [protected, virtual] |
CAlfVisual Deletes the child visuals
IMPORT_C TInt | EffectiveLayoutOrdinal | ( | const CAlfVisual & | aVisual | ) | const |
Layout is calculated according the ordinals. The effective ordinal may not be the same as the real child ordinal, because some visuals are laid out manually.
const CAlfVisual & aVisual |
IMPORT_C void | EnableScrollingL | ( | TBool | aScrolling = ETrue | ) |
Enables or disables scrolling in the layout.
TBool aScrolling = ETrue | ETrue to enable scrolling, EFalse to disable. |
IMPORT_C CAlfVisual * | FindTag | ( | const TDesC8 & | aTag | ) | [virtual] |
CAlfVisual Finds a visual whose tag descriptor contains a specific tag.
CAlfLayout::FindTag() extends the search into child visuals, covering recursively entire visual hierarchies.
Todo: how should several visuals with matching tag to be handled ??
CAlfVisual::Tag() CAlfVisual::SetTagL() CAlfVisual::IsTagged() CAlfVisual::FindTag()
const TDesC8 & aTag | Tag to look for. If this tag is found as a part of a visual's colon-separated tag descriptor, it is treated as a match and the visual is returned. The tag to look for cannot contain separator characters (:). |
IMPORT_C TInt | FindVisual | ( | CAlfVisual * | aVisual | ) | const |
Finds a visual's index.
CAlfVisual * aVisual | Visual to look for. |
IMPORT_C TInt | HorizontalInnerPadding | ( | ) | const |
Returns the inner horizontal padding.
this will return correct pixel values only if paddings were set using deprecated pixel based APIs, so migrate to using metrics instead
IMPORT_C TPoint | InnerPadding | ( | ) | const |
Returns the inner padding. this will return correct pixel values only if paddings were set using deprecated pixel based APIs, so migrate to using metrics instead
IMPORT_C const TAlfXYMetric & | InnerPaddingAsMetric | ( | ) | const |
Returns the inner padding metric InnerPadding() which is superceded by this method
IMPORT_C TAlfRealPoint | InnerPaddingInBaseUnits | ( | ) | const |
Returns the inner padding converted to the base units of this layout. These can be summed with the positions and sizes of the layout's children.
IMPORT_C TInt | Insert | ( | CAlfVisual * | aVisual, |
TInt | aPosition | |||
) |
Insert a new visual to the layout, at specified position (position 0 is the first, Count() -1 is the last). If the visual is already a member of some other layout, it will be removed from the old layout first.
CAlfVisual * aVisual | Visual to append. |
TInt aPosition |
IMPORT_C void | MoveVisualToBack | ( | CAlfVisual & | aVisual, |
TInt | aLayoutTransitionTime = 0 | |||
) |
Moves a child visual behind the other children (in drawing order). In other words the visual is drawn first (the other child visuals will be drawn on top of this visual).
In practise this affects the order of the visuals whithin this layout so that the visual is moved at the beginning of the list (ordinal 0).
CAlfVisual & aVisual | Child visual to move. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | MoveVisualToFront | ( | CAlfVisual & | aVisual, |
TInt | aLayoutTransitionTime = 0 | |||
) |
Moves a child visual to the front of the other children. In other words the visual is drawn last (on top of the other child visuals). In practise this affects the order of the visuals whithin this layout so that the visual is moved at the end of the list.
Causes layout recalculation.
MoveVisualToBack() Reorder() MoveVisualToFront() - Use this instead!
CAlfVisual & aVisual | Child visual to move. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | PropertyOwnerExtension | ( | const TUid & | aExtensionUid, |
TAny ** | aExtensionParams | |||
) | [protected, virtual] |
! future proofing
IMPORT_C void | Remove | ( | CAlfVisual * | aVisual, |
TInt | aLayoutTransitionTime = 0 | |||
) |
Remove a visual from the layout.
CAlfVisual * aVisual | Visual to remove. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | RemoveAndDestroyAllD | ( | ) | [virtual] |
From CAlfVisual . Removes this layout from its owner and and destroys the layout. Also removes the entire hierarchy of child visuals and destroys all of them.
IMPORT_C void | Reorder | ( | CAlfVisual & | aVisual, |
TInt | aPosition, | |||
TInt | aLayoutTransitionTime = 0 | |||
) |
Moves the given child visual to specific position in the layout's list of child visuals. Affects the drawing order (last child is drawn last), and possibly the final laid out position and size of the visual. This is due to that many layout implementations calculate the positioning of their children based on child's order number in the list.
Causes layout recalculation.
CAlfVisual & aVisual | Child visual to move. |
TInt aPosition | New position (and ordinal number) in the child list (0 = first, Count()-1 = last). |
TInt aLayoutTransitionTime = 0 |
IMPORT_C const TAlfTimedPoint & | ScrollOffset | ( | ) | const |
Returns the scroll offset of the layout. The scroll offset is in layout's base units.
IMPORT_C void | SetBaseUnit | ( | const TAlfMetric & | aBaseUnit | ) |
Defines the base unit used for positioning and sizing children within this layout. For example, the actual X position of a child is determined by aBaseUnit.iX * childX . The effect of the base unit is limited to the children of this layout -- the grandchildren use the base units of their parents, not this base unit.
It is recommended to use EAlfUnitNormalized if proportional base units are required. For example, EAlfUnitRelativeToMySize would not make sense as a base unit.
const TAlfMetric & aBaseUnit |
IMPORT_C void | SetBaseUnit | ( | const TAlfXYMetric & | aBaseUnit | ) |
Defines the base unit used for positioning and sizing children within this layout. For example, the actual X position of a child is determined by aBaseUnit.iX * childX . The effect of the base unit is limited to the children of this layout -- the grandchildren use the base units of their parents, not this base unit.
const TAlfXYMetric & aBaseUnit |
IMPORT_C void | SetInnerPadding | ( | const TPoint & | aInnerPadding | ) |
Sets the inner padding of the layout. This is typically the amount of empty space between child visuals in the layout.
that the left and right paddings will be the same, and the top and bottom paddings will be the same.
const TPoint & aInnerPadding | Inner padding (e.g., column, row separation). |
IMPORT_C void | SetInnerPadding | ( | const TAlfXYMetric & | aInnerPadding | ) |
Sets the inner padding of the layout. This is typically the amount of empty space between child visuals in the layout.
as paddings are relative to the layout visual, if relative units are required, it is advisable to use EAlfUnitRelativeToMySize so that the paddings are relative to the size of this layout visual
const TAlfXYMetric & aInnerPadding | Inner padding, using metrics. |
IMPORT_C void | SetScrollOffset | ( | const TAlfTimedPoint & | aPoint | ) |
Set the scroll offset
const TAlfTimedPoint & aPoint | Sets the point. |
IMPORT_C void | SetTransitionTime | ( | TInt | aTransitionTime | ) |
Sets the transition time for the recalculation of this layout's contents. This is used when a visual is added or removed or when the order of the children is changed.
Set to KAlfLayoutDefaultTransitionTime to make the layout use the default transition time queried from CAlfStatic.
TInt aTransitionTime | Transition time in milliseconds, or KAlfLayoutDefaultTransitionTime. |
IMPORT_C void | UpdateChildrenLayout | ( | TInt | aTransitionTime = 0 | ) | [virtual] |
CAlfVisual Update the layout of all children. Subclasses can call this to recalculate the layout of all children.
TInt aTransitionTime = 0 | Time for layout transition in milliseconds. Any negative value uses value given in CAlfEnv::StaticSetLayoutTransitionTime() |
IMPORT_C TInt | VerticalInnerPadding | ( | ) | const |
Returns the inner vertical padding.
this will return correct pixel values only if paddings were set using deprecated pixel based APIs, so migrate to using metrics instead
IMPORT_C TSize | VirtualSize | ( | ) | const |
Determines the virtual size of the layout. The virtual size may be larger than the actual size. The virtual size is updated automatically when the layout's children are positioned.
IMPORT_C CAlfVisual & | Visual | ( | TInt | aIndex | ) | const |
Returns a child visual.
TInt aIndex | Index of the child visual. |
EExpandNone = 0 |
Not expanding in any direction. |
EExpandHorizontally = 1 |
Expands horizontally. |
EExpandVertically = 2 |
Expands vertically. |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.