/*

* 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 CHuiVisual. Visuals are graphical entities visible on a display

*

*/

#ifndef __HUIVISUAL_H__

#define __HUIVISUAL_H__

#include <e32base.h>

#include <e32std.h>

#include <uiacceltk/HuiTimedPoint.h>

#include <uiacceltk/huimetric.h>

#include <uiacceltk/HuiRealRect.h>

#include <uiacceltk/HuiRealPoint.h>

#include <uiacceltk/HuiRealSize.h>

#include <uiacceltk/HuiOwnedPointer.h>

#include <uiacceltk/HuiBrush.h>

#include <uiacceltk/HuiBrushArray.h>

#include <uiacceltk/HuiSessionObject.h>

/* Forward declarations. */

class CHuiEnv;

class CHuiControlGroup;

class CHuiSkin;

class CHuiControl;

class MHuiEventHandler;

class CHuiDisplay;

class CHuiLayout;

class CHuiGc;

class CHuiVisual;

class CHuiTransformation;

class CHuiDropShadow;

class CHuiFxEffect;

class CHuiFxEffectParser;

class MHuiEffectable;

class CHuiCanvasRenderBuffer;

/** Visual types. */

enum THuiVisualType

    {

    EHuiVisualTypeVisual,

    EHuiVisualTypeLine,

    EHuiVisualTypeText,

    EHuiVisualTypeImage,

    EHuiVisualTypeMesh,

    EHuiVisualTypeCanvas

    };

/**

 * Visual flags.

 *

 * @see CHuiVisual::SetFlag()

 * @see CHuiVisual::SetFlags()

 * @see CHuiVisual::Flags() 

 * @see CHuiVisual::ClearFlag() 

 * @see CHuiVisual::ClearFlags()  

 */

enum THuiVisualFlags

    {

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

    EHuiVisualFlagManualSize = 0x1,

    EHuiVisualFlagManualPosition = 0x2,

    EHuiVisualFlagManualLayout = EHuiVisualFlagManualSize |

                                 EHuiVisualFlagManualPosition,

    EHuiVisualFlagBlendAdd = 0x4,

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

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

    EHuiVisualFlagLayoutUpdateNotification = 0x8,

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

    EHuiVisualFlag3DProjection = 0x10,

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

    EHuiVisualFlagNoDepthOcclusion = 0x20,

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

        display horizon is used instead. */

    EHuiVisualFlagLocalHorizon = 0x40,

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

    EHuiVisualFlagClipping = 0x80,

    /** Visual is using a horizontal center origin, i.e., the X coordinate

        of the visual's position defines its horizontal center point. */

    EHuiVisualFlagHOriginCenter = 0x100,

    /** Visual is using a right edge origin, i.e., the X coordinate

        of the visual's position defines its right edge. */

    EHuiVisualFlagHOriginRight = 0x200,

    /** Visual is using a vertical center origin, i.e., the Y coordinate

        of the visual's position defines its vertical center point. */

    EHuiVisualFlagVOriginCenter = 0x400,

    /** Visual is using a bottom edge origin, i.e., the Y coordinate

        of the visual's position defines its bottom edge. */

    EHuiVisualFlagVOriginBottom = 0x800,

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

    EHuiVisualChanged = 0x1000,

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

    EHuiVisualFlagNoDepthUpdate = 0x2000,

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

    EHuiVisualFlagManualTransitionTime = 0x4000,

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

    EHuiVisualFlagDrawAfterOthers = 0x10000,

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

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

    EHuiVisualFlagFreezeLayout = 0x20000,

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

        interaction. */

    EHuiVisualFlagIgnorePointer = 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. 

     */

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

     */    

    EHuiVisualFlagEnableDebugMode  = 0x100000,

    /** 

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

     **/

    EHuiVisualFlagInactive = 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.

     **/

    EHuiVisualFlagOpaqueHint = 0x400000,

    /** 

     * \internal

     * Setting this flag means that visual is not drawn to the normal place in visual tree.

     * If some canvas visual has set this visual as an external content visual, it is drawn there.

     * This is used only for canvas visuals and this is for internal use only.

     **/    

    EHuiVisualFlagDrawOnlyAsExternalContent = 0x800000,

    EHuiVisualFlagShouldBeHidden = 0x1000000,

    EHuiVisualFlagShouldDestroy = 0x2000000,

    EHuiVisualFlagShouldBeInactive = 0x4000000,

	EHuiVisualFlagAlwaysDraw = 0x8000000,

    /**

     * This indicates that this visual is completely under another opaque visual.

     * So this is a hint, set by client, that the toolkit can use to optimize drawing.

     */

    EHuiVisualFlagUnderOpaqueHint = 0x10000000,

    EHuiVisualFlagShouldBeUnderOpaqueHint = 0x20000000,

    EHuiVisualFlagShouldBeShown = 0x40000000,

    // visual that is used only by wserv

    EHuiVisualFlagWserv = 0x80000000,

    EHuiVisualFlagLast = 0xFFFFFFFF

    };

