diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_visual_api/inc/alf/alfdisplay.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfdisplay.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,405 @@ +/* +* 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 +#include +#include + +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& 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 ETrue 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