CAlfLayout Class Reference

class CAlfLayout : public CAlfVisual

Base class for all layouts.

alfclient.lib
Since
S60 v3.2
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(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.

Nested Classes and Structures

Public Member Functions
CAlfLayout ()
~CAlfLayout ()
IMPORT_C CAlfLayout * AddNewL ( CAlfControl &, CAlfLayout *)
IMPORT_C TInt Append ( CAlfVisual *, TBool , TInt )
IMPORT_C TAlfXYMetric BaseUnit ()
IMPORT_C TInt ChildOrdinal ( TInt )
IMPORT_C TBool ChildPos ( TInt , TPoint &)
IMPORT_C TBool ChildSize ( TInt , TSize &)
IMPORT_C void ConstructL ( CAlfControl &)
IMPORT_C TInt Count ()
IMPORT_C TInt EffectiveLayoutOrdinal (const CAlfVisual &)
IMPORT_C void EnableScrollingL ( TBool )
IMPORT_C CAlfVisual * FindTag (const TDesC8 &)
IMPORT_C TInt FindVisual ( CAlfVisual *)
IMPORT_C TInt HorizontalInnerPadding ()
IMPORT_C TPoint InnerPadding ()
IMPORT_C const TAlfXYMetric & InnerPaddingAsMetric ()
IMPORT_C TAlfRealPoint InnerPaddingInBaseUnits ()
IMPORT_C TInt Insert ( CAlfVisual *, TInt )
IMPORT_C void MoveVisualToBack ( CAlfVisual &, TInt )
IMPORT_C void MoveVisualToFront ( CAlfVisual &, TInt )
IMPORT_C void Remove ( CAlfVisual *, TInt )
IMPORT_C void RemoveAndDestroyAllD ()
IMPORT_C void Reorder ( CAlfVisual &, TInt , TInt )
IMPORT_C const TAlfTimedPoint & ScrollOffset ()
IMPORT_C TBool Scrolling ()
IMPORT_C void SetBaseUnit (const TAlfMetric &)
IMPORT_C void SetBaseUnit (const TAlfXYMetric &)
IMPORT_C void SetInnerPadding (const TPoint &)
IMPORT_C void SetInnerPadding (const TAlfXYMetric &)
IMPORT_C void SetScrollOffset (const TAlfTimedPoint &)
IMPORT_C void SetTransitionTime ( TInt )
IMPORT_C TInt TransitionTime ()
IMPORT_C void UpdateChildrenLayout ( TInt )
IMPORT_C TInt VerticalInnerPadding ()
IMPORT_C TSize VirtualSize ()
IMPORT_C CAlfVisual & Visual ( TInt )
Protected Member Functions
IMPORT_C void DoRemoveAndDestroyAllD ()
IMPORT_C void PropertyOwnerExtension (const TUid &, TAny **)
Inherited Functions
CAlfPropertyOwner::CAlfPropertyOwner()
CAlfPropertyOwner::CopyProperty(const CAlfPropertyOwner &,const TDesC8 &)
CAlfPropertyOwner::PropertyClear()
CAlfPropertyOwner::PropertyFindInteger(const TDesC8 &,TInt *)const
CAlfPropertyOwner::PropertyFindString(const TDesC8 &,TDesC **)const
CAlfPropertyOwner::PropertyRemove(const TDesC8 &)
CAlfPropertyOwner::PropertySetIntegerL(const TDesC8 &,TInt,TInt,TInt)
CAlfPropertyOwner::PropertySetStringL(const TDesC8 &,const TDesC &)
CAlfPropertyOwner::~CAlfPropertyOwner()
CAlfVisual::AlignByOrigin(TAlfRealRect &)const
CAlfVisual::Brushes()
CAlfVisual::CAlfVisual()
CAlfVisual::ClearFlag(TAlfVisualFlags)
CAlfVisual::ClearFlags(TUint)
CAlfVisual::Clipping()const
CAlfVisual::Comms()const
CAlfVisual::ConstructL(CAlfControl &,TInt,TInt,const TDesC8 &)
CAlfVisual::CopyValues(const CAlfVisual &,TInt,TInt)
CAlfVisual::DepthOffset()const
CAlfVisual::Display()const
CAlfVisual::DisplayRect()const
CAlfVisual::DisplayRectTarget()const
CAlfVisual::DisplayToLocal(const TAlfRealPoint &)const
CAlfVisual::DisplayToLocal(const TPoint &)const
CAlfVisual::DropShadowHandler()const
CAlfVisual::EffectiveOpacity()const
CAlfVisual::EnableBrushesL(TBool)
CAlfVisual::EnableDropShadowL(TBool)
CAlfVisual::EnableTransformationL(TBool)
CAlfVisual::Env()const
CAlfVisual::Flags()const
CAlfVisual::HasTactileFeedback(TInt)const
CAlfVisual::HorizontalOrigin()const
CAlfVisual::HorizontalPadding()const
CAlfVisual::Identifier()const
CAlfVisual::IsTagged()const
CAlfVisual::Layout()const
CAlfVisual::LocalToDisplay(const TAlfRealPoint &)const
CAlfVisual::LocalToDisplay(const TPoint &)const
CAlfVisual::MaxSize()const
CAlfVisual::MaxSizeInBaseUnits()const
CAlfVisual::Mimic(CAlfVisual &,TInt)
CAlfVisual::MinSize()const
CAlfVisual::MinSizeInBaseUnits()const
CAlfVisual::Move(const TAlfRealPoint &,TInt)
CAlfVisual::Move(const TPoint &,TInt)
CAlfVisual::MoveToFront(TInt)
CAlfVisual::Opacity()const
CAlfVisual::Owner()const
CAlfVisual::Padding()const
CAlfVisual::PaddingAsMetric()const
CAlfVisual::PaddingInPixels()const
CAlfVisual::Pause(TInt)
CAlfVisual::Pos()const
CAlfVisual::RemoveTactileFeedback(TInt)
CAlfVisual::Resume(TInt)
CAlfVisual::SetCenteredPosAndSize(const TAlfRealPoint &,const TAlfRealSize &,TInt)
CAlfVisual::SetCenteredPosAndSize(const TPoint &,const TSize &,TInt)
CAlfVisual::SetClipping(TBool)
CAlfVisual::SetDepthOffset(const TAlfTimedValue &)
CAlfVisual::SetDisplay(CAlfDisplay *)
CAlfVisual::SetEffectL(const TDesC &)
CAlfVisual::SetFlag(TAlfVisualFlags)
CAlfVisual::SetFlags(TUint)
CAlfVisual::SetGroupEffectL(const TDesC &,TInt)
CAlfVisual::SetLayout(CAlfLayout *)
CAlfVisual::SetMaxSize(const TAlfRealSize &)
CAlfVisual::SetMaxSize(const TSize &)
CAlfVisual::SetMinSize(const TAlfRealSize &)
CAlfVisual::SetMinSize(const TSize &)
CAlfVisual::SetOpacity(const TAlfTimedValue &)
CAlfVisual::SetOrigin(TAlfVisualHOrigin,TAlfVisualVOrigin)
CAlfVisual::SetOwner(CAlfControl &)
CAlfVisual::SetPadding(TInt)
CAlfVisual::SetPadding(const TAlfBoxMetric &)
CAlfVisual::SetPadding(const TPoint &)
CAlfVisual::SetPos(const TAlfRealPoint &,TInt)
CAlfVisual::SetPos(const TAlfTimedPoint &)
CAlfVisual::SetRect(const TAlfRealRect &,TInt)
CAlfVisual::SetSize(const TAlfRealSize &,TInt)
CAlfVisual::SetSize(const TAlfTimedPoint &)
CAlfVisual::SetTactileFeedbackL(TInt,TInt)
CAlfVisual::SetTagL(const TDesC8 &)
CAlfVisual::Size()const
CAlfVisual::Tag()const
CAlfVisual::TagMatches(const TDesC8 &)const
CAlfVisual::Transformation()
CAlfVisual::VerticalOrigin()const
CAlfVisual::VerticalPadding()const
CAlfVisual::~CAlfVisual()
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Public Member Enumerations
enum TExpansionFlags { EExpandNone  = 0, EExpandHorizontally  = 1, EExpandVertically  = 2 }
Private Attributes
TLayoutPrivateData * iLayoutData

Constructor & Destructor Documentation

CAlfLayout()

IMPORT_C CAlfLayout ( )

Constructor.

~CAlfLayout()

IMPORT_C ~CAlfLayout ( )

Virtual destructor.

Member Functions Documentation

AddNewL(CAlfControl &, CAlfLayout *)

IMPORT_C CAlfLayout * AddNewL ( CAlfControl & aOwner,
CAlfLayout * aParentLayout = 0
) [static]

2-phased constructor which also gives ownedship to control.

Parameters

CAlfControl & aOwner
CAlfLayout * aParentLayout = 0 If given, has the parent layout.

Append(CAlfVisual *, TBool, TInt)

IMPORT_C TInt Append ( CAlfVisual * aVisual,
TBool aConstructedWithParentInformation = EFalse,
TInt aLayoutTransitionTime = 0
)

Parameters

CAlfVisual * aVisual Visual to append.
TBool aConstructedWithParentInformation = EFalse Whether visual already knows its parent
TInt aLayoutTransitionTime = 0

BaseUnit()

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.

Note:

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 .

ChildOrdinal(TInt)

IMPORT_C TInt ChildOrdinal ( TInt aIndex )

Determines the layout ordinal for a child visual. The child's placement depends on the ordinal number.

Parameters

TInt aIndex Index of the child visual.

ChildPos(TInt, TPoint &)

IMPORT_C TBool ChildPos ( TInt aOrdinal,
TPoint & aPos
)

Determines the position of a child visual according to the layout.

Parameters

TInt aOrdinal Layout ordinal of the child visual.
TPoint & aPos New position for the child.

ChildSize(TInt, TSize &)

IMPORT_C TBool ChildSize ( TInt aOrdinal,
TSize & aSize
)

Determines the size of a child visual according to the layout.

Parameters

TInt aOrdinal Layout ordinal of the child visual.
TSize & aSize New target size for the child.

ConstructL(CAlfControl &)

IMPORT_C void ConstructL ( CAlfControl & aOwner ) [virtual]

From CAlfVisual . Second-phase constructor.

Parameters

CAlfControl & aOwner

Count()

IMPORT_C TInt Count ( ) const

Returns the number of child visuals in the layout.

DoRemoveAndDestroyAllD()

IMPORT_C void DoRemoveAndDestroyAllD ( ) [protected, virtual]

CAlfVisual Deletes the child visuals

EffectiveLayoutOrdinal(const CAlfVisual &)

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.

Parameters

const CAlfVisual & aVisual

EnableScrollingL(TBool)

IMPORT_C void EnableScrollingL ( TBool aScrolling = ETrue )

Enables or disables scrolling in the layout.

Parameters

TBool aScrolling = ETrue ETrue to enable scrolling, EFalse to disable.

FindTag(const TDesC8 &)

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()

Parameters

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 (:).

FindVisual(CAlfVisual *)

IMPORT_C TInt FindVisual ( CAlfVisual * aVisual ) const

Finds a visual's index.

Parameters

CAlfVisual * aVisual Visual to look for.

HorizontalInnerPadding()

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

InnerPadding()

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

InnerPaddingAsMetric()

IMPORT_C const TAlfXYMetric & InnerPaddingAsMetric ( ) const

Returns the inner padding metric InnerPadding() which is superceded by this method

InnerPaddingInBaseUnits()

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.

Insert(CAlfVisual *, TInt)

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.

Parameters

CAlfVisual * aVisual Visual to append.
TInt aPosition

MoveVisualToBack(CAlfVisual &, TInt)

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).

