/*

* 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 CHuiEnv, a common working environment for the Toolkit.

*

*/

#ifndef __HUIENV_H__

#define __HUIENV_H__

#include <e32base.h>

#include <w32std.h>

#include <barsread.h>

#include <coemain.h>

#include <uiacceltk/HuiTextureManager.h>

#include <uiacceltk/huifontmanager.h>

#include <uiacceltk/HuiCommand.h>

#include <uiacceltk/HuiObserverArray.h>

#include <uiacceltk/HuiRenderer.h>

#include <uiacceltk/huilowmemoryobserver.h>

/* Forward declarations */

class CCoeControl;

class CHuiStatic;

class CHuiDisplay;

class CHuiRosterImpl;

class CHuiSkin;

class CHuiScheduler;

class CHuiControl;

class CHuiControlGroup;

class CHuiVisualFactory;

class CHuiVisual;

class MHuiActionObserver;

class THuiEvent;

class CDirectScreenAccess;

class MHuiEventHandler;

class CHuiTextStyleManager;

class CHuiThemeManager;

class CHuiCanvasTextureCache;

class CHuiFxEngine;

class CHighResTimer;

const TInt KHuiEnvReleasedActionId = 0x200100F8;

const TInt KHuiEnvRestoredActionId = 0x200100F9;

/**

 * THuiRefreshMode modes can be used to define when the screen redraws

 * should be performed.

 * @see CHuiEnv::SetRefreshMode()

 */

enum THuiRefreshMode

    {

    /** Refresh occurs only when requested by calling CHuiEnv::RefreshCallBack(). */

    EHuiRefreshModeManual,

    /** Refresh is done automatically when necessary. */

    EHuiRefreshModeAutomatic, // = default

    /** Refresh is done all the time, even if nothing has changed. Dirty regions

        are not used for determining what has changed. Instead, displays are

        always fully redrawn. */

    EHuiRefreshModeForced

    };

/**

 * HUI environment observer. Instance of this class can be created

 * by user application and passed in constructor to CHuiEnv. The

 * observer class will be called for certain events.

 */

class MHuiEnvObserver

	{

public:

    /**

     * Called to create a new CHuiSkin derived object for the use

     * of the calling CHuiEnv object. This method can return

     * either an application specific Skin - object or NULL for

     * allowing CHuiEnv to create it's default Skin object. The calling

     * CHuiEnv will take responsibility of the created CHuiSkin object.

     *

     * @param aEnv The CHuiEnv object to which to create the

     *             new skin object.

     *

     * @return New instance of a CHuiSkin - derived object.

     */

    virtual CHuiSkin* CreateSkinL(CHuiEnv& aEnv) = 0;

    };

/**

 * Interface for observing action commands. When the scheduler executes an

 * action command, the registered listeners that implement this interface

 * will receive a notification of the action.

 */

class MHuiActionObserver

    {

public:

    /**

     * Called by the scheduler when an action command is executed.

     *

     * @param aActionCommand  The command that is being executed.

     */

    virtual void HandleActionL(const THuiActionCommand& aActionCommand) = 0;

    };

/**

 * CHuiEnv is a common working environment for the Toolkit. CHuiEnv manages

 * the common data for a HUITK application, such as displays, the texture

 * manager, visual factory and currently used skin.

 *

 * An application that uses HUITK will need to create one CHuiEnv. Also

 * destroying the CHuiEnv instance will clean up all resources associted

 * with the UI.

 *

 * @see NewL()

 * @see NewLC()

 */

