/*
* 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:   Display class.
*
*/



#ifndef C_ALFDISPLAY_H
#define C_ALFDISPLAY_H

#include <e32base.h>
#include <alf/alfdisplaybackgrounditem.h>
#include <alf/alfevent.h>

class CAlfEnv;
class CAlfRoster;
class MAlfInputCapabilitiesSupplier;
class MObjectProvider;
class TPointerEvent;


/* Screen buffer uids */
const TUid KAlfUidBackBufferAll = 			{0x2000e59d}; // Not used
const TUid KAlfUidBackBufferScreen0 = 		{0x2000e59e};
const TUid KAlfUidBackBufferScreen1 = 		{0x2000e59f};
const TUid KAlfUidBackBufferTvOutNormal = 	{0x2000e5a0};
const TUid KAlfUidBackBufferTvOutWide = 	{0x2000e5a1};

/**
 * Rendering quality enumerator. 
 *
 * @see CAlfDisplay::SetQuality()
 * @see CAlfDisplay::Quality()
 */
enum TAlfQuality
    {
    /** Accurate quality ensures the best visual quality. */
    EAlfQualityAccurate,

    /** Fastest rendering speed in exchange for lower quality. */
    EAlfQualityFast
    };

/**
*  The intended usage of the display. The display may use this info to 
*  prioritize the HW usage and route content.
*  Vendor specific meanings may be used at the end of the enum space.
*
*  @see CAlfDisplay::SetUsageL()
*/
enum TAlfDisplayUsageHint
    {
    EAlfDisplayUsageGeneric        = 0x00000001,
    EAlfDisplayUsage3D             = 0x00000002,
    EAlfDisplayUsageVideoPlayback  = 0x00000004,
    EAlfDisplayUsageVideoCapture   = 0x00000008,
    EAlfDisplayUsageViewfinder     = 0x00000010,
    EAlfDisplayUsageStillImage     = 0x00000011,
    EAlfDisplayUsageVendorSpecific = 0x80000000
    };

/**
 *  Display class represents a drawing area on which UI Accelerator Toolkit
 *  draws it's contents. 
 *  
 *  The display always occupies a rectangular area of a rendering surface. 
 *  Usually the display occupies the whole rendering surface but it can also 
 *  occupy only parts of the rendering surface. Multiple displays can then 
 *  occupy multiple parts of the same rendering surface. This can be achieved 
 *  by setting the visible area of a display through 
 *  CAlfDisplay::SetVisibleArea() - method.
 *
 *  There should always be at least one display on which the contents of an
 *  application UI can be drawn to. The display can be one of the several 
 *  display types listed in CAlfDisplay::TDisplayType.
 *
 *  Before any visual content is drawn on the display, the display area is
 *  cleared. Different parts of the display can be cleared with different 
 *  methods and can be configured using the 
 *  CAlfDisplay::SetBackgroundItemsL() - method. Alternatively the clearing 
 *  mode to clear the whole display area can be assigned using 
 *  CAlfDisplay::SetClearBackgroundL() - method.
 *
 *  A display contains always a CAlfRoster - object which defines the drawing
 *  order of the CAlfControlGroup objects in the UI, controls the order in 
 *  which events are passed from control group to another and defines which
 *  control groups are shown and hidden at any given time.
 *
 *  To construct a display, use the CAlfEnv::NewDisplayL() - method.
 *  Usage:
 *  @code
 *  CAlfDisplay* display = iEnv->NewDisplayLiEnv->NewDisplayL( ClientRect(), 
 * 				CAlfEnv::ENewDisplayAsCoeControl );
 * 
 *  @endcode
 *  @lib alfclient.lib
 *  @since S60 v3.2
 */
