/*

* Copyright (c) 2006 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:   Base class for visuals

*

*/

#ifndef C_ALFVISUAL_H

#define C_ALFVISUAL_H

class CAlfEnv;

class CAlfVisual;

class CAlfControlGroup;

class CAlfControl;

class MAlfEventHandler;

struct TAlfBoxMetric;

class CAlfDropShadow;

#include <e32base.h>

#include <alf/alftimedvalue.h>

#include <alf/alfpropertyowner.h>

/** Visual types. */

enum TAlfVisualType

    {

    EAlfVisualTypeVisual,

    EAlfVisualTypeLine,

    EAlfVisualTypeText,

    EAlfVisualTypeLCTText,

    EAlfVisualTypeImage,

    EAlfVisualTypeMesh,

    EAlfVisualTypeCanvas

    };

/** Visual flags. */

enum TAlfVisualFlags

    {

    /** Manual layout means that layouts can't change the position and

        size of the visual; the owner of the visual is expected to

        manually maintain the visual's placement. */

    EAlfVisualFlagManualSize = 0x1,

    EAlfVisualFlagManualPosition = 0x2,

    EAlfVisualFlagManualLayout = EAlfVisualFlagManualSize |

                                 EAlfVisualFlagManualPosition,

    /** 

     * This enum is retained for source compatibility.

     * @deprecated 

     * @note See EAlfVisualFlagClipping

     */

    AlfVisualFlagClipping = 0x4,

    /** Notify owner control when the visual's layout has been updated.

        Notication is sent after all children have been updated. */

    EAlfVisualFlagLayoutUpdateNotification = 0x8,

    /** When the visual is drawn it will use a 3D projection. */

    EAlfVisualFlag3DProjection = 0x10,

    /** No depth test when drawing with a 3D projection. */

    EAlfVisualFlagNoDepthOcclusion = 0x20,

    /** Use a local horizon with a 3D projection. Otherwise, the global

        display horizon is used instead. */

    EAlfVisualFlagLocalHorizon = 0x40,

    /** Contents of the visual are clipped to its display rectangle. */

    EAlfVisualFlagClipping = 0x80,

    EAlfVisualFlagHOriginCenter = 0x100,

    EAlfVisualFlagHOriginRight = 0x200,

    EAlfVisualFlagVOriginCenter = 0x400,

    EAlfVisualFlagVOriginBottom = 0x800,

    /** Visual has changed and needs refresh. */

    EAlfVisualChanged = 0x1000,

    /** When the visual is drawn, the depth buffer shouldn't be updated. */

    EAlfVisualFlagNoDepthUpdate = 0x2000,

    /** Use the visual's local layout transition time, do not inherit from parent. */

    EAlfVisualFlagManualTransitionTime = 0x4000,

    /** Draw above the normal drawing order. */

    EAlfVisualFlagDrawAfterOthers = 0x10000,

    /** Do not automatically update the layout of children when doing 

        changes in a layout (e.g., when reordering children). */

    EAlfVisualFlagFreezeLayout = 0x20000,

    /** The visual will be ignored when checking for possible pointer event

        interaction. */

    EAlfVisualFlagIgnorePointer = 0x40000,

    /** 

     * automatically reverse the base unit sign in the X axis if the current locale setting is 

     * for mirrored layout

     *

     * @note this will only affect the positions of visuals contained

     * within layout visuals, the contents within a visual such as a text visual will not be 

     * affected. 

     */

    EAlfVisualFlagAutomaticLocaleMirroringEnabled = 0x80000,

    /** 

     * RnD: if set, some of the debug features are enabled. See programmers'

     * guide for more info.

     *

     * If the central repository has the setting to draw selected visual outline, 

     * setting this flag will draw outline for the visual and its child visuals

     */    

    EAlfVisualFlagEnableDebugMode  = 0x100000,

    //Code added by Devayani

    /** 

     * Setting this flag makes visual and its children Inactive i.e. it is ignored from roster operations 

     * - Draw, Handle event, change notifications etc.

     * Unsetting flag can again make visual tree active.

     * Note that flag change does not take effect unless that display area is refreshed.

     **/

    EAlfVisualFlagInactive = 0x200000,

    /** 

     * Setting this flag informs renderer that visual is to be considered as opaque and thus

     * renderer may choose not to draw visuals behind opaque visual. Note that visual

     * attribute "opacity" is not affected by this flag.

     **/

    EAlfVisualFlagOpaqueHint = 0x400000,

    EAlfVisualFlagLast = 0xFFFFFFFF

    };

/** Horizontal origin of a visual. */

enum TAlfVisualHOrigin

    {

    EAlfVisualHOriginLeft = 0,

    EAlfVisualHOriginCenter = 1,

    EAlfVisualHOriginRight = 2

    };

/** Vertical origin of a visual. */

enum TAlfVisualVOrigin

    {

    EAlfVisualVOriginTop = 0,

    EAlfVisualVOriginCenter = 1,

    EAlfVisualVOriginBottom = 2

    };

const TText KAlfTagSeparator = ':';

const TInt KAlfTactileFeedbackEventTypeNone = -1;

class CAlfControl;