MoveVisualToFront() Reorder()

Parameters

CAlfVisual & aVisual Child visual to move.
TInt aLayoutTransitionTime = 0 How long the transition should take visually, in milliseconds.

MoveVisualToFront(CAlfVisual &, TInt)

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!

Parameters

CAlfVisual & aVisual Child visual to move.
TInt aLayoutTransitionTime = 0 How long the transition should take visually, in milliseconds.

PropertyOwnerExtension(const TUid &, TAny **)

IMPORT_C void PropertyOwnerExtension ( const TUid & aExtensionUid,
TAny ** aExtensionParams
) [protected, virtual]

! future proofing

Parameters

const TUid & aExtensionUid
TAny ** aExtensionParams

Remove(CAlfVisual *, TInt)

IMPORT_C void Remove ( CAlfVisual * aVisual,
TInt aLayoutTransitionTime = 0
)

Parameters

CAlfVisual * aVisual Visual to remove.
TInt aLayoutTransitionTime = 0 How long the transition should take visually, in milliseconds.

RemoveAndDestroyAllD()

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.

Reorder(CAlfVisual &, TInt, TInt)

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.

MoveVisualToBack() MoveVisualToFront()

Parameters

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

ScrollOffset()

IMPORT_C const TAlfTimedPoint & ScrollOffset ( ) const

