diff -r 000000000000 -r 05e9090e2422 uiresources_pub/skins_api/inc/AknsDrawUtils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiresources_pub/skins_api/inc/AknsDrawUtils.h Thu Dec 17 09:14:12 2009 +0200 @@ -0,0 +1,746 @@ +/* +* Copyright (c) 2002-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 a public static class AknsDrawUtils and related +* constants. +* +*/ + + +#ifndef AKNSDRAWUTILS_H +#define AKNSDRAWUTILS_H + +// INCLUDES +#include + +// CONSTANTS + +/** +* Default value for drawing parameters. +* +* @since 2.0 +*/ +static const TInt KAknsDrawParamDefault = 0x0; + +/** +* Drawing parameter that limits processing of layout levels to the first one. +* This can be used to temporarily disable secondary layout levels. +* +* @since 2.0 +*/ +static const TInt KAknsDrawParamLimitToFirstLevel = 0x1; + +/** +* Drawing parameter that suspends clearing under images. Only the first +* layout level is affected. +* +* @since 2.0 +*/ +static const TInt KAknsDrawParamNoClearUnderImage = 0x2; + +/** +* Drawing parameter that causes the layouts and bitmaps to be prepared, +* but no actual drawing takes place. +* +* @since 2.8 +*/ +static const TInt KAknsDrawParamPrepareOnly = 0x04; + +/** +* Drawing parameter that draws only the RGB channel of data. +* +* @since 3.0 +*/ +static const TInt KAknsDrawParamRGBOnly = 0x8; + +/** +* Drawing parameter that draws only the alpha channel of data. If the data +* is unmasked, the result is undefined. +* +* @since 3.0 +*/ +static const TInt KAknsSDMAlphaOnly = 0x10; +/** +* Drawing parameter that allows empty SCALABLEITEMS to use +* the parent bitmap directly +* +* @since 3.0 +*/ +static const TInt KAknsDrawParamChained = 0x20; + +/** +* Forces drawing the bottom level in chain to use RGBOnly. Bottom level is the +* first drawn level, visually the bottom most level. +* +* @since 3.0 +*/ +static const TInt KAknsDrawParamBottomLevelRGBOnly = 0x40; + +/** +* Ignores layer mask when drawing layers. +* +* @since 3.2 +*/ + +static const TInt KAknsDrawParamIgnoreLayerMask = 0x80; + +/** +* Direction, from where notes and queries slide to the screen. +* +* @since 3.1 +*/ +enum TSlidingMode + { + /** Sliding is disabled either by skin or compile time */ + ESlidingDisabled = 0, + + /** Slide from the CBA side */ + ESlidingFromCBA, + + /** Slide from left */ + ESlidingFromLeft, + + /** Slide from topleft */ + ESlidingFromTopLeft, + + /** Slide from top */ + ESlidingFromTop, + + /** Slide from topright */ + ESlidingFromTopRight, + + /** Slide from right */ + ESlidingFromRight, + + /** Slide from bottomright */ + ESlidingFromBottomRight, + + /** Slide from bottom */ + ESlidingFromBottom, + + /** Slide from bottomleft */ + ESlidingFromBottomLeft, + + /** Slide from random direction (any of the 8 directions) */ + ESlidingFromRandom + }; + + +// FORWARD DECLARATIONS +class MAknsSkinInstance; +class MAknsControlContext; +class CWindowGc; +class CFbsBitGc; +class CCoeControl; + +// CLASS DECLARATION + +/** +* Static utility class to support Avkon Skins drawing operations. +* AknsDrawUtils provides utility methods to perform skin-aware drawing +* operations, such as background drawing. +* +* This is a public static class with exported functions. +* The class is not intended for derivation outside the library. +* +* @lib AknSkins.lib +* +* @since 2.0 +*/ +class AknsDrawUtils + { + public: // New functions + + /** + * Returns pointer to the current control context. + * If aMop parameter is specified retrieves the nearest control context + * in control hierarchy. If none is found (or @c NULL parameter was + * given) returns @c NULL. + * + * @since 2.0 + * + * @param aMop Object provider to be used to find the control context + * or @c NULL. + * + * @return Pointer to the nearest control context or @c NULL if none + * was found. + */ + IMPORT_C static MAknsControlContext* ControlContext( + const MObjectProvider* aMop ); + + /** + * Returns pointer to the control context of the parent of the given + * control. The context possibly supplied by the control itself is ignored. + * + * @since 2.6 + * + * @param aControl Pointer to CCoeControl or @c NULL. + * + * @return Pointer to the nearest control context of the parent control + * or @c NULL if none was found. + */ + IMPORT_C static MAknsControlContext* ControlContextOfParent( + const CCoeControl* aControl ); + + /** + * Draws background with assumed origin. + * Draws bacground to the specified rectangle. Origin is assumed + * to be (0,0). This overload can not be used with parent absolute + * layouts. + * + * See @c DrawBackground for details on chained layouts. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. If @c NULL and skin + * instance was given, default parameters are used. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aRect Rectangle to be drawn. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. + */ + IMPORT_C static TBool Background( MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, CWindowGc& aGc, const TRect& aRect ); + + /** + * Draws background with proper origin. + * Draws bacground to the specified rectangle. The origin is queried + * from the control position list (if given using + * AknsUtils::RegisterControlPosition). If not found, the origin is + * queried from the given control, which may result in a window server + * flush. + * + * See @c DrawBackground for details on chained layouts. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. Must be specified, if + * aInstance is not @c NULL. + * + * @param aControl Control that knows the current window. + * Must be specified if parent absolute layout can be used, + * otherwise @c NULL may be given. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aRect Rectangle to be drawn. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. Note that many scalable skins implicitly define + * background bitmaps for seemingly blank areas. + */ + IMPORT_C static TBool Background( MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, const CCoeControl* aControl, + CWindowGc& aGc, const TRect& aRect ); + + /** + * Draws background with proper origin and drawing parameters. + * Draws bacground to the specified rectangle. The origin is queried + * from the control position list (if given using + * AknsUtils::RegisterControlPosition). If not found, the origin is + * queried from the given control, which may result in a window server + * flush. Drawing parameters may be used to control drawing. + * + * See @c DrawBackground for details on chained layouts. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. Must be specified, if + * aInstance is not @c NULL. + * + * @param aControl Control that knows the current window. + * Must be specified if parent absolute layout can be used, + * otherwise @c NULL may be given. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aRect Rectangle to be drawn. + * + * @param aDrawParam Bitwise combination of drawing parameters. + * @c KAknsDrawParamDefault should be used if no special handling + * is required. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. Note that many scalable skins implicitly define + * background bitmaps for seemingly blank areas. + */ + IMPORT_C static TBool Background( MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, const CCoeControl* aControl, + CWindowGc& aGc, const TRect& aRect, const TInt aDrawParam ); + + /** + * Draws background to the given graphics context. + * The origin is queried from the control position list (if given using + * AknsUtils::RegisterControlPosition). If not found, the origin is + * queried from the given control, which may result in a window server + * flush. + * + * If background contains multiple layers, they are drawn in the + * sequence specified by the context. If multiple contexts are chained + * (using @c SetParentContext), they are drawn in reverse order, i.e. + * the context given as parameter to this method call is drawn last. + * + * Drawing parameter KAknsDrawParamNoClearUnderImage is automatically + * assumed for all the chained contexts, except the deepest one. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. Must be specified, if + * aInstance is not @c NULL. + * + * @param aControl Control that knows the current window. + * Must be specified if parent absolute layout can be used, + * otherwise @c NULL may be given. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aDstPos Destination position (top-left corner of the area + * to be drawn) in graphics context coordinate system. + * + * @param aControlRect Rectangle (in the control coordinate system) + * to be drawn. + * + * @param aDrawParam Bitwise combination of drawing parameters. + * @c KAknsDrawParamDefault should be used if no special handling + * is required. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. Note that many scalable skins implicitly define + * background bitmaps for seemingly blank areas. + */ + IMPORT_C static TBool DrawBackground( MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, const CCoeControl* aControl, + CBitmapContext& aGc, const TPoint& aDstPos, + const TRect& aControlRect, const TInt aDrawParam ); + + /** + * Draws background between rects. + * Draws bacground between specified rectangles. Origin is assumed + * to be (0,0). + * + * See @c DrawBackground for details on chained layouts. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. If @c NULL and skin + * instance was given, default parameters are used. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aOuterRect Outer rectangle. + * + * @param aInnerRect Inner rectangle. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. Note that many scalable skins implicitly define + * background bitmaps for seemingly blank areas. + */ + IMPORT_C static TBool BackgroundBetweenRects( + MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, CWindowGc& aGc, + const TRect& aOuterRect,const TRect& aInnerRect ); + + /** + * Draws background between rects. + * Draws bacground between specified rectangles. + * + * See @c DrawBackground for details on chained layouts. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. Must be specified if + * aInstance is not @c NULL. + * + * @param aControl Control that knows the current window. + * Must be specified if parent absolute layout can be used, + * otherwise @c NULL may be given. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aOuterRect Outer rectangle. + * + * @param aInnerRect Inner rectangle. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. Note that many scalable skins implicitly define + * background bitmaps for seemingly blank areas. + */ + IMPORT_C static TBool BackgroundBetweenRects( + MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, const CCoeControl* aControl, + CWindowGc& aGc, + const TRect& aOuterRect,const TRect& aInnerRect ); + + /** + * Draws background between rects. + * Draws bacground between specified rectangles with drawing parameters. + * + * @since 2.0 + * + * @param aInstance Pointer to skin instance as obtained from + * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared + * without bitmap. + * + * @param aContext Control context to obtain context specific + * information about background drawing. Must be specified if + * aInstance is not @c NULL. + * + * @param aControl Control that knows the current window. + * Must be specified if parent absolute layout can be used, + * otherwise @c NULL may be given. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aOuterRect Outer rectangle. + * + * @param aInnerRect Inner rectangle. + * + * @param aDrawParam Bitwise combination of drawing parameters. + * @c KAknsDrawParamDefault should be used if no special handling + * is required. + * + * @return ETrue if background was drawn with a bitmap, EFalse + * otherwise. Note that many scalable skins implicitly define + * background bitmaps for seemingly blank areas. + */ + IMPORT_C static TBool BackgroundBetweenRects( + MAknsSkinInstance* aInstance, + MAknsControlContext* aContext, const CCoeControl* aControl, + CWindowGc& aGc, + const TRect& aOuterRect, const TRect& aInnerRect, + const TInt aDrawParam ); + + /** + * Determines whether background drawing would be done with + * a bitmap (deprecated). + * + * @param aInstance Pointer to skin instance. If @c NULL, + * method returns EFalse. + * + * @param aContext Control context, or @c NULL if no context + * is used. Note that absence of control context affects + * the result. + * + * @return @c ETrue if background would be drawn with a bitmap, + * @c EFalse otherwise. If a scalable skin is currently active, + * the return value is undefined, and does not necessarily + * reflect the return value of the actual drawing operation. + * + * @deprecated This method is deprecated as of release 2.8. + * Use the return values of background drawing functions to + * determine whether the background was drawn with skinned + * content. The return value is always ETrue starting from + * rel 3.1 + */ + IMPORT_C static TBool HasBitmapBackground( + MAknsSkinInstance* aInstance, + MAknsControlContext* aContext ); + + /** + * Draws a cached image (with its attributes specified in the skin) + * to the given rectangle. + * + * @param aInstance Pointer to the skin instance. If @c NULL, + * the method returns immediately. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aRect Rectangle specifying the pane used for drawing. The + * image is laid out within the rectangle. + * + * @param aID Item ID of the image to be drawn. + */ + IMPORT_C static void DrawCachedImage( MAknsSkinInstance* aInstance, + CWindowGc& aGc, const TRect& aRect, const TAknsItemID& aID ); + + /** + * Draws a cached image (with its attributes specified in the skin) + * to the given rectangle in an off-screen graphics context. + * + * @since 2.8 + * + * @param aInstance Pointer to the skin instance. If @c NULL, + * the method returns immediately. + * + * @param aGc Bitmapped graphics context to be used for drawing. + * + * @param aRect Rectangle specifying the pane used for drawing. The + * image is laid out within the rectangle. + * + * @param aID Item ID of the image to be drawn. + */ + IMPORT_C static void DrawCachedImage( MAknsSkinInstance* aInstance, + CFbsBitGc& aGc, const TRect& aRect, const TAknsItemID& aID ); + + /** + * Draws a frame (with cached images) to the specified area. + * + * @param aInstance Pointer to the skin instance. If @c NULL, the + * method returns EFalse. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aOuterRect Outer rectangle of the frame. Frame elements + * will be drawn within this rectangle. + * + * @param aInnerRect Inner rectangle of the frame. Frame center + * will be drawn within this rectangle. + * + * @param aFrameID Item ID of the entire frame. + * + * @param aCenterID Item ID of the center part of the frame. If + * @c KAknsIIDNone, no center will be drawn. If @c KAknsIIDDefault, + * the default value from the frame itself will be used. Other values, + * the item to be used for the center part. If the frame is + * specified as 1 part graphics in the skin instead of 9 part + * graphics, this parameter has no effect. + * + * @return EFalse, if the frame was not drawn at all. ETrue, if the + * frame was (at least partially) drawn. + */ + IMPORT_C static TBool DrawFrame( MAknsSkinInstance* aInstance, + CWindowGc& aGc, const TRect& aOuterRect, const TRect& aInnerRect, + const TAknsItemID& aFrameID, const TAknsItemID& aCenterID ); + + /** + * Prepares the frame graphics for drawing. This function should be + * called when the frame sizes are known and in places where Flushing + * the Window server buffer will not cause flicker. For example, a + * good place to call PrepareFrame() would be controls SizeChanged + * function. Altough its not mandatory to call PrepareFrame() + * before DrawFrame(), it's highly recommended in order to avoid + * unnecessary flushes in the middle of the actual drawing routine. + * + * Note that the rect parameters must be exactly the same for + * PrepareFrame and subsequent DrawFrame calls. Otherwise the + * DrawFrame functions will cause a flush, which leads + * to flicker. + * + * @since 2.8 + * + * @param aInstance Pointer to the skin instance. If @c NULL, the + * method returns EFalse. + * + * @param aOuterRect Outer rectangle of the frame. Frame elements + * are scaled to this size. + * + * @param aInnerRect Inner rectangle of the frame. Frame center + * is scaled to this size + * + * @param aFrameID Item ID of the entire frame. + * + * @param aCenterID Item ID of the center part of the frame. If + * @c KAknsIIDNone, no center part will be prepared. + * If @c KAknsIIDDefault, the default value from the frame + * itself will be used. Other values, the item to be used + * for the center part. If the frame is specified as 1 part + * graphics in the skin instead of 9 part graphics, this + * parameter has no effect. + * + * @return EFalse, if were nothing to prepare. ETrue, if the + * frame was (at least partially) prepared. + */ + IMPORT_C static TBool PrepareFrame( MAknsSkinInstance* aInstance, + const TRect& aOuterRect, const TRect& aInnerRect, + const TAknsItemID& aFrameID, const TAknsItemID& aCenterID); + + /** + * Draws a frame (with cached images) to the specified area + * in an off-screen graphics context. + * + * @since 2.8 + * + * @param aInstance Pointer to the skin instance. If @c NULL, the + * method returns EFalse. + * + * @param aGc Bitmapped graphics context to be used for drawing. + * + * @param aOuterRect Outer rectangle of the frame. Frame elements + * will be drawn within this rectangle. + * + * @param aInnerRect Inner rectangle of the frame. Frame center + * will be drawn within this rectangle. + * + * @param aFrameID Item ID of the entire frame. + * + * @param aCenterID Item ID of the center part of the frame. If + * @c KAknsIIDNone, no center will be drawn. If @c KAknsIIDDefault, + * the default value from the frame itself will be used. Other values, + * the item to be used for the center part. If unsure, specify + * @c KAknsIIDDefault. If the frame is specified as 1 part + * graphics in the skin instead of 9 part graphics, this + * parameter has no effect. + * + * @param aDrawParam Bitwise combination of drawing parameters. + * @c KAknsDrawParamDefault should be used if no special handling + * is required. + * + * @return EFalse, if the frame was not drawn at all. ETrue, if the + * frame was (at least partially) drawn. + */ + IMPORT_C static TBool DrawFrame( MAknsSkinInstance* aInstance, + CFbsBitGc& aGc, const TRect& aOuterRect, const TRect& aInnerRect, + const TAknsItemID& aFrameID, const TAknsItemID& aCenterID, + const TInt aDrawParam ); + + /** + * Draws a frame (with cached images) to the specified area + * in an off-screen graphics context. + * + * @since 2.8 + * + * @param aInstance Pointer to the skin instance. If @c NULL, the + * method returns EFalse. + * + * @param aGc Bitmapped graphics context to be used for drawing. + * + * @param aOuterRect Outer rectangle of the frame. Frame elements + * will be drawn within this rectangle. + * + * @param aInnerRect Inner rectangle of the frame. Frame center + * will be drawn within this rectangle. + * + * @param aFrameID Item ID of the entire frame. + * + * @param aCenterID Item ID of the center part of the frame. If + * @c KAknsIIDNone, no center will be drawn. If @c KAknsIIDDefault, + * the default value from the frame itself will be used. Other values, + * the item to be used for the center part. If unsure, specifi + * @c KAknsIIDDefault. If the frame is specified as 1 part + * graphics in the skin instead of 9 part graphics, this + * parameter has no effect. + * + * @return EFalse, if the frame was not drawn at all. ETrue, if the + * frame was (at least partially) drawn. + */ + IMPORT_C static TBool DrawFrame( MAknsSkinInstance* aInstance, + CFbsBitGc& aGc, const TRect& aOuterRect, const TRect& aInnerRect, + const TAknsItemID& aFrameID, const TAknsItemID& aCenterID ); + + /** + * Draws the specified part of the frame (with a cached image) to the + * specified rectangle. + * + * @par Compatibility note: + * Prior to Series 60 release 2.8, the entire outer rectangle could + * be given as the rectangle of a corner part. Due to scalable UI + * compatibility, this is no longer supported in release 2.8, and thus + * the exact corner rectangle is required. This funtion may not + * function correctly if the skin specifies the frame as 1 part + * graphics. + * + * @param aInstance Pointer to the skin instance. If @c NULL, the + * method returns @c EFalse. + * + * @param aGc Graphics context to be used for drawing. + * + * @param aRect Rectangle for drawing. This must be the rectangle + * of the specific part of the drawn that will be drawn, e.g. + * top-left corner rectangle if the top-left corner is being drawn. + * + * @param aFrameID Item ID of the entire frame. + * + * @param aFrameElement Element (index) of the frame element to + * be drawn. + * + * @return ETrue, if the element was drawn. EFalse otherwise. + */ + IMPORT_C static TBool DrawFramePart( MAknsSkinInstance* aInstance, + CWindowGc& aGc, const TRect& aRect, const TAknsItemID& aFrameID, + const TAknsFrameElementIndex aFrameElement ); + + /** + * Returns a boolean value indicating whether list separator lines + * should be drawn. + * + * This method checks: + * - The value of @c KAknsIIDPropertyListSeparatorLines property. + * - The presence of (non-scalable) column bitmaps. + * If found, @c EFalse is returned. + * - The presence of generic list background (non-scalable). + * If found, @c EFalse is returned. + * + * Note that the exact internal implementation of the checks is + * subject to change. + * + * @since 2.8 + * + * @param aInstance Pointer to the skin instance. If @c NULL, + * the method returns @c ETrue. + * + * @return @c ETrue, if list separator lines should drawn. + * @c EFalse, if list separator lines should not be drawn + * and, consequently, list column and slice bitmaps (if any) from the + * skin content should be drawn. + */ + IMPORT_C static TBool IsListSeperatorLines( + MAknsSkinInstance* aInstance ); + + /** + * Returns an enum value indicating the way notes and queries appear + * to the screen (sliding animation) + * + * @since 3.1 + * + * @param aInstance Pointer to the skin instance. If @c NULL, + * the method returns @c ESlidingDisabled. + * + * @return @c Sliding mode from enumeration TSlidingMode + */ + IMPORT_C static TSlidingMode SlidingMode( + MAknsSkinInstance* aInstance ); + + private: // Prohibited constructors and destructor + + // Construction prohibited (static class) + AknsDrawUtils(); + // Destruction prohibited (static class) + ~AknsDrawUtils(); + }; + +#endif // AKNSDRAWUTILS_H + +// End of File