/** Horizontal origin of a visual. */

enum THuiVisualHOrigin

    {

    EHuiVisualHOriginLeft = 0,

    EHuiVisualHOriginCenter = 1,

    EHuiVisualHOriginRight = 2

    };

/** Vertical origin of a visual. */

enum THuiVisualVOrigin

    {

    EHuiVisualVOriginTop = 0,

    EHuiVisualVOriginCenter = 1,

    EHuiVisualVOriginBottom = 2

    };

enum THuiReferenceState

 	{

  	EHuiReferenceStateNow = 0,

  	EHuiReferenceStateTarget = 1

  	};

const TInt KHuiTactileFeedbackEventTypeNone = -1;

/**

 * Interface for visual owners. A class that owns a visual must implement 

 * this interface. Visual owners are expected to destroy their visuals when

 * the owner is destroyed.

 */

class MHuiVisualOwner

    {

public:

    IMPORT_C virtual ~MHuiVisualOwner();

    /**

     * Returns the environment where this visual belongs into.

     *

     * @return  Environment.

     */

    virtual CHuiEnv& Env() const = 0;

    /**

     * Determines the control group in which the owner belong to. If the owner

     * does not belong to a control group, <code>NULL</code> is returned.

     *

     * @return Control group or <code>NULL</code>.

     */

    virtual CHuiControlGroup* ControlGroup() const = 0;

    /**

     * Returns the event handler resposible for handling events related to 

     * the visual, for example when the visual receives a pointer down event.

     */

    virtual MHuiEventHandler* EventHandler() = 0;

	/**

	 * Appends a visual to the visual owner. 

	 *

	 * @param aVisual  Visual to append. The owner receives ownership

	 * of the visual.

	 *

     * @return Reference to appended visual.

	 */

    virtual void AppendL(CHuiVisual* aVisual) = 0;

	/**

	 * Removes a visual from the owner. 

	 *

	 * @param aVisual  Visual to remove. 

	 *

	 * @return Pointer to removed visual. Caller gets ownership.

	 */

	virtual void Remove(CHuiVisual* aVisual) = 0;

    /**

     * Removes a visual from the ownership of the owner. This is called when

     * the visual is being destroyed.

     *

     * @param aVisual  Visual to remove.

     */

    virtual void VisualDestroyed(CHuiVisual& aVisual) = 0;

    /**

     * Notifies the owner that the layout of a visual has been recalculated.

     * Called only when the EHuiVisualFlagLayoutUpdateNotification flag has

     * been set for the visual.

     *

     * @param aVisual  Visual that has been laid out.

     */

    virtual void VisualLayoutUpdated(CHuiVisual& aVisual) = 0;

	/**

	 * Notifies the visual owner if there was an error (a leave happened)

	 * when preparing the visual for drawing. Typically the resource alloc

	 * errors such as out of memory is escalated through this callback.

	 * 

     * @param aVisual    Visual that caused the error.

     * @param aErrorCode Symbian KErr error code for the failure.

	 */

    virtual void VisualPrepareDrawFailed(CHuiVisual& aVisual, TInt aErrorCode) = 0;

    };

/**

 * Visuals are graphical entities visible on a display. They are responsible

 * for maintaining their state independently.

 *

 * Visuals use a hierarchical coordinate system. All coordinate values are

 * specified in the base unit of the parent layout, relative to the parent 

 * visual's upper left corner. This is called the local coordinate system of

 * the visual. Visuals that have no parent are relative to the upper left 

 * corner of the HuiDisplay.

 *

 * In practice, this means that when a layout is moved 10 pixels to the right,

 * all of its children are automatically also moved 10 pixels to the right

 * on the screen.

 *

 * Visuals can be tagged with human-readable descriptors. @see SetTagL()

 *

 * Note that all layouts are derived from CHuiVisual. Layout visuals are

 * used for building visual trees. @see CHuiLayout

 */

