2 * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
5 * under the terms of "Eclipse Public License v1.0"
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Defines a public static class AknsDrawUtils and related
20 #ifndef AKNSDRAWUTILS_H
21 #define AKNSDRAWUTILS_H
24 #include <AknsUtils.h>
29 * Default value for drawing parameters.
33 static const TInt KAknsDrawParamDefault = 0x0;
36 * Drawing parameter that limits processing of layout levels to the first one.
37 * This can be used to temporarily disable secondary layout levels.
41 static const TInt KAknsDrawParamLimitToFirstLevel = 0x1;
44 * Drawing parameter that suspends clearing under images. Only the first
45 * layout level is affected.
49 static const TInt KAknsDrawParamNoClearUnderImage = 0x2;
52 * Drawing parameter that causes the layouts and bitmaps to be prepared,
53 * but no actual drawing takes place.
57 static const TInt KAknsDrawParamPrepareOnly = 0x04;
60 * Drawing parameter that draws only the RGB channel of data.
64 static const TInt KAknsDrawParamRGBOnly = 0x8;
67 * Drawing parameter that draws only the alpha channel of data. If the data
68 * is unmasked, the result is undefined.
72 static const TInt KAknsSDMAlphaOnly = 0x10;
74 * Drawing parameter that allows empty SCALABLEITEMS to use
75 * the parent bitmap directly
79 static const TInt KAknsDrawParamChained = 0x20;
82 * Forces drawing the bottom level in chain to use RGBOnly. Bottom level is the
83 * first drawn level, visually the bottom most level.
87 static const TInt KAknsDrawParamBottomLevelRGBOnly = 0x40;
90 * Ignores layer mask when drawing layers.
95 static const TInt KAknsDrawParamIgnoreLayerMask = 0x80;
98 * Direction, from where notes and queries slide to the screen.
104 /** Sliding is disabled either by skin or compile time */
105 ESlidingDisabled = 0,
107 /** Slide from the CBA side */
110 /** Slide from left */
113 /** Slide from topleft */
116 /** Slide from top */
119 /** Slide from topright */
120 ESlidingFromTopRight,
122 /** Slide from right */
125 /** Slide from bottomright */
126 ESlidingFromBottomRight,
128 /** Slide from bottom */
131 /** Slide from bottomleft */
132 ESlidingFromBottomLeft,
134 /** Slide from random direction (any of the 8 directions) */
139 // FORWARD DECLARATIONS
140 class MAknsSkinInstance;
141 class MAknsControlContext;
149 * Static utility class to support Avkon Skins drawing operations.
150 * AknsDrawUtils provides utility methods to perform skin-aware drawing
151 * operations, such as background drawing.
153 * This is a public static class with exported functions.
154 * The class is not intended for derivation outside the library.
162 public: // New functions
165 * Returns pointer to the current control context.
166 * If aMop parameter is specified retrieves the nearest control context
167 * in control hierarchy. If none is found (or @c NULL parameter was
168 * given) returns @c NULL.
172 * @param aMop Object provider to be used to find the control context
175 * @return Pointer to the nearest control context or @c NULL if none
178 IMPORT_C static MAknsControlContext* ControlContext(
179 const MObjectProvider* aMop );
182 * Returns pointer to the control context of the parent of the given
183 * control. The context possibly supplied by the control itself is ignored.
187 * @param aControl Pointer to CCoeControl or @c NULL.
189 * @return Pointer to the nearest control context of the parent control
190 * or @c NULL if none was found.
192 IMPORT_C static MAknsControlContext* ControlContextOfParent(
193 const CCoeControl* aControl );
196 * Draws background with assumed origin.
197 * Draws bacground to the specified rectangle. Origin is assumed
198 * to be (0,0). This overload can not be used with parent absolute
201 * See @c DrawBackground for details on chained layouts.
205 * @param aInstance Pointer to skin instance as obtained from
206 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
209 * @param aContext Control context to obtain context specific
210 * information about background drawing. If @c NULL and skin
211 * instance was given, default parameters are used.
213 * @param aGc Graphics context to be used for drawing.
215 * @param aRect Rectangle to be drawn.
217 * @return ETrue if background was drawn with a bitmap, EFalse
220 IMPORT_C static TBool Background( MAknsSkinInstance* aInstance,
221 MAknsControlContext* aContext, CWindowGc& aGc, const TRect& aRect );
224 * Draws background with proper origin.
225 * Draws bacground to the specified rectangle. The origin is queried
226 * from the control position list (if given using
227 * AknsUtils::RegisterControlPosition). If not found, the origin is
228 * queried from the given control, which may result in a window server
231 * See @c DrawBackground for details on chained layouts.
235 * @param aInstance Pointer to skin instance as obtained from
236 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
239 * @param aContext Control context to obtain context specific
240 * information about background drawing. Must be specified, if
241 * aInstance is not @c NULL.
243 * @param aControl Control that knows the current window.
244 * Must be specified if parent absolute layout can be used,
245 * otherwise @c NULL may be given.
247 * @param aGc Graphics context to be used for drawing.
249 * @param aRect Rectangle to be drawn.
251 * @return ETrue if background was drawn with a bitmap, EFalse
252 * otherwise. Note that many scalable skins implicitly define
253 * background bitmaps for seemingly blank areas.
255 IMPORT_C static TBool Background( MAknsSkinInstance* aInstance,
256 MAknsControlContext* aContext, const CCoeControl* aControl,
257 CWindowGc& aGc, const TRect& aRect );
260 * Draws background with proper origin and drawing parameters.
261 * Draws bacground to the specified rectangle. The origin is queried
262 * from the control position list (if given using
263 * AknsUtils::RegisterControlPosition). If not found, the origin is
264 * queried from the given control, which may result in a window server
265 * flush. Drawing parameters may be used to control drawing.
267 * See @c DrawBackground for details on chained layouts.
271 * @param aInstance Pointer to skin instance as obtained from
272 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
275 * @param aContext Control context to obtain context specific
276 * information about background drawing. Must be specified, if
277 * aInstance is not @c NULL.
279 * @param aControl Control that knows the current window.
280 * Must be specified if parent absolute layout can be used,
281 * otherwise @c NULL may be given.
283 * @param aGc Graphics context to be used for drawing.
285 * @param aRect Rectangle to be drawn.
287 * @param aDrawParam Bitwise combination of drawing parameters.
288 * @c KAknsDrawParamDefault should be used if no special handling
291 * @return ETrue if background was drawn with a bitmap, EFalse
292 * otherwise. Note that many scalable skins implicitly define
293 * background bitmaps for seemingly blank areas.
295 IMPORT_C static TBool Background( MAknsSkinInstance* aInstance,
296 MAknsControlContext* aContext, const CCoeControl* aControl,
297 CWindowGc& aGc, const TRect& aRect, const TInt aDrawParam );
300 * Draws background to the given graphics context.
301 * The origin is queried from the control position list (if given using
302 * AknsUtils::RegisterControlPosition). If not found, the origin is
303 * queried from the given control, which may result in a window server
306 * If background contains multiple layers, they are drawn in the
307 * sequence specified by the context. If multiple contexts are chained
308 * (using @c SetParentContext), they are drawn in reverse order, i.e.
309 * the context given as parameter to this method call is drawn last.
311 * Drawing parameter KAknsDrawParamNoClearUnderImage is automatically
312 * assumed for all the chained contexts, except the deepest one.
316 * @param aInstance Pointer to skin instance as obtained from
317 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
320 * @param aContext Control context to obtain context specific
321 * information about background drawing. Must be specified, if
322 * aInstance is not @c NULL.
324 * @param aControl Control that knows the current window.
325 * Must be specified if parent absolute layout can be used,
326 * otherwise @c NULL may be given.
328 * @param aGc Graphics context to be used for drawing.
330 * @param aDstPos Destination position (top-left corner of the area
331 * to be drawn) in graphics context coordinate system.
333 * @param aControlRect Rectangle (in the control coordinate system)
336 * @param aDrawParam Bitwise combination of drawing parameters.
337 * @c KAknsDrawParamDefault should be used if no special handling
340 * @return ETrue if background was drawn with a bitmap, EFalse
341 * otherwise. Note that many scalable skins implicitly define
342 * background bitmaps for seemingly blank areas.
344 IMPORT_C static TBool DrawBackground( MAknsSkinInstance* aInstance,
345 MAknsControlContext* aContext, const CCoeControl* aControl,
346 CBitmapContext& aGc, const TPoint& aDstPos,
347 const TRect& aControlRect, const TInt aDrawParam );
350 * Draws background between rects.
351 * Draws bacground between specified rectangles. Origin is assumed
354 * See @c DrawBackground for details on chained layouts.
358 * @param aInstance Pointer to skin instance as obtained from
359 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
362 * @param aContext Control context to obtain context specific
363 * information about background drawing. If @c NULL and skin
364 * instance was given, default parameters are used.
366 * @param aGc Graphics context to be used for drawing.
368 * @param aOuterRect Outer rectangle.
370 * @param aInnerRect Inner rectangle.
372 * @return ETrue if background was drawn with a bitmap, EFalse
373 * otherwise. Note that many scalable skins implicitly define
374 * background bitmaps for seemingly blank areas.
376 IMPORT_C static TBool BackgroundBetweenRects(
377 MAknsSkinInstance* aInstance,
378 MAknsControlContext* aContext, CWindowGc& aGc,
379 const TRect& aOuterRect,const TRect& aInnerRect );
382 * Draws background between rects.
383 * Draws bacground between specified rectangles.
385 * See @c DrawBackground for details on chained layouts.
389 * @param aInstance Pointer to skin instance as obtained from
390 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
393 * @param aContext Control context to obtain context specific
394 * information about background drawing. Must be specified if
395 * aInstance is not @c NULL.
397 * @param aControl Control that knows the current window.
398 * Must be specified if parent absolute layout can be used,
399 * otherwise @c NULL may be given.
401 * @param aGc Graphics context to be used for drawing.
403 * @param aOuterRect Outer rectangle.
405 * @param aInnerRect Inner rectangle.
407 * @return ETrue if background was drawn with a bitmap, EFalse
408 * otherwise. Note that many scalable skins implicitly define
409 * background bitmaps for seemingly blank areas.
411 IMPORT_C static TBool BackgroundBetweenRects(
412 MAknsSkinInstance* aInstance,
413 MAknsControlContext* aContext, const CCoeControl* aControl,
415 const TRect& aOuterRect,const TRect& aInnerRect );
418 * Draws background between rects.
419 * Draws bacground between specified rectangles with drawing parameters.
423 * @param aInstance Pointer to skin instance as obtained from
424 * AknsUtils::SkinInstance(). If @c NULL rectangle is cleared
427 * @param aContext Control context to obtain context specific
428 * information about background drawing. Must be specified if
429 * aInstance is not @c NULL.
431 * @param aControl Control that knows the current window.
432 * Must be specified if parent absolute layout can be used,
433 * otherwise @c NULL may be given.
435 * @param aGc Graphics context to be used for drawing.
437 * @param aOuterRect Outer rectangle.
439 * @param aInnerRect Inner rectangle.
441 * @param aDrawParam Bitwise combination of drawing parameters.
442 * @c KAknsDrawParamDefault should be used if no special handling
445 * @return ETrue if background was drawn with a bitmap, EFalse
446 * otherwise. Note that many scalable skins implicitly define
447 * background bitmaps for seemingly blank areas.
449 IMPORT_C static TBool BackgroundBetweenRects(
450 MAknsSkinInstance* aInstance,
451 MAknsControlContext* aContext, const CCoeControl* aControl,
453 const TRect& aOuterRect, const TRect& aInnerRect,
454 const TInt aDrawParam );
457 * Determines whether background drawing would be done with
458 * a bitmap (deprecated).
460 * @param aInstance Pointer to skin instance. If @c NULL,
461 * method returns EFalse.
463 * @param aContext Control context, or @c NULL if no context
464 * is used. Note that absence of control context affects
467 * @return @c ETrue if background would be drawn with a bitmap,
468 * @c EFalse otherwise. If a scalable skin is currently active,
469 * the return value is undefined, and does not necessarily
470 * reflect the return value of the actual drawing operation.
472 * @deprecated This method is deprecated as of release 2.8.
473 * Use the return values of background drawing functions to
474 * determine whether the background was drawn with skinned
475 * content. The return value is always ETrue starting from
478 IMPORT_C static TBool HasBitmapBackground(
479 MAknsSkinInstance* aInstance,
480 MAknsControlContext* aContext );
483 * Draws a cached image (with its attributes specified in the skin)
484 * to the given rectangle.
486 * @param aInstance Pointer to the skin instance. If @c NULL,
487 * the method returns immediately.
489 * @param aGc Graphics context to be used for drawing.
491 * @param aRect Rectangle specifying the pane used for drawing. The
492 * image is laid out within the rectangle.
494 * @param aID Item ID of the image to be drawn.
496 IMPORT_C static void DrawCachedImage( MAknsSkinInstance* aInstance,
497 CWindowGc& aGc, const TRect& aRect, const TAknsItemID& aID );
500 * Draws a cached image (with its attributes specified in the skin)
501 * to the given rectangle in an off-screen graphics context.
505 * @param aInstance Pointer to the skin instance. If @c NULL,
506 * the method returns immediately.
508 * @param aGc Bitmapped graphics context to be used for drawing.
510 * @param aRect Rectangle specifying the pane used for drawing. The
511 * image is laid out within the rectangle.
513 * @param aID Item ID of the image to be drawn.
515 IMPORT_C static void DrawCachedImage( MAknsSkinInstance* aInstance,
516 CFbsBitGc& aGc, const TRect& aRect, const TAknsItemID& aID );
519 * Draws a frame (with cached images) to the specified area.
521 * @param aInstance Pointer to the skin instance. If @c NULL, the
522 * method returns EFalse.
524 * @param aGc Graphics context to be used for drawing.
526 * @param aOuterRect Outer rectangle of the frame. Frame elements
527 * will be drawn within this rectangle.
529 * @param aInnerRect Inner rectangle of the frame. Frame center
530 * will be drawn within this rectangle.
532 * @param aFrameID Item ID of the entire frame.
534 * @param aCenterID Item ID of the center part of the frame. If
535 * @c KAknsIIDNone, no center will be drawn. If @c KAknsIIDDefault,
536 * the default value from the frame itself will be used. Other values,
537 * the item to be used for the center part. If the frame is
538 * specified as 1 part graphics in the skin instead of 9 part
539 * graphics, this parameter has no effect.
541 * @return EFalse, if the frame was not drawn at all. ETrue, if the
542 * frame was (at least partially) drawn.
544 IMPORT_C static TBool DrawFrame( MAknsSkinInstance* aInstance,
545 CWindowGc& aGc, const TRect& aOuterRect, const TRect& aInnerRect,
546 const TAknsItemID& aFrameID, const TAknsItemID& aCenterID );
549 * Prepares the frame graphics for drawing. This function should be
550 * called when the frame sizes are known and in places where Flushing
551 * the Window server buffer will not cause flicker. For example, a
552 * good place to call PrepareFrame() would be controls SizeChanged
553 * function. Altough its not mandatory to call PrepareFrame()
554 * before DrawFrame(), it's highly recommended in order to avoid
555 * unnecessary flushes in the middle of the actual drawing routine.
557 * Note that the rect parameters must be exactly the same for
558 * PrepareFrame and subsequent DrawFrame calls. Otherwise the
559 * DrawFrame functions will cause a flush, which leads
564 * @param aInstance Pointer to the skin instance. If @c NULL, the
565 * method returns EFalse.
567 * @param aOuterRect Outer rectangle of the frame. Frame elements
568 * are scaled to this size.
570 * @param aInnerRect Inner rectangle of the frame. Frame center
571 * is scaled to this size
573 * @param aFrameID Item ID of the entire frame.
575 * @param aCenterID Item ID of the center part of the frame. If
576 * @c KAknsIIDNone, no center part will be prepared.
577 * If @c KAknsIIDDefault, the default value from the frame
578 * itself will be used. Other values, the item to be used
579 * for the center part. If the frame is specified as 1 part
580 * graphics in the skin instead of 9 part graphics, this
581 * parameter has no effect.
583 * @return EFalse, if were nothing to prepare. ETrue, if the
584 * frame was (at least partially) prepared.
586 IMPORT_C static TBool PrepareFrame( MAknsSkinInstance* aInstance,
587 const TRect& aOuterRect, const TRect& aInnerRect,
588 const TAknsItemID& aFrameID, const TAknsItemID& aCenterID);
591 * Draws a frame (with cached images) to the specified area
592 * in an off-screen graphics context.
596 * @param aInstance Pointer to the skin instance. If @c NULL, the
597 * method returns EFalse.
599 * @param aGc Bitmapped graphics context to be used for drawing.
601 * @param aOuterRect Outer rectangle of the frame. Frame elements
602 * will be drawn within this rectangle.
604 * @param aInnerRect Inner rectangle of the frame. Frame center
605 * will be drawn within this rectangle.
607 * @param aFrameID Item ID of the entire frame.
609 * @param aCenterID Item ID of the center part of the frame. If
610 * @c KAknsIIDNone, no center will be drawn. If @c KAknsIIDDefault,
611 * the default value from the frame itself will be used. Other values,
612 * the item to be used for the center part. If unsure, specify
613 * @c KAknsIIDDefault. If the frame is specified as 1 part
614 * graphics in the skin instead of 9 part graphics, this
615 * parameter has no effect.
617 * @param aDrawParam Bitwise combination of drawing parameters.
618 * @c KAknsDrawParamDefault should be used if no special handling
621 * @return EFalse, if the frame was not drawn at all. ETrue, if the
622 * frame was (at least partially) drawn.
624 IMPORT_C static TBool DrawFrame( MAknsSkinInstance* aInstance,
625 CFbsBitGc& aGc, const TRect& aOuterRect, const TRect& aInnerRect,
626 const TAknsItemID& aFrameID, const TAknsItemID& aCenterID,
627 const TInt aDrawParam );
630 * Draws a frame (with cached images) to the specified area
631 * in an off-screen graphics context.
635 * @param aInstance Pointer to the skin instance. If @c NULL, the
636 * method returns EFalse.
638 * @param aGc Bitmapped graphics context to be used for drawing.
640 * @param aOuterRect Outer rectangle of the frame. Frame elements
641 * will be drawn within this rectangle.
643 * @param aInnerRect Inner rectangle of the frame. Frame center
644 * will be drawn within this rectangle.
646 * @param aFrameID Item ID of the entire frame.
648 * @param aCenterID Item ID of the center part of the frame. If
649 * @c KAknsIIDNone, no center will be drawn. If @c KAknsIIDDefault,
650 * the default value from the frame itself will be used. Other values,
651 * the item to be used for the center part. If unsure, specifi
652 * @c KAknsIIDDefault. If the frame is specified as 1 part
653 * graphics in the skin instead of 9 part graphics, this
654 * parameter has no effect.
656 * @return EFalse, if the frame was not drawn at all. ETrue, if the
657 * frame was (at least partially) drawn.
659 IMPORT_C static TBool DrawFrame( MAknsSkinInstance* aInstance,
660 CFbsBitGc& aGc, const TRect& aOuterRect, const TRect& aInnerRect,
661 const TAknsItemID& aFrameID, const TAknsItemID& aCenterID );
664 * Draws the specified part of the frame (with a cached image) to the
665 * specified rectangle.
667 * @par Compatibility note:
668 * Prior to Series 60 release 2.8, the entire outer rectangle could
669 * be given as the rectangle of a corner part. Due to scalable UI
670 * compatibility, this is no longer supported in release 2.8, and thus
671 * the exact corner rectangle is required. This funtion may not
672 * function correctly if the skin specifies the frame as 1 part
675 * @param aInstance Pointer to the skin instance. If @c NULL, the
676 * method returns @c EFalse.
678 * @param aGc Graphics context to be used for drawing.
680 * @param aRect Rectangle for drawing. This must be the rectangle
681 * of the specific part of the drawn that will be drawn, e.g.
682 * top-left corner rectangle if the top-left corner is being drawn.
684 * @param aFrameID Item ID of the entire frame.
686 * @param aFrameElement Element (index) of the frame element to
689 * @return ETrue, if the element was drawn. EFalse otherwise.
691 IMPORT_C static TBool DrawFramePart( MAknsSkinInstance* aInstance,
692 CWindowGc& aGc, const TRect& aRect, const TAknsItemID& aFrameID,
693 const TAknsFrameElementIndex aFrameElement );
696 * Returns a boolean value indicating whether list separator lines
699 * This method checks:
700 * - The value of @c KAknsIIDPropertyListSeparatorLines property.
701 * - The presence of (non-scalable) column bitmaps.
702 * If found, @c EFalse is returned.
703 * - The presence of generic list background (non-scalable).
704 * If found, @c EFalse is returned.
706 * Note that the exact internal implementation of the checks is
711 * @param aInstance Pointer to the skin instance. If @c NULL,
712 * the method returns @c ETrue.
714 * @return @c ETrue, if list separator lines should drawn.
715 * @c EFalse, if list separator lines should not be drawn
716 * and, consequently, list column and slice bitmaps (if any) from the
717 * skin content should be drawn.
719 IMPORT_C static TBool IsListSeperatorLines(
720 MAknsSkinInstance* aInstance );
723 * Returns an enum value indicating the way notes and queries appear
724 * to the screen (sliding animation)
728 * @param aInstance Pointer to the skin instance. If @c NULL,
729 * the method returns @c ESlidingDisabled.
731 * @return @c Sliding mode from enumeration TSlidingMode
733 IMPORT_C static TSlidingMode SlidingMode(
734 MAknsSkinInstance* aInstance );
736 private: // Prohibited constructors and destructor
738 // Construction prohibited (static class)
740 // Destruction prohibited (static class)
744 #endif // AKNSDRAWUTILS_H