1 /*

     2 * Copyright (c)  Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Image visual displays an image.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_ALFIMAGEVISUAL_H

    21 #define C_ALFIMAGEVISUAL_H

    22 

    23 #include <alf/alfvisual.h> 

    24 #include <alf/alfgc.h> 

    25 

    26 class TAlfImage;

    27 class TRgb;

    28 struct TAlfMetric;

    29 struct TAlfXYMetric;

    30 

    31 /**

    32  * Image visual displays an image.

    33  *

    34  * An image visual can be used to display portions of CAlfTextures on the UI.

    35  * Crossfading between two images in a single image visual is possible.

    36  * The secondaryAlpha property controls the blending between the primary and secondary images 

    37  * of the visual. The default value is 0.0, which results in only the primary image being drawn. 

    38  * The secondary image is ignored when doing scaling calculations.

    39  * 

    40  * Usage:

    41  * @code

    42  * //Create image visual and set image

    43  * //It will set primary image for imagevisual

    44  * CAlfImageVisual* imagevisual =  CAlfImageVisual::AddNewL( control );

    45  * imagevisual->SetImage( iImage );

    46  * 

    47  * 

    48  * //Set secondary image and alpha value for crossfading

    49  * imagevisual->SetSecondaryImage( iImage2 );

    50  * imagevisual->SetSecondaryAlpha( 0.5 );

    51  * 

    52  * @endcode

    53  * @see TAlfImage

    54  * @see CAlfTexture

    55  * 

    56  * @lib alfclient.lib

    57  * @since S60 v3.2

    58  */

    59 class CAlfImageVisual : public CAlfVisual

    60     {

    61 

    62 public:

    63 

    64     /** @beginAPI */

    65 

    66     /** Image scaling modes. */

    67     enum TScaleMode

    68         {

    69         /** Image is not scaled. It will be drawn at a 1:1 mapping between its texture and the screen pixels.*/

    70         EScaleNormal,

    71     

    72         /** Image is uniformly scaled to fit the width of the visual's area. The aspect

    73             ratio of the image is preserved. */

    74         EScaleFitWidth,

    75         

    76         /** Image is uniformly scaled to fit the height of the visual's area. The aspect

    77             ratio of the image is preserved. */

    78         EScaleFitHeight,

    79     

    80         /** Image is uniformly scaled to fit the visual's area so that the entire area

    81             is covered. The aspect ratio of the image is preserved. */

    82         EScaleCover,            

    83         

    84         /** Image is uniformly scaled to fit the visual's area. The aspect ratio of the 

    85             image is not preserved. This is the default scale mode. It allows

    86             full control of the appearance of the image by adjusting the 

    87             visual's size. */

    88         EScaleFit,

    89         

    90         /** Image is uniformly scaled to fit inside the visual's area. The aspect ratio 

    91             of the image is preserved. */

    92         EScaleFitInside

    93         };

    94     

    95     /** Color modes. */

    96     enum TColorMode

    97         {

    98         /** Default color mode. */

    99         EColorModulate,

   100         

   101         /** A dimmed color mode will apply fogging to this visual. */

   102         EColorDimmed

   103         };

   104 

   105     /** @endAPI */        

   106         

   107     /**

   108      * Constructor.

   109      */

   110     IMPORT_C CAlfImageVisual();

   111 

   112     /**

   113      * Second-phase constructor, from CAlfVisual 

   114      */

   115     IMPORT_C void ConstructL(CAlfControl& aOwner);

   116 

   117     /**

   118      * Destructor

   119      */

   120     IMPORT_C virtual ~CAlfImageVisual();

   121 

   122 	/** @beginAPI */

   123     

   124     /**

   125      * Constructs and appends a new image visual to the owner control.

   126      *

   127      * @param aOwnerControl  Control that will own the new visual.

   128      *

   129      * @return  The new visual.

   130      */

   131     IMPORT_C static CAlfImageVisual* AddNewL(CAlfControl& aOwnerControl,

   132                                             CAlfLayout* aParentLayout = 0);

   133 

   134 

   135     /**

   136      * Sets the scaling mode for the bitmap.

   137      * An unscaled image will be drawn at a 1:1 mapping between its

   138      * texture and the screen. A scaled image will be resized to fit the

   139      * visual's size exactly.

   140      * If unset, the default is EScaleFit.

   141      * 

   142      * @param aScaleMode The scaling mode of this image visual.

   143      */

   144     IMPORT_C void SetScaleMode(CAlfImageVisual::TScaleMode aScaleMode);

   145     

   146     /**

   147      * Gets the scaling mode of the Image Visual texture.

   148      * Returns the Scalemode set to Image Visual, using SetScaleMode()

   149      * Default is EScaleFit.

   150      * 

   151      * @return Scaling mode of the image visual.

   152      * @see SetScaleMode()

   153      */

   154     IMPORT_C CAlfImageVisual::TScaleMode ScaleMode();

   155        

   156     /**

   157      * Sets the image displayed by the image visual. If no image

   158      * has been set for the visual, the visual does not draw anything.

   159      *

   160      * @note You may call SetImage also with images(/textures) that have not

   161      * been loaded (yet). The toolkit has been designed so that SetImage()

   162      * can be called before the texture has been finished loading. In the

   163      * meantime, a placeholder could be used. In other words, the CAlfTexture

   164      * that the TAlfImage refers to does need to exist but it doesn't have to

   165      * be loaded yet.

   166      *

   167      * @note Redrawing of the visual happens automatically after SetImage() has

   168      * been called.

   169      * @note Redrawing also happens automatically when a texture has been fully

   170      * loaded by the texture manager. The manager notifies the environment,

   171      * which issues a full display redraw.

   172      *

   173      * @param aImage Primary image to be visualized.

   174      */

   175     IMPORT_C void SetImage(const TAlfImage& aImage); 

   176 

   177     /**

   178      * Sets the secondary image displayed by the image visual.

   179      *

   180      * The reason there are two images is to make crossfading simpler from

   181      * the application's point of view. The blending ratio between the images

   182      * is controlled with the timed value iSecondaryAlpha of CAlfImageVisual.

   183      *

   184      * If iSecondaryAlpha is zero (the default), the secondary image will not be

   185      * drawn. When iSecondaryAlpha increases, the secondary image becomes

   186      * gradually visible as its opacity increases.

   187      *

   188      * When crossfading is not needed, SetSecondaryImage() and iSecondaryAlpha

   189      * can be ignored.

   190      *

   191      * @see SetImage()

   192      * @see SetSecondaryAlpha()

   193      */

   194     IMPORT_C void SetSecondaryImage(const TAlfImage& aImage);

   195 

   196     /** 

   197      * Sets alpha for the secondary image. If one, the primary image is not

   198      * visible at all. 

   199      * @param aAlpha Alpha value for the image  

   200      */

   201     IMPORT_C void SetSecondaryAlpha(const TAlfTimedValue& aAlpha);

   202 

   203     /** 

   204      * Gets alpha for the secondary image. 

   205      * @return Alpha value for the image  

   206      */

   207     IMPORT_C TAlfTimedValue SecondaryAlpha();

   208 

   209     /**

   210      * Returns the image of the visual.

   211      */

   212     IMPORT_C const TAlfImage& Image() const;

   213 

   214     /**

   215      * Returns the secondary image of the visual.

   216      */

   217     IMPORT_C const TAlfImage& SecondaryImage() const;

   218 

   219     /**

   220      * Sets the color of the image. Defaults to white.

   221      */

   222     IMPORT_C void SetColor(const TRgb& aColor);

   223 

   224     /**

   225      * Sets the color mode of the image. Defaults to modulate.

   226      *

   227      * @param aColorMode  Color mode.

   228      * @param aParam      Parameter for the mode. With blend, specifies the

   229      *                    amount of color to blend (0...1). 1.0 will cause

   230      *                    the image to be fully blended to the visual's color.

   231      */

   232     IMPORT_C void SetColorMode(CAlfImageVisual::TColorMode aColorMode, TReal32 aParam = 0.0) __SOFTFP;

   233 

   234     /**

   235      * Sets the stretch widths of the image. Set both to zero to disable stretching.

   236      * A stretched image will be scaled over the whole width or height of the visual,

   237      * except for a band specified by the parameters, which will not be scaled (1:1 pixel mapping).

   238      * For doing uniform scaling of an image, use the SetScaleMode API instead.

   239      *

   240      * @deprecated  Deprecated as an unneeded and broken functionality.

   241      *

   242      * @param aTop     Top width in pixels.

   243      * @param aBottom  Bottom width in pixels.

   244      * @see SetStretchMode.

   245      * @see CHuiGc::DrawStretchImage

   246      */

   247     IMPORT_C void SetStretch(TInt aTop, TInt aBottom);

   248 	

   249     /**

   250      * Sets the stretch mode of the image.

   251      *

   252      * @see CHuiGc::DrawStretchImage.

   253      * @see Setstretch.

   254      * @param aStretchMode  Horizontal or vertical.

   255      */

   256     IMPORT_C void SetStretchMode(CAlfGc::TStretchMode aStretchMode);

   257 

   258     /**

   259      * @deprecated Use CAlfDropShadow

   260      * 

   261      * Sets the drop shadow distance.

   262      *

   263      * @deprecated  Use metric unit version instead.

   264      *

   265      * @param aShadowDistance  Pixels.

   266      */

   267     IMPORT_C void SetDropShadow(TInt aShadowDistance);

   268 

   269     /**

   270      * @deprecated Use CAlfDropShadow

   271      *

   272      * Sets the drop shadow distance.

   273      *

   274      * @param aShadowDistance  Set shadow distance in metric units. Both X and Y will use this value.

   275      */

   276     IMPORT_C void SetDropShadow(const TAlfMetric& aShadowDistance);

   277 

   278     /**

   279      * @deprecated Use CAlfDropShadow

   280      *

   281      * Sets the drop shadow distance.

   282      *

   283      * @param aShadowDistance  Set shadow distance in metric units.

   284      */

   285     IMPORT_C void SetDropShadow(const TAlfXYMetric& aShadowDistance);

   286 

   287     /** 

   288      * Sets angle for turning the image around its center point. 

   289      * @param Turn angle

   290      */

   291     IMPORT_C void SetTurnAngle(const TAlfTimedValue& aAngle);

   292 

   293     /** 

   294      * Gets angle for turning the image around its center point. 

   295      * @return Turn angle

   296      */

   297     IMPORT_C TAlfTimedValue TurnAngle();

   298 

   299     /** 

   300      * Sets uniform scale factor for the image. 

   301      * @param aScale Scale factor

   302      */

   303     IMPORT_C void SetScale(const TAlfTimedValue& aScale);

   304 

   305     /** 

   306      * Gets uniform scale factor for the image. 

   307      * @return aScale Scale factor

   308      */

   309     IMPORT_C TAlfTimedValue Scale();

   310 

   311     /** 

   312      * Sets relative offset for scaled images.

   313      * @param aOffset relative offset

   314      */

   315     IMPORT_C void SetOffset(const TAlfTimedPoint& aOffset);

   316 

   317     /** 

   318      * Gets relative offset for scaled images.

   319      * @return relative offset

   320      */

   321     IMPORT_C TAlfTimedPoint Offset();

   322 

   323     /**

   324      * From CAlfVisual

   325      * @see CAlfVisual

   326      */

   327     IMPORT_C void RemoveAndDestroyAllD();

   328     IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);

   329     IMPORT_C CAlfVisual* FindTag(const TDesC8& aTag);

   330 

   331     /** @endAPI */

   332 

   333 protected:

   334     /**

   335      * From CAlfVisual

   336      * @see CAlfVisual

   337      */

   338     IMPORT_C void DoRemoveAndDestroyAllD();

   339     IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   340 

   341 

   342 private:

   343 

   344 	/** Private data */

   345     struct TImageVisualPrivateData;    

   346     TImageVisualPrivateData* iImageVisualData;

   347     };

   348 

   349 

   350 #endif // C_ALFIMAGEVISUAL_H