class CHuiLayout : public CHuiVisual |
Layouts are visuals that manage the placement of a set of child visuals (or other 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(EHuiVisualFlagLayoutUpdateNotification);
.. and override VisualLayoutUpdated() method in your control.
SetSize() SetFlags() CHuiControl::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 THuiXYMetric 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 THuiMetric 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 CHuiTransformation, 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 EHuiVisualFlagAutomaticLocaleMirroringEnabled, 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 EHuiUnitS60 metric unit is dependent on the platform-specified measurement units for layout. CHuiGridLayout and CHuiAnchorLayout provide support for pixel-independent placement of their children.
CHuiAnchorLayout CHuiGridLayoutApplications that need more complex layouts should derive their own CHuiLayout 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 | DrawSelf(CHuiGc &, const TRect &) |
TBool | EffectIsAppliedToChildren() |
IMPORT_C void | ExpandRectWithContent(TRect &) |
IMPORT_C THuiRealPoint | MetricReferenceForLayoutInPixels(const CHuiLayout *, const THuiXYMetric &) |
IMPORT_C THuiRealPoint | MetricReferenceForLayoutInPixels(const THuiXYMetric &) |
IMPORT_C void | VisualExtension(const TUid &, TAny **) |
Private Member Functions | |
---|---|
void | DrawStoredBitmap(CHuiGc &) |
TBool | HasActiveChilderen() |
Public Member Enumerations | |
---|---|
enum | EHuiLayoutChildRect { THuiLayoutChildRectNotImplemented = -1, THuiLayoutChildRectUpdateNotNeeded = 0, THuiLayoutChildRectPosUpdateNeeded = 1, THuiLayoutChildRectSizeUpdateNeeded = 2, THuiLayoutChildRectLayoutUpdateNeeded = THuiLayoutChildRectPosUpdateNeeded | THuiLayoutChildRectSizeUpdateNeeded } |
enum | TExpansionFlags { EExpandNone = 0, EExpandHorizontally = 1, EExpandVertically = 2 } |
Protected Attributes | |
---|---|
THuiLayoutPrivateData * | iHuiLayoutPrivateData |
Inherited Attributes | |
---|---|
CHuiVisual::iDepthOffset | |
CHuiVisual::iOpacity | |
CHuiVisual::iOwner | |
CHuiVisual::iPreviousDrawn | |
CHuiVisual::iSessionId | |
CHuiVisual::iTrackVisual |
IMPORT_C | CHuiLayout | ( | MHuiVisualOwner & | aOwner | ) |
Constructor.
MHuiVisualOwner & aOwner |
IMPORT_C CHuiLayout * | AddNewL | ( | CHuiControl & | aOwnerControl, |
CHuiLayout * | aParentLayout = 0 | |||
) | [static] |
Construct a new basic layout and give its ownership to a control. Note that CHuiLayout has no real layout functionality: its children must be laid out manually.
CHuiControl & aOwnerControl | Owner control. |
CHuiLayout * aParentLayout = 0 | Parent layout for the new layout. |
IMPORT_C void | AppendL | ( | CHuiVisual * | aVisual, |
TInt | aLayoutTransitionTime = 0 | |||
) |
Append a new visual to the layout. If the visual is already a member of some other layout, it will be removed from the old layout first.
CHuiVisual * aVisual | Visual to append. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C THuiXYMetric | 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 EHuiVisualFlagAutomaticLocaleMirroringEnabled 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.
THuiRealRect | BoundingRect | ( | ) | const |
Calculate the bounding rectangle for the layout. The rectangle is calculated in the base units of the layout, i.e. it is calculated using unconverted the child coordinates and sizes.
IMPORT_C TInt | ChildOrdinal | ( | TInt | aIndex | ) | [virtual] |
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 | |||
) | [virtual] |
New virtual method. Determines the position of a child visual according to the layout. The child position is determined using the base units of the layout. Derived layout classes should refer to InnerSize() and InnerTopLeft() to determine the area suitable for placing children into.
IMPORT_C TInt | ChildRect | ( | TInt | aOrdinal, |
THuiRealRect & | aRect | |||
) | [virtual] |
New virtual method. Determines the position and size of a child visual according to the layout. The child position is determined using the base units of the layout. Derived layout classes should refer to InnerSize() and InnerTopLeft() to determine the area suitable for placing children into.
TInt aOrdinal | Layout ordinal of the child visual. |
THuiRealRect & aRect | New position for the child. This is used to set the child size and position with no conversions. |
IMPORT_C TBool | ChildSize | ( | TInt | aOrdinal, |
TSize & | aSize | |||
) | [virtual] |
New virtual method. Determines the size of a child visual according to the layout. The child size is determined using the base units of the layout. Derived layout classes should refer to InnerSize() and InnerTopLeft() to determine the area suitable for placing children into.
IMPORT_C void | ConstructL | ( | ) | [virtual] |
Second-phase constructor from CHuiVisual, must be called in deriving class
IMPORT_C TInt | Count | ( | ) | const [virtual] |
From CHuiVisual. Returns the number of child visuals in the layout.
IMPORT_C void | Draw | ( | CHuiGc & | aGc | ) | const [virtual] |
From CHuiVisual. Draws (renders) this layout.
The default implementataion applies transformations (affects the positions of the layout), draws brushes and of course children.
Layout clipping is not affected by transformation.
CHuiGc & aGc |
IMPORT_C void | DrawSelf | ( | CHuiGc & | aGc, |
const TRect & | aDisplayRect | |||
) | const [protected, virtual] |
From CHuiVisual. Overridden by subclasses to draw the content of the visual. By default DrawSelf does not draw anything.
IMPORT_C TInt | EffectiveLayoutOrdinal | ( | const CHuiVisual & | 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 CHuiVisual & aVisual |
IMPORT_C void | EnableScrollingL | ( | TBool | aScrolling = ETrue | ) |
Enables or disables scrolling in the layout. An offset for the origin of the layout can be defined using ScrollOffset() - method and manipulating the THuiTimedPoint returned by that method.
Scroll offset, unlike other layout parameters, is not directly applied to layout children when UpdateChildrenLayout() is called. Instead, the scroll offset is taken into consideration when individual child visual display rectangles are calculated. This way the scroll offset is directly applied to dirty rectangle calculations as well as to visual content rectangle calculations when visuals are drawn.
TBool aScrolling = ETrue | ETrue to enable scrolling, EFalse to disable. |
IMPORT_C void | ExpandRectWithContent | ( | TRect & | aRect | ) | const [protected, virtual] |
Expands the dirty region of the visual depending on the content of the visual. This includes any brushes attached to the visual. Used during dirty region reporting.
TRect & aRect | Dirty region. |
IMPORT_C CHuiVisual * | FindTag | ( | const TDesC8 & | aTag | ) | [virtual] |
From CHuiVisual. Finds a visual whose tag descriptor contains a specific tag. Checks self first, then looks through the child visuals.
CHuiLayout::FindTag() extends upon the basic implementation in CHuiVisual::FindTag() by adding recursive visual hierarchy searching.
CHuiVisual::Tag() CHuiVisual::SetTagL() CHuiVisual::IsTagged() CHuiVisual::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 | ( | const CHuiVisual * | aVisual | ) | const |
Finds a visual's index.
const CHuiVisual * aVisual | Visual to look for. |
IMPORT_C void | GetClassName | ( | TDes & | aName | ) | const [virtual] |
Returns the name of the class.
TDes & aName | Name of the visual class. |
IMPORT_C void | GetInstanceName | ( | TDes & | aName | ) | const [virtual] |
TDes & aName |
IMPORT_C TInt | HorizontalInnerPadding | ( | ) | const |
Returns the inner horizontal padding. This is useless, use InnerPaddingInBaseUnits() instead.
IMPORT_C THuiRealPoint | 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 THuiRealSize | InnerSize | ( | ) | const |
Calculate the size of the inner area (bounds without outer padding). The size is calculated in the base units of this layout, so that children can be positioned within the layout based on this size.
IMPORT_C THuiRealPoint | InnerTopLeft | ( | ) | const |
Calculates the top left corner of the inner area (bounds without outer padding). The point is calculated in the base units of this layout, so that the children can be positioned within the layout based on this point.
IMPORT_C void | InsertL | ( | CHuiVisual * | aVisual, |
TInt | aPosition, | |||
TInt | aLayoutTransitionTime = 0 | |||
) |
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.
CHuiVisual * aVisual | Visual to append. |
TInt aPosition | |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C THuiRealPoint | MetricReferenceForLayoutInPixels | ( | const CHuiLayout * | aLayout, |
const THuiXYMetric & | aMetric | |||
) | const [protected] |
Calculate the metric reference for this layout, relative to this layout's base units.
const CHuiLayout * aLayout | this parameter is no longer used, an alternative method is provided that does not take this parameter |
const THuiXYMetric & aMetric | the metric for which we need a reference value |
IMPORT_C THuiRealPoint | MetricReferenceForLayoutInPixels | ( | const THuiXYMetric & | aMetric | ) | const [protected] |
const THuiXYMetric & aMetric |
IMPORT_C void | MoveVisualToBack | ( | CHuiVisual & | 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).
CHuiVisual & aVisual | Child visual to move. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | MoveVisualToFront | ( | CHuiVisual & | 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!
CHuiVisual & aVisual | Child visual to move. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | NotifySkinChangedL | ( | ) | [virtual] |
Notifies children of the change in the environment's skin.
IMPORT_C TBool | PrepareDrawL | ( | ) | [virtual] |
From CHuiVisual. Prepares all children of this layout for drawing. The preparation is done in drawing order.
Actually this default implementation is not leaving, since it traps the prepare errors inside and handles the errors by calling the visual owners "prepare draw failed" -callback.
IMPORT_C void | Remove | ( | CHuiVisual * | aVisual, |
TInt | aLayoutTransitionTime = 0 | |||
) |
Remove a visual from the layout.
CHuiVisual * aVisual | Visual to remove. |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | RemoveAndDestroyAllD | ( | ) | [virtual] |
From CHuiVisual. 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 | ( | CHuiVisual & | 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.
CHuiVisual & aVisual | Child visual to move. |
TInt aPosition | New position (and ordinal number) in the child list (0 = first, Count()-1 = last). |
TInt aLayoutTransitionTime = 0 | How long the transition should take visually, in milliseconds. |
IMPORT_C void | ReportChanged | ( | ) | [virtual] |
From CHuiVisual. Called to inform the display that a dirty region has to be defined.
Forward the notification request to all the child visuals. Scrolling causes changed reports from the layout itself.
IMPORT_C THuiTimedPoint & | ScrollOffset | ( | ) |
IMPORT_C TBool | Scrolling | ( | ) | const |
Indicates whether scrolling is enabled in this layout. EnableScrolling()
IMPORT_C void | SetBaseUnit | ( | const THuiMetric & | 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 EHuiUnitNormalized if proportional base units are required. For example, EHuiUnitRelativeToMySize would not make sense as a base unit.
const THuiMetric & aBaseUnit |
IMPORT_C void | SetBaseUnit | ( | const THuiXYMetric & | 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 THuiXYMetric & 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.
const TPoint & aInnerPadding | Inner padding (e.g., column, row separation). |
IMPORT_C void | SetInnerPadding | ( | const THuiXYMetric & | 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 EHuiUnitRelativeToMySize so that the paddings are relative to the size of this layout visual
const THuiXYMetric & aInnerPadding | Inner padding, using metrics. |
IMPORT_C void | SetPos | ( | const THuiRealPoint & | aPos, |
TInt | aTransitionTime = 0 | |||
) | [virtual] |
From CHuiVisual. Sets the position of the layout.
const THuiRealPoint & aPos | Target position, in the local coordinate system as defined by the parent layout (or the display, if there is no parent). |
TInt aTransitionTime = 0 | Transition time in milliseconds. |
IMPORT_C void | SetScrollOffsetInBaseUnits | ( | const THuiRealPoint & | aOffset, |
TInt | aTransitionTime = 0 | |||
) |
Specifies the scroll offset of this layout. The scroll offset is defined in layout's base units. The scroll offset has to be enabled before this method is called. BaseUnit() EnableScrollingL()
const THuiRealPoint & aOffset | Offset in layout's base units. |
TInt aTransitionTime = 0 | Time when the offset is to be reached in milliseconds. |
IMPORT_C void | SetSessionId | ( | TInt | aSessionId | ) |
Sets the session id for object.
TInt aSessionId |
IMPORT_C void | SetSize | ( | const THuiRealSize & | aSize, |
TInt | aTransitionTime = 0 | |||
) | [virtual] |
From CHuiVisual. Change the size of the layout. Children's positions and sizes are updated accordingly. Each layout class is responsible for determining how to update children's layout.
const THuiRealSize & aSize | Size to set the layout to. |
TInt aTransitionTime = 0 |
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.
You need to set the EHuiVisualFlagManualTransitionTime flag of this visual before this setting has any effect. This flag overrides the layout transition time hierarchy and uses a local value instead.
CHuiLayout::SetTransitionTime() CHuiVisual::SetFlag() EHuiVisualFlagManualTransitionTime
TInt aTransitionTime | Transition time in milliseconds. |
IMPORT_C TInt | TransitionTime | ( | ) | const |
Returns the transition time of this layout.
CHuiLayout::SetTransitionTime() CHuiVisual::SetFlag() EHuiVisualFlagManualTransitionTime
IMPORT_C void | UpdateChildLayout | ( | TInt | aIndex, |
TInt | aTransitionTime = 0 | |||
) | [virtual] |
New virtual method. Update the layout of one child visual.
IMPORT_C void | UpdateChildrenLayout | ( | TInt | aTransitionTime = 0 | ) | [virtual] |
From CHuiVisual. Update the layout of all children. Subclasses can call this to recalculate the layout of all children.
TInt aTransitionTime = 0 | Time for layout transition. |
IMPORT_C TInt | VerticalInnerPadding | ( | ) | const |
Returns the inner vertical padding. This is useless, use InnerPaddingInBaseUnits() 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 CHuiVisual & | Visual | ( | TInt | aIndex | ) | const [virtual] |
From CHuiVisual. Returns a child visual.
TInt aIndex | Index of the child visual. |
IMPORT_C void | VisualExtension | ( | const TUid & | aExtensionUid, |
TAny ** | aExtensionParams | |||
) | [protected, virtual] |
! From HuiVisual
THuiLayoutChildRectNotImplemented = -1 | |
THuiLayoutChildRectUpdateNotNeeded = 0 | |
THuiLayoutChildRectPosUpdateNeeded = 1 | |
THuiLayoutChildRectSizeUpdateNeeded = 2 | |
THuiLayoutChildRectLayoutUpdateNeeded = THuiLayoutChildRectPosUpdateNeeded | THuiLayoutChildRectSizeUpdateNeeded |
EExpandNone = 0 |
Not expanding in any direction. |
EExpandHorizontally = 1 |
Expands horizontally. |
EExpandVertically = 2 |
Expands vertically. |
THuiLayoutPrivateData * | iHuiLayoutPrivateData | [protected] |
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.