class CAlfLayout;

class CAlfDisplay;

class CAlfEnv;

class CAlfBrushArray;

class CAlfGenComponent;

class MAlfMappingFunction;

class CAlfTransformation;

/** Fixed properties for visuals, Use these for efficient copying of visual properties. */ 

class AlfVisualProperties

    {

    public:

    enum 

        {

        ENone = 0x0,

        ESize = 0x1,

        EPosition = 0x2,

        EOpacity = 0x4,

        EDepthOffset = 0x8,

        ESecondaryImageAlpha = 0x10, 

        EScale = 0x20,

        EPosOffset = 0x40,

        ETextVisShadowOpacity = 0x80,

        EImageVisTurnAngle = 0x100,

        ELineVisThickness = 0x200,

        ELineVisShadowThickness = 0x400,

        ELineVisStartPos = 0x800,

        ELineVisEndPos = 0x1000,

        EMeshVisYawAngle = 0x2000, 

        EMeshVisPitchAngle = 0x4000,

        EMeshVisMaterial = 0x8000,

        ELayoutScrollOffset = 0x10000,

        // Add new properties here (next value: 0x20000)

        EAll = 0xFFFFFFFF

        };

    };

/**

 *  Visual base class

 *

 *  All visuals and layout are derived from this.

 *  Usage:

 *  @code

 *    // #1 Visual object usage

 *    CAlfVisual* newVisual = CAlfVisual::AddNewL( *myMainControl, mMainGridLayout );

 *    newVisual->EnableBrushesL();

 *    newVisual->Brushes->AppendL( borderBrush, EAlfHasOwnership );

 *    

 *   // #2 as a base class

 *   class CMyVisual : public CAlfVisual

 *       {    

 *   public:

 *       // allocation function

 *       CMyVisual(CAlfControl& aOwnerControl, CAlfLayout* aParentLayout = 0);  

 *    

 *       // Function documentation

 *       void MyVisualSpecificFunction();

 *   protected:

 *

 *       ~CAlfVisual();

 *   private:

 *       TInt mMyPrivateData;    

 *       };

 *  @endcode

 *  @lib alfclient.lib

 *  @since S60 v3.2

 */