NONSHARABLE_CLASS(CHuiEnv) : public CBase,

                             public MHuiTextureManagerStateChangedObserver,

                             public MHuiTextureLoadingCompletedObserver

    {

public:

    /* Types. */

    /** Flags for creating new displays. */

    enum TNewDisplayFlags

        {

        ENewDisplayFullScreen = 0x1,

        ENewDisplayOverlaid = 0x2

        };

    /** @beginAPI */

    /* Constructors and destructor. */

    /**

     * Constructs a new HUI environment. An application that uses HUI will

     * need to create one CHuiEnv. This will not start the timing used

     * inside Hitchcock UI Toolkit. The animation timing will be started

     * from the point in time when the first frame is drawn. So UI build up

     * and precalculation can be done without affecting the animation time.

     *

     * @param aRenderer  Rendering interface to use in the environment.

     * @param aObserver  Pointer to observer class instance that will be called

     *                   to perform application specific configurations. Can be

     *                   NULL to create a default CHuiEnv.

     *

     * @return  HUI environment.

     */

    IMPORT_C static CHuiEnv* NewL(THuiRenderer aRenderer = EHuiRendererDefault,

                                  MHuiEnvObserver* aObserver = NULL);

    /**

     * Constructs a new HUI environment and leaves it on the cleanup stack.

     * This will not start the timing used inside Hitchcock UI Toolkit. 

     * The animation timing will be started from the point in time when 

     * the first frame is drawn. So UI build up and precalculation can be 

     * done without affecting the animation time. 

     *

     * @param aRenderer  Rendering interface to use in the environment.

     * @param aObserver  Pointer to observer class instance that will be called

     *                   to perform application specific configurations. Can be

     *                   NULL to create a default CHuiEnv.

     *

     * @return  HUI environment.

     */

    IMPORT_C static CHuiEnv* NewLC(THuiRenderer aRenderer = EHuiRendererDefault,

                                   MHuiEnvObserver* aObserver = NULL);

    /** @endAPI */

    /**

     * Destructor.

     */

    virtual ~CHuiEnv();

    /* Methods. */

    /** @beginAPI */

    /**

     * Determines which renderer is currently in use. Always returns the real

     * explicit identifier of the renderer, and not an ambiguous identifier

     * like "Default".

     *

     * @return  THuiRenderer enum.

     */

    IMPORT_C THuiRenderer Renderer() const;

    /**

     * Creates a new HuiDisplay.

     *

     * @param aRect  Size of the display.

     * @param aNativeControl  Native control to which to associate the display.

     * @param aFlags  Flags for the display (TNewDisplayFlags).

     * @param aRosterOwningDisplay  The display that will share its roster.

     * @param aDisplayType  Display type.

     *

     * @return  Display.

     */

    IMPORT_C CHuiDisplay& NewDisplayL(const TRect& aRect,

                                      CCoeControl* aNativeControl = 0,

                                      TInt aFlags = 0,

                                      CHuiDisplay* aRosterOwningDisplay  = NULL,

                                      TInt aDisplayType = 0 );

    /**

     * Creates a new HuiDisplay.

     *

     * @param aRect  Size of the display.

     * @param aNativeControl  Native control to which to associate the display.

     * @param aFlags  Flags for the display (TNewDisplayFlags).

     * @param aRosterOwningDisplay  The display that will share its roster.

     * @param aDisplayType  Display type.

     * @param aBackBufferUid  Screen back buffer uid.

     *

     * @return  Display.

     */

    IMPORT_C CHuiDisplay& NewDisplayL(const TRect& aRect,

                                      CCoeControl* aNativeControl,

                                      TInt aFlags,

                                      CHuiDisplay* aRosterOwningDisplay,

                                      TInt aDisplayType,

                                      TUid aBackBufferUid );

    /**

     * Creates a new HuiDisplay.

     *

     * @param aNativeWindow  Native window to which to associate the display.

     * @param aFlags  Flags for the display (TNewDisplayFlags).

     * @param aRosterOwningDisplay  The display that will share its roster.

     * @param aDisplayType  Display type.

     * @param aBackBufferUid  Screen back buffer uid.

     *

     * @return  Display.

     */

    IMPORT_C CHuiDisplay& NewDisplayL(RWindow* aNativeWindow,

                                      TInt aFlags,

                                      CHuiDisplay* aRosterOwningDisplay,

                                      TInt aDisplayType,

                                      TUid aBackBufferUid );

    /**

     * Determines the number of displays currently created with NewDisplayL().

     *

     * @return  Display count.

     */

    IMPORT_C TInt DisplayCount() const;

    /**

     * Sets the refresh mode.

     *

     * @param aMode  New refresh mode.

     *

     * @see THuiRefreshMode

     */

    IMPORT_C void SetRefreshMode(THuiRefreshMode aMode);

    /**

     * Determines the environment's display refresh mode.

     *

     * @return  Refresh mode.

     */

    IMPORT_C THuiRefreshMode RefreshMode() const;

    /**

     * Sets the maximum allowed frame rate. Specify 0.0 to use the default limit.

     *

     * @param aFrameRate  New maximum frame rate in frames per second.

     */

    IMPORT_C void SetMaxFrameRate(TReal32 aFrameRate) __SOFTFP;

    /**

     * Continues normal display refreshing. If display refreshing is already

     * being done, calling this has no effect. This is called automatically

     * from inside the toolkit when something is done that may lead to a

     * visible change on a display. The application may also call this if it

     * has previously paused refresh with PauseRefresh().

     * This does not affect any timing. 

     *

     * @see CHuiStatic

     */

    IMPORT_C void ContinueRefresh();

    /**

     * Continues normal display refreshing. If display refreshing is already

     * being done, calling this has no effect. This is called automatically

     * from inside the toolkit when something is done that may lead to a

     * visible change on a display. The application may also call this if it

     * has previously paused refresh with PauseRefresh().

     * @param aFastFirstRefresh If ETrue and refresh timer is not active,

     * first refresh will be done as soon as possible. Otherwise first refresh

     * will occur after refresh timer has expred.  

     *

     * @see CHuiStatic

     */

    void ContinueRefresh(TBool aFastFirstRefresh);

    /**

     * Pauses display refreshing temporarily. This is called when it is clear

     * that any displays will not be updated soon. The application may call

     * this at times when it needs more processing time for other tasks.

     */

    IMPORT_C void PauseRefresh();

    /**

     * Constructs a new empty control group.

     *

     * @param aId (Resource) Identifier of the new group.

     *

     * @return  Reference to the new group.

     */

    IMPORT_C CHuiControlGroup& NewControlGroupL(TInt aId);

    /**

     * Deletes a previously loaded control group. The controls inside the

     * groups will also be destroyed. Note that this will also destroy the

     * visuals of the controls, because they are owned by the controls.

     *

     * @param aId  Identifier of the group to be deleted.

     *

     * @return  <code>KErrNone</code>, if the deletion is successful.

     *          <code>KErrNotFound</code>, if there are no control groups

     *          with the specified identifier.

     */

    IMPORT_C TInt DeleteControlGroup(TInt aId);

    /**

     * Load controls and a group from a resource definition and create a

     * HuiControlGroup out of them.

     *

     * @param aResourceId  Resource identifier of the group.

     *

     * @return  Control group with controls inside.

     */

    IMPORT_C CHuiControlGroup& LoadControlGroupL(TInt aResourceId);

    /**

     * Returns an existing control group based on its identifier.

     * @note Will panic with THuiPanic::EInternal if the specified

     * control group is not found.

     */

    IMPORT_C CHuiControlGroup& ControlGroup(TInt aResourceId);

    /**

     * "Loads" bitmaps specified in a resource. Works with all

     * supported image formats, including BMP, PNG and JPG. The resource

     * defines a numerical identifier for each bitmap. The bitmaps

     * are added to the texture manager in this environment and can be

     * accessed using the numerical identifiers.

     * @see TextureManager()

     *

     * @note Does not really _load_ the bitmaps to textures. Instead, the

     * bitmap filenames are bound to the id:s specified by the resource. The

     * texture ids may be later used to load the texture resource (by calling

     * CHuiTextureManager::LoadTextureL() with the id).

     *

     * @see CHuiTextureManager::LoadTextureL()

     * @see CHuiTextureManager::TextureL()

     * @see CHuiTextureManager::Texture()

     *

     * @todo The bitmap resource file format is not documented.

     *

     * @param aResourceId Resource containing a list of bitmap file names.

     */

    IMPORT_C void LoadBitmapsL(TInt aResourceId);

    /**

     * Returns the visual factory.

     */

    IMPORT_C CHuiVisualFactory& VisualFactory() const;

    /**

     * Returns the texture manager.

     */

    IMPORT_C CHuiTextureManager& TextureManager() const;

    /**

     * Returns the font manager object.

     */

    IMPORT_C THuiFontManager& FontManager() const;

    /**

     * Returns the text style manager.

     */

    IMPORT_C CHuiTextStyleManager& TextStyleManager() const;

    /**

     * Finds a control from the control groups of this

     * environment.

     * @param aId The id of the control to find.

     * @see CHuiControl::SetId()

     * @see CHuiControl::Id()

     * @return The control instance, or NULL if no such control exists.

     */

    IMPORT_C CHuiControl* FindControl(TInt aId) const;

    /**

     * Schedule a command.

     *

     * @param aCommand  Command to send.

     * @param aDelayMilliSeconds  Time in ms to wait before executing the command. If

     * set to zero, the command is executed immediately. Note that the point of

     * execution may not be exactly this amount of milliseconds.

     *

     * @return  System-wide error code. If successful, returns <code>KErrNone</code>.

     */

    IMPORT_C TInt Send(const THuiCommand& aCommand, TInt aDelayMilliSeconds = 0);

    /**

     * Schedule a command. Leaves if there is a failure when posting the command

     * to the scheduler.

     *

     * @param aCommand  Command to send.

     * @param aDelayMilliSeconds  Time to wait before executing the command.

     */

    IMPORT_C void SendL(const THuiCommand& aCommand, TInt aDelayMilliSeconds = 0);

    /**

     * Cancel commands related to an object. This object may be a timed value,

     * a visual, MHuiEventHandler, or anything you can do commands on.

     *

     * @param aObject Any commands owned by this object will be cancelled.

     *                Note that you must cast derived classes that are passed,

     *                otherwise the pointer will point to the base class.

     */

    IMPORT_C void CancelCommands(TAny* aObject);

    /**

     * Overloaded version of CancelCommands, especially for classes derived from

     * MHuiEventHandler, so that correct pointer will be used.

     * @see CHuiEnv::CancelCommands

     */

    IMPORT_C void CancelCommands(MHuiEventHandler* aObject);

    /**

     * Overloaded version of CancelCommands, especially for classes derived from

     * MHuiEventHandler, so that correct pointer will be used.

     * @see CHuiEnv::CancelCommands

     */

    IMPORT_C void CancelCommands(TAny* aObject,

                                 THuiOp aCommandOperation);

    /**

     * Overloaded version of CancelCommands, especially for classes derived from

     * MHuiEventHandler, so that correct pointer will be used.

     * @see CHuiEnv::CancelCommands

     */

    IMPORT_C void CancelCommands(TAny* aObject,

                                 THuiCommandType aCommandType,

                                 TInt aParam);

    /**

     * Time until the given command will be executed on the given object.

     * 

     * @param aObject The object that is waiting for a command to be executed.

     *                Note that you must cast derived classes that are passed,

     *                otherwise the pointer will point to the base class.     

     * @param aCommandType  Type of command.     

     * @return  Time interval in milliseconds. -1, if no commands found.

     */

    IMPORT_C TInt TimeUntilCommand(TAny* aObject,

                                   THuiCommandType aCommandType);

    /**

     * Returns the skin that is used by the environment. Only one skin can be

     * used at a time.

     */

    IMPORT_C CHuiSkin& Skin() const;

    /**

     * Starts the refresh timer with given tick interval. Can be used to

     * control how often the toolkit updates itself.

     *

     * @param aMilliSeconds  Milliseconds between ticks.

     */

    IMPORT_C void StartRefresh(TInt aMilliSeconds);

    /**

     * Starts the refresh timer with given tick interval. Can be used to

     * control how often the toolkit updates itself.

     *

     * @param aMilliSeconds  Milliseconds between ticks.

     * @param aDelayInMilliSeconds Milliseconds until first refrsh.

     */

     void StartRefresh(TInt aIntervalInMilliSeconds, TInt aDelayInMilliSeconds);

    /**

     * Handles a key event received from CONE.

     *

     * @param aKeyEvent  Received key event to handle.

     * @param aType      Type of event.

     * @param aAssocDisplay  Associated CHuiDisplay, if there is one.

     *                   If specified, the event is handled by this display's

     *                   roster only. If <code>NULL</code>, event is offered

     *                   to all displays.

     */

    IMPORT_C TBool HandleKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType,

                                   CHuiDisplay* aAssocDisplay = 0);

    /**

     * Sets the interval before an idle notification is sent. Idling

     * begins when no input has been received after this delay. 

     *