NONSHARABLE_CLASS( CAlfDisplay ): public CBase
    {
public:

    /* Types. */

    /**
     * Background clear modes. Different clear modes can be taken into use 
     * with CAlfDisplay::SetClearBackgroundL() - method.
     */
    enum TClearMode
        {
        /**
         * Do not clear. This is more like an optimization flag.
         * Using this with OpenGL ES renderer results
         * to undefined (Trashed) background - so be sure to display content
         * that fills the entire screen. With the BITGDI renderer the
         * behavior is similar but the display are will show the previously
         * rendered avkon content (if any).
         */
        EClearNone = EFalse,

        /**
         * Clear with a solid color.
         */
        EClearWithColor = ETrue,

        /**
         * Clear with the skin background texture.
         */
        EClearWithSkinBackground
        };

    /** Display types. */
    enum TDisplayType
        {
        /** @deprecated: Primary LCD display. */
        EDisplayLcd0 = 0x0,              
 
        /** @deprecated: TV out */
        EDisplayTvOut = 0x2,

        /** @deprecated: TV out widescreen */
        EDisplayTvOutWide = 0x3,

        /** Physical screen */
        EDisplayNormal = 0x10,     
 
        /** Not used. Virtual display */
        EDisplayVirtual = 0x20,

        /** @deprecated: Off screen buffer */
        EDisplayOffScreenBuffer = 0x40
        };
                
    /**
     * Constructor
     *
     * To construct a new display, use CAlfEnv::NewDisplayL() - method.
     */
    CAlfDisplay();
    
    /**
     * ConstructL
     *
     * To construct a new display, use CAlfEnv::NewDisplayL() - method.
     */
    void ConstructL(
        CAlfEnv& aEnv, 
        TBool aAsCoeControl,
        const TRect& aRect, 
        CAlfRoster* aSharedRoster,
        TInt aDisplayType, 
        TUid aBufferUid);

    /**
     * Destructor.
     */
    virtual ~CAlfDisplay();

    /**
     * Sets the flag that tells the display to clear the background before
     * doing a refresh. Creates new objects required to be able to clear
     * the background with the defined mode.
     *
     * @param aClearBackground  Background clearing mode. For example EFalse,
     *                          ETrue, EClearWithColor,
     *                          EClearWithSkinBackground are the valid 
     *                          alternatives. EClearWithColor is equivalent to 
     *                          ETrue. EFalse is equivalent to EClearNone.
     *
     * @see CAlfDisplay::TClearMode
     */
    IMPORT_C void SetClearBackgroundL(TInt aClearBackground);

    /**
     * Sets the items that specify how to clear display before display
     * refresh. Items may have overlapping rectangles, drawing order is same 
     * as item order in the parameter array. But having lots of overlapping 
     * drawing causes negative performance impact.
     *
     * This method is alternative to SetClearBackgroundL().
     *
     * @see SetClearBackgroundL()
     * @param aItems Array of items that specify how to clear the background.
     *
     */
    IMPORT_C void SetBackgroundItemsL(
                    const RArray<TAlfDisplayBackgroundItem>& aItems);
    
    /**
     * Returns the roster of the display.
     * @return The roster.
     */
    IMPORT_C CAlfRoster& Roster();

    /**
     * Returns the roster of the display.
     * @return The roster.
     */
    IMPORT_C const CAlfRoster& Roster() const;
    
    /**
     * Sets the visible area of the display. The visible area is the area on
     * the display's rendering surface where the display is drawn. Normally
     * a display covers the entire rendering surface, but in the situation
     * where multiple displays are drawn on the same surface, this would be
     * used to define the visible area of each display.
     * Note: This does not set the visible area if alf server session is not focused
     * 
     * @param aArea  Visible area for the display.
     */
    IMPORT_C void SetVisibleArea(const TRect& aArea);

    /**
     * Sets the visible area of the display. Similar to SetVisibleArea.
     * But this sets the visible area even though alf server session is not focused.
     * Shall be used by client app when Dynamic layout switch happens. 
     *
     * @param aArea  Visible area for the display.
     */
    IMPORT_C void ForceSetVisibleArea(const TRect& aArea);
    
    /**
     * Returns the visible area of the display.
     *
     * @return  Visible area of the display. Affected by display orientation
     *          so that the returned rectangle uses the oriented coordinate
     *          space.
     */
    IMPORT_C TRect VisibleArea() const;
    
    /**
     * Returns the environment of the display.
     */
    IMPORT_C CAlfEnv& Env();
    
    /**
     * Return the server side handle
     *
     * @return Handle to the server side CAlfSrvDisplaySubSession object. 0 if
     *         not set.
     */
    TInt ServerHandle() const;
    
    /**
     * Set the current focused editor. 
     */
    IMPORT_C void SetFocusedEditor(
                    MAlfInputCapabilitiesSupplier* aCurrentEditor);

    /**
     * Flag the entire display as dirty.
     */
    IMPORT_C void SetDirty();
    
    /**
     * Sets the rendering quality of the display.
     *
     * @param aRenderingQuality One of the quality enumerators in TAlfQuality.
     */
    IMPORT_C void SetQuality(TAlfQuality aRenderingQuality);

    /**
     * Determines the rendering quality of the display.
     *
     * @return TAlfQuality enumerator that represents the rendering quality
     *         setting.
     */
    IMPORT_C TAlfQuality Quality() const;
    
    /**
     * Sets the flag that enables the use of depth testing.
     *
     * @param aUseDepth  <code>ETrue</code> to enable depth.
     */
    IMPORT_C void SetUseDepth(TBool aUseDepth);
        
    /**
    * Method to return an object provider interface for this display.
    *
    * @return a pointer or NULL to an MObjectProvider interface
    */
    IMPORT_C MObjectProvider* ObjectProvider() const;

    /**
     * Tells display the intended usage of the display. Display may use this
     * information to optimize the drawing.
     *
     * @param aUsageHint
     *
     *   Possible values for parameter are:
     *   - EAlfDisplayUsageGeneric 
     *   - EAlfDisplayUsage3D      
     *   - EAlfDisplayUsageVideoPlayback
     *   - EAlfDisplayUsageVideoCapture 
     *   - EAlfDisplayUsageViewfinder   
     *   - EAlfDisplayUsageStillImage   
     *   - EAlfDisplayUsageVendorSpecific + n
     *  
     *  Supported values depend on display type
     *  and underlying HW.
     * 
     *  @see TAlfDisplayUsageHint
     */    
    IMPORT_C void SetUsageL(TUint aUsageHint);

    /**
     * Suppresses automatic fading by display. This applies only to displays that are tied
     * to windows. By default, automatic fading is enabled.
     * @param aSuppress ETrue to suppress, EFalse to enable automatic fading.
     * @return error code, KErrNone upon success.
     */
    IMPORT_C TInt SuppressAutomaticFading( TBool aSuppress = ETrue );

    /**
     * Visual content will be drawn to the given window. The visual can be a visual tree i.e.
     * layout visual. The visual will not be any more drawn to the original place. The window
     * need not to be a full screen window. Giving NULL as aVisual will remove the binding,
     * and visual content will be drawn to the original place again.
     *
     * @param aWindow  Application window.
     * @param aVisual  Visual or layout visual.
     */
	IMPORT_C void SetClientWindowForDrawingL(RWindow* aWindow, CAlfVisual* aVisual);

    /** @endAPI */
    
    /**
     * Handles layout change.
     */
    void NotifyLayoutChangedL();

    /**
    * Accesses whether this CAlfDisplay is focused. 
    * A display should normally be focused. It will not be focused at least in
    * the following cases:
    *  - a non-ALF window in the current application is present in front of
    *    this AlfDisplay
    *  - a non-ALF window in another application is present in front of this
    *    AlfDisplay
    *
    * @return the focus state
    */
    TBool IsFocused() const;

    /**
     * Forwards a pointer event received from CONE. This can be called directly by application
     * to pass in external pointer events. You will have to call this from an application to pass
     * pointer events to CAlfControl - derived objects if you have created the CAlfDisplay 
     * class as offscreen buffer that has no native window to grab pointerevents automatically.
     *
     * @param aPointerEvent  Received pointer event to handle. Note that iParentPosition of the 
     * pointerevent should always be in the same coordinate space as where the displays rect 
     * was defined when it was created.
     */
    IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

private:

    /**
     * Chacks screen size.
     */
    void CheckScreenRect(TRect aRect);


private:
    
    // Private data. Owned.
    struct TPrivateData;
    TPrivateData* iData;
     
    };

#endif // C_ALFDISPLAY_H