class CAlfVisual : public CAlfPropertyOwner

    {

public:

    /**

     * Constructor

     */

    IMPORT_C CAlfVisual();

    /**

     * ConstructL

     */

    IMPORT_C virtual void ConstructL(CAlfControl& aOwner);

    /**

     * Destructor

     */

    IMPORT_C virtual ~CAlfVisual();

    /**

     * Destroys a hierarchy of visuals, along with this visual. The visuals

     * are first removed from their owner.

     */

    IMPORT_C virtual void RemoveAndDestroyAllD();

    /**

     * Return the server side handle

     *

     * @return Handle to the server side CAlfVisual object. 0 if not set.

     */

    IMPORT_C TInt Identifier() const;

    /**

     * Sets the layout this visual belongs to.

     *

     * @param aLayout Parent layout

     */

    void SetLayout(CAlfLayout* aLayout);

    /**

     * Set a flag that affects the visual's behaviour.

     *

     * @param aFlag  Flag to set.

     */

    IMPORT_C void SetFlag(TAlfVisualFlags aFlag);

    /**

     * Sets one or more flags that affect the visual's behaviour.

     *

     * @param aAnyFlags  One or more flags to set.

     */

    IMPORT_C void SetFlags(TUint aAnyFlags);

    /**

     * Unset flags that affect the visual's behaviour.

     *

     * @param aFlag  Flag to clear.

     */

    IMPORT_C void ClearFlag(TAlfVisualFlags aFlag);

    /**

     * Clear one or more flags that affect the visual's behaviour.

     *

     * @param aAnyFlags  One or more flags to clear.

     */

    IMPORT_C void ClearFlags(TUint aAnyFlags);

    /**

     * Returns the flags of the visual.

     * @return Flags.

     */

    IMPORT_C TUint Flags() const;

    /**

     * Returns the layout this visual belongs to.

     *

     * @return Parent layout. NULL if not set.

     */

    IMPORT_C CAlfLayout* Layout() const;

    /**

     * Returns the position of the visual. This is set by UpdateLayout().

     *

     * @return Position.

     */

    IMPORT_C TAlfTimedPoint Pos() const;

    /**

     * Sets the position of the visual.

     */

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

    /**

     * Returns the size of the visual. This is set by UpdateLayout().

     */

    IMPORT_C const TAlfTimedPoint Size() const;

    /**

     * Sets the size of the visual.

     */

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

    /**

     * Returns the overall opacity affecting the owner's visuals. All visuals 

     * owned by this object are affected by this opacity.

     *

     * @return  Timed value.

     */

    IMPORT_C const TAlfTimedValue& Opacity() const;

    /**

     * Set opacity

     *

     * @param aOpacity Opacity value.

     */

    IMPORT_C void SetOpacity( const TAlfTimedValue& aOpacity );

    /**

     * Returns the environment where this visual belongs into.

     *

     * @return  Environment.

     */

    IMPORT_C CAlfEnv& Env() const;

    /**

     * Returns the display of the visual (if shown).

     *

     * @return  Pointer to <code>CAlfDisplay</code> instance, or

     * <code>NULL</code> if no display is associated with the visual.

     */

    IMPORT_C CAlfDisplay* Display() const;

    /**

     * Sets the display on which the visual is being shown.

     *

     * @param aDisplay  Pointer to display onto which to attach the visual

     */

    void SetDisplay(CAlfDisplay* aDisplay);

    /**

     * Determines the tag of the visual.

     *

     * @return  Tag descriptor of the visual.

     *

     * @see CAlfVisual::SetTagL()

     * @see CAlfVisual::IsTagged()

     * @see CAlfVisual::FindTag()

     */

    IMPORT_C const TDesC8& Tag() const;

    /**

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

     * recalculate the layout of all children.

     *

     * @param aTransitionTime  Time for layout transition in milliseconds.

     *                         Any negative value uses value given in 

     *                         CAlfEnv::StaticSetLayoutTransitionTime()

     */

    IMPORT_C virtual void UpdateChildrenLayout(TInt aTransitionTime = 0);

    /**

     * Calculates the visual's bounding rectangle in display coordinates.

     * Display coordinates are defined relative to the display's visible area.

     * Uses the target values of the position and size, which means transitions

     * are always immediate in the returned rectangle.

     *

     * @return Rectange.

     */

    IMPORT_C TAlfRealRect DisplayRectTarget() const;

    /**

     * Convert local coordiantes to display coordinates.

     * Display coordinates are defined relative to the display's visible area.

     *

     * @return Converted point.

     */

    IMPORT_C TPoint LocalToDisplay(const TPoint& aPoint) const;

    /**

     * Convert local coordinates to display coordinates.

     * Display coordinates are defined relative to the display's visible area.

     *

     * @param aPoint  Point in local coordinates.

     * @return  Point in display coordinates.

     */

    IMPORT_C TAlfRealPoint LocalToDisplay(const TAlfRealPoint& aPoint) const;

    /*

     * Convert display coordinates to local coordinates.

     * Display coordinates are defined relative to the display's visible area.

     *

     * @param aPoint  Point in display coordinates.

     * @return  Point in local coordinates.

     */

    IMPORT_C TPoint DisplayToLocal(const TPoint& aPoint) const;

    /**

     * Convert display coordinates to local coordinate.

     * Display coordinates are defined relative to the display's visible area.

     *

     * @param aPoint  Point in display coordinates.

     * @return  Point in local coordinates.

     */

    IMPORT_C TAlfRealPoint DisplayToLocal(const TAlfRealPoint& aPoint) const;

    /**

     * Enables or disables brushes for the visual.

     */

    IMPORT_C void EnableBrushesL(TBool aEnabled = ETrue);

    /**

     * Returns the brushes of the visual.

     *

     * @return  Brush array. <code>NULL</code>, if not enabled.

     */

    IMPORT_C CAlfBrushArray* Brushes();

    /**

     * Moves the visual to the front inside its parent layout. 

     * In other words, the visual becames the last child of the parent.

     * Causes layout recalculation.

     */

    IMPORT_C void MoveToFront(TInt aTransitionTime = 0);

    /**

     * Enables or disables transformation of the control group.

     *

     * @param aIsTransformed ETrue for enabling.

     */

    IMPORT_C void EnableTransformationL( TBool aIsTransformed = ETrue );

    /**

     * Returns the transformation of the control group.

     *

     * @return  Transformation steps.

     */

    IMPORT_C CAlfTransformation& Transformation();

    /**

     * Sets the number of pixels that the visual uses for padding its contents.

     * Sets both the horizontal and vertical padding.

     *

     * @note that the left and right paddings will be the same, and the top and bottom

     *      paddings will be the same.

     * @deprecated migrate to using metrics instead

     *

     * @param aPadding  Number of padding pixels.

     */

    IMPORT_C void SetPadding(TInt aPadding);

    /**

     * Sets the number of pixels that the visual uses for padding its contents.

     * Sets the horizontal and vertical padding separately.

     *

     * @note that the left and right paddings will be the same, and the top and bottom

     *      paddings will be the same.

     * @deprecated migrate to using metrics instead

     *

     * @param aPadding  Number of padding pixels.

     */

    IMPORT_C void SetPadding(const TPoint& aPadding);

    /**

     * Sets the amount of padding that the visual uses for padding its contents.

     * The box metric can have a different amount on all sides.

     *

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

     *

     * @param aPadding  Amount of padding.

     */

    IMPORT_C void SetPadding(const TAlfBoxMetric& aPadding);

    /**

     * Returns the padding of the visual, in pixels.

     *

     * @return  Padding, in pixels. iTl.iX is the left padding, iTl.iY is 

     *          the top padding, iBr.iX is the right padding, and iBr.iY

     *          is the bottom padding. The width and height of the returned 

     *          rectangle are meaningless.

     */

    IMPORT_C TAlfRealRect PaddingInPixels() const;

    /**

     * Sets the tag of the visual.

     *

     * The tag is a descriptor, in the form of one or more colon-separated

     * character sequences. By default, visuals have no tag (""). Normally,