Returns the scroll offset of the layout. The scroll offset is in layout's base units.

Scrolling()

IMPORT_C TBool Scrolling ( ) const

Is scrolling in the layout.

SetBaseUnit(const TAlfMetric &)

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.

Note:

It is recommended to use EAlfUnitNormalized if proportional base units are required. For example, EAlfUnitRelativeToMySize would not make sense as a base unit.

Parameters

const TAlfMetric & aBaseUnit

SetBaseUnit(const TAlfXYMetric &)

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.

Parameters

const TAlfXYMetric & aBaseUnit

SetInnerPadding(const TPoint &)

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.

Note:

that the left and right paddings will be the same, and the top and bottom paddings will be the same.

migrate to using metrics instead

Parameters

const TPoint & aInnerPadding Inner padding (e.g., column, row separation).

SetInnerPadding(const TAlfXYMetric &)

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.

Note:

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

Parameters

const TAlfXYMetric & aInnerPadding Inner padding, using metrics.

SetScrollOffset(const TAlfTimedPoint &)

IMPORT_C void SetScrollOffset ( const TAlfTimedPoint & aPoint )

Set the scroll offset

Parameters

const TAlfTimedPoint & aPoint Sets the point.

SetTransitionTime(TInt)

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.

Parameters

TInt aTransitionTime Transition time in milliseconds, or KAlfLayoutDefaultTransitionTime.

TransitionTime()

IMPORT_C TInt TransitionTime ( ) const

Returns the transition time of this layout.

CAlfLayout::SetTransitionTime()

UpdateChildrenLayout(TInt)

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.

Parameters

TInt aTransitionTime = 0 Time for layout transition in milliseconds. Any negative value uses value given in CAlfEnv::StaticSetLayoutTransitionTime()

VerticalInnerPadding()

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

VirtualSize()

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.

Visual(TInt)

IMPORT_C CAlfVisual & Visual ( TInt aIndex ) const

Returns a child visual.

Parameters

TInt aIndex Index of the child visual.

Member Enumerations Documentation

Enum TExpansionFlags

Enumerators

EExpandNone = 0

Not expanding in any direction.

EExpandHorizontally = 1

Expands horizontally.

EExpandVertically = 2

Expands vertically.

Member Data Documentation

TLayoutPrivateData * iLayoutData

TLayoutPrivateData * iLayoutData [private]