class CHuiVisual : public CBase, public MHuiBrushGuide, public MHuiSessionObject

    {

public:

    /* Constructors and destructor. */

    /** @beginAPI */

    /**

     * Constructs and appends a new visual to the owner control.

     *

     * @param aOwnerControl  Control that will own the new visual.

     *

     * @return  The new visual.

     */

    IMPORT_C static CHuiVisual* AddNewL(CHuiControl& aOwnerControl,

                                        CHuiLayout* aParentLayout = 0);

    /**

     * Constructor.

     *

     * @param aEnv    The environment where this visuals belongs to.

     * @param aOwner  Owner control.

     */

    IMPORT_C CHuiVisual(MHuiVisualOwner& aOwner);

    /**

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

     */

    IMPORT_C virtual void ConstructL();

    /**

     * Destructor.

     */

    IMPORT_C ~CHuiVisual();

    /* New Methods. */

    /**

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

     * are first removed from their owner.

     */

    IMPORT_C virtual void RemoveAndDestroyAllD();

    /**

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

     * a visual could have a single tag, for example ("caption").

     * The tag descriptor of the visual may contain multiple tags,

     * for example: "tag1:tag2:tag3".

     *

     * Tags can be used for identifying visuals. In a typical use case, a control

     * could identify which of its visuals represent certain elements of the

     * control based on the tag descriptors. In this case, the tags would be

     * set by an outside party that also sets the tags of the visuals.

     *

     * @param aTag  Tag descriptor for the visual.

     *

     * @see CHuiVisual::Tag()

     * @see CHuiVisual::IsTagged()

     * @see CHuiVisual::FindTag()

     */

    IMPORT_C void SetTagL(const TDesC8& aTag);

    /**

     * Determines the tag of the visual.

     *

     * @return  Tag descriptor of the visual.

     *

     * @see CHuiVisual::SetTagL()

     * @see CHuiVisual::IsTagged()

     * @see CHuiVisual::FindTag()

     */

    IMPORT_C const TDesC8& Tag() const;

    /**

     * Determines if the visual has a tag.

     *

     * @return  <code>ETrue</code>, if the visual has been tagged with SetTagL().

     *          <code>EFalse</code> otherwise.

     *

     * @see CHuiVisual::Tag()

     * @see CHuiVisual::SetTagL()

     * @see CHuiVisual::FindTag()

     */

    IMPORT_C TBool IsTagged() const;

    /**

     * Finds a visual whose tag descriptor contains a specific tag.

     *

     * CHuiVisual::FindTag() is the basic implementation that checks if

     * this visual's tag matches the specified tag. CHuiLayout::FindTag()

     * extends the search into child visuals, covering recursively entire

     * visual hierarchies.

     *

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

     *

     * @see CHuiVisual::Tag()

     * @see CHuiVisual::SetTagL()

     * @see CHuiVisual::IsTagged()

     * @see CHuiLayout::FindTag()

     */

    IMPORT_C virtual CHuiVisual* FindTag(const TDesC8& aTag);

    /**

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

     *

     * @param aFlag  Flag to set.

     */

    IMPORT_C void SetFlag(THuiVisualFlags aFlag);

    /**

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

     *

     * @param aAnyFlags  One or more flags to set.

     */

    IMPORT_C void SetFlags(TInt aAnyFlags);

    /**

     * Unset flags that affect the visual's behaviour.

     *

     * @param aFlag  Flag to clear.

     */

    IMPORT_C void ClearFlag(THuiVisualFlags aFlag);

    /**

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

     *

     * @param aAnyFlags  One or more flags to clear.

     */

    IMPORT_C void ClearFlags(TInt aAnyFlags);

    /**

     * Returns the flags of the visual.

     */

    inline TInt Flags() const;

    /**

     * Returns the owner of the visual.

     */

    IMPORT_C MHuiVisualOwner& Owner() const;

    /**

     * Sets the owner of the visual.

     *

     * @param aOwner  New owner of the visual.

     */

    IMPORT_C void SetOwner(MHuiVisualOwner& aOwner);

    /**

     * Returns the number of child visuals.

     */

    IMPORT_C virtual TInt Count() const;

    /**

     * Returns a child visual.

     *

     * @param aIndex  Index of the child visual.

     *

     * @return  Reference to a child visual.

     */

    IMPORT_C virtual CHuiVisual& Visual(TInt aIndex) const;

    /**

     * Returns the layout this visual belongs to.

     */

    IMPORT_C CHuiLayout* Layout() const;

    /**

     * Sets the layout this visual belongs to.

     */

    void SetLayout(CHuiLayout* aLayout);

    /**

     * Returns the environment of the visual.

     */

    IMPORT_C CHuiEnv& Env() const;

    /**

     * Returns the skin of the owner control's environment.

     */

    IMPORT_C CHuiSkin& Skin() const;

    /**

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

     *

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

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

     */

    IMPORT_C CHuiDisplay* Display() const;