/*

* Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   Defines CHuiLayout class. Layouts are visuals that manage 

*                the placement of a set of child visuals.

*

*/

#ifndef __HUILAYOUT_H__

#define __HUILAYOUT_H__

#include <e32base.h>

#include <uiacceltk/HuiVisual.h>

#include <uiacceltk/huimetric.h>

/* Forward declarations */

class CHuiEnv;

class CHuiControl;

/** Layout types. */

enum THuiLayoutType

    {

    EHuiLayoutTypeLayout,

    EHuiLayoutTypeFlow,

    EHuiLayoutTypeGrid,

    EHuiLayoutTypeApp,

    EHuiLayoutTypeAnchor

    };

/**

 * 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 <strong>size of a layout

 * is not available when your controls ConstructL is executed</strong>, 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:

 *

 * <code>

 * layout->SetFlags(EHuiVisualFlagLayoutUpdateNotification);

 * </code>

 *

 * .. and override VisualLayoutUpdated() method in your control.

 *

 * @see SetSize()

 * @see SetFlags()

 * @see 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 

 * @c 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.

 *

 * @see CHuiAnchorLayout

 * @see CHuiGridLayout

 *

 * Applications 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.

 */

class CHuiLayout : public CHuiVisual

    {

public:

    enum TExpansionFlags

        {

        /** Not expanding in any direction. */

        EExpandNone = 0,

        /** Expands horizontally. */

        EExpandHorizontally = 1,

        /** Expands vertically. */

        EExpandVertically = 2

        };

    /** @beginAPI */

    /* Constructors and destructor. */

    /**

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

     *

     * @param aOwnerControl  Owner control.

     * @param aParentLayout  Parent layout for the new layout.

     */

    IMPORT_C static CHuiLayout* AddNewL(CHuiControl& aOwnerControl,

                                        CHuiLayout* aParentLayout = 0);

    /**

     * Constructor.

     */

    IMPORT_C CHuiLayout(MHuiVisualOwner& aOwner);

    /**

     * Destructor.

     */

    IMPORT_C ~CHuiLayout();

    /**

     * Second-phase constructor from CHuiVisual, must be called in deriving class

     */

    IMPORT_C void ConstructL();

    /* Methods. */

    /**

     * 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 RemoveAndDestroyAllD();

    /**

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

     *

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

     *

     * @return  Visual whose tag descriptor matches the tag. <code>NULL</code>,

     *          if no such visual could be found. If a visual is returned,

     *          it will either be this visual or one of its descendants.

     *

     * @see CHuiVisual::Tag()

     * @see CHuiVisual::SetTagL()

     * @see CHuiVisual::IsTagged()

     * @see CHuiVisual::FindTag()

     */

    IMPORT_C CHuiVisual* FindTag(const TDesC8& aTag);

    /**

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

     *

     * @param aVisual  Visual to append.

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

     *

     * @todo  Add a method for appending multiple visuals in one set, so that

     *        they only cause a single layout update.

     */

    IMPORT_C void AppendL(CHuiVisual* aVisual, 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.

     *

     * @param aVisual  Visual to append.

     * @param TInt     Position to insert. This is the new ordinal number of the visual.

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

     */

    IMPORT_C void InsertL(CHuiVisual* aVisual, TInt aPosition, TInt aLayoutTransitionTime = 0);

    /**

     * Remove a visual from the layout.

     *

     * @param aVisual  Visual to remove.

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

     * @todo  Add a method for removing multiple visuals in one set, so that

     *        they only cause a single layout update.

     */

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

    /**

     * From CHuiVisual. Returns the number of child visuals in the layout.

     */

    IMPORT_C TInt Count() const;

    /**

     * From CHuiVisual. Returns a child visual.

     *

     * @param aIndex  Index of the child visual.

     *

     * @return  Reference to a child visual.

     */

    IMPORT_C CHuiVisual& Visual(TInt aIndex) const;

    /**

     * Finds a visual's index.

     *

     * @param aVisual  Visual to look for.

     *

     * @return  Index of the visual, or <code>KErrNotFound</code>.

     */

    IMPORT_C TInt FindVisual(const CHuiVisual* aVisual) const;

     /**

     * From CHuiVisual. Sets the position of the layout.

     * @param aPos             Target position, in the local coordinate system as

     *                         defined by the parent layout (or the display, 

     *                         if there is no parent).

     * @param aTransitionTime  Transition time in milliseconds.

     */

    IMPORT_C void SetPos(const THuiRealPoint& aPos, TInt aTransitionTime = 0);

    /**

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

     *

     * @param aSize                 Size to set the layout to.

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

     */

    IMPORT_C void SetSize(const THuiRealSize& aSize, TInt aTransitionTime = 0);

    /**

     * From CHuiVisual. Update the layout of all children. Subclasses can call this to

     * recalculate the layout of all children.

     *

     * @param aTransitionTime  Time for layout transition.

     */

    IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);

    /**

     * New virtual method. Update the layout of one child visual.

     *

     * @param aIndex           Child visual index.

     * @param aTransitionTime  Time for layout transition.

     */

    IMPORT_C virtual void UpdateChildLayout(TInt aIndex, TInt aTransitionTime = 0);

    /**

     * Sets the inner padding of the layout. This is typically the amount

     * of empty space between child visuals in the layout.

     *

     * @param aInnerPadding  Inner padding (e.g., column, row separation).

     */

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

     *

     * @param aInnerPadding  Inner padding, using metrics.

     */

    IMPORT_C void SetInnerPadding(const THuiXYMetric& aInnerPadding);

    /**

     * Returns the current inner padding.

     */

    IMPORT_C const THuiXYMetric& InnerPadding() const;

    /**

     * Returns the inner horizontal padding. 

     * @deprecated This is useless, use InnerPaddingInBaseUnits() instead.

     */

    IMPORT_C TInt HorizontalInnerPadding() const;

    /**

     * Returns the inner vertical padding.

     * @deprecated This is useless, use InnerPaddingInBaseUnits() instead.

     */

    IMPORT_C TInt VerticalInnerPadding() 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 THuiRealPoint InnerPaddingInBaseUnits() const __SOFTFP;

    /**

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

     *

     * @param aScrolling  <code>ETrue</code> to enable scrolling,

     *                    <code>EFalse</code> to disable.

     */

    IMPORT_C void EnableScrollingL(TBool aScrolling = ETrue);

    /**

     * Indicates whether scrolling is enabled in this layout.

     * @see EnableScrolling()

     *

     * @return ETrue if scrolling is enabled, EFalse otherwise.

     */

    IMPORT_C TBool Scrolling() const;

    /**

     * Returns the scroll offset of the layout. The scroll offset is in

     * layout's base units. The scroll offset has to be enabled before this 

     * method is called.

     * @see EnableScrollingL()

     *

     * @return  Reference to timed point that defines the scroll offset.

     *

     * @panic THuiPanic::ELayoutNotScrolling  Scrolling is not enabled.

     */

    IMPORT_C THuiTimedPoint& ScrollOffset();

    IMPORT_C const THuiTimedPoint& ScrollOffset() const;

    /**

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

     * @see BaseUnit()

     * @see EnableScrollingL()

     *

     * @param aOffset Offset in layout's base units.

     * @param aTransitionTime Time when the offset is to be reached in milliseconds.

     */

    IMPORT_C void SetScrollOffsetInBaseUnits(const THuiRealPoint& aOffset, TInt aTransitionTime = 0);

    /**

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

     *

     * @return  Virtual size.

     *

     * @panic THuiPanic::ELayoutNotScrolling  Scrolling is not enabled.

     */

    IMPORT_C TSize VirtualSize() 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.

     *

     * @return  Effective ordinal for the child visual.

     *

     * @panic  THuiPanic::ELayoutChildVisualNotFound  aVisual is not a child

     *         of this layout.

     */

    IMPORT_C TInt EffectiveLayoutOrdinal(const CHuiVisual& aVisual) const;

    /**

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

     *

     * @param aVisual    Child visual to move.

     * @param aPosition  New position (and ordinal number)

     * 					 in the child list (0 = first, Count()-1 = last).

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.

     * @see MoveVisualToBack()

     * @see MoveVisualToFront()

     */

    IMPORT_C void Reorder(CHuiVisual& aVisual, TInt aPosition, 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.

     *

     * @param aVisual  Child visual to move.

     * @see MoveVisualToBack()

     * @see Reorder()

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

     *

     * @see MoveVisualToFront() - Use this instead!

     */

    IMPORT_C void MoveVisualToFront(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).

     *

     * @param aVisual  Child visual to move.

     * @param aLayoutTransitionTime How long the transition should take visually, in milliseconds.     

     * @see MoveVisualToFront()

     * @see Reorder()

     */

    IMPORT_C void MoveVisualToBack(CHuiVisual& aVisual, TInt aLayoutTransitionTime = 0);

    /**

     * Notifies children of the change in the environment's skin.

     */

    IMPORT_C void NotifySkinChangedL();

    /**

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

     *

     * @param aTransitionTime  Transition time in milliseconds.

     *

     * @see CHuiLayout::SetTransitionTime()     

     * @see CHuiVisual::SetFlag()     

     * @see EHuiVisualFlagManualTransitionTime

     */

    IMPORT_C void SetTransitionTime(TInt aTransitionTime);

    /**

     * Returns the transition time of this layout.

     *

     * @return  Transition time in milliseconds, or

     *          KHuiLayoutDefaultTransitionTime.

     *

     * @see CHuiLayout::SetTransitionTime()

     * @see CHuiVisual::SetFlag()     

     * @see EHuiVisualFlagManualTransitionTime     

     */

    IMPORT_C TInt TransitionTime() const;

    /**

     * Determines the layout ordinal for a child visual. The child's placement

     * depends on the ordinal number.

     *

     * @param aIndex  Index of the child visual.

     */

    IMPORT_C virtual TInt ChildOrdinal(TInt aIndex);

	/**

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

	 * 

	 * @return ETrue if the prepare succeeded, or EFail if 

	 * the prepare failed. Failing to prepare a draw 

	 * terminates the screen refresh and drawing 

	 * for the current frame.

	 * 

	 * @see MHuiVisualOwner::VisualPrepareDrawFailed()

	 */

	IMPORT_C TBool PrepareDrawL();	

    /**

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