1 /*

     2 * Copyright (c) 2008 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:  API for handling alf graphic resources

    15 *

    16 */

    17 

    18 

    19 #ifndef ALF_RESOURCEPOOL_H

    20 #define ALF_RESOURCEPOOL_H

    21 

    22 #include <osn/osndefines.h>

    23 #include <osn/ustring.h>

    24 

    25 #include <alf/alftexture.h>

    26 class TAlfImage;

    27 class CAlfTextureManager;

    28 struct TAlfXYMetric;

    29 

    30 namespace Alf 

    31 {

    32 

    33 #define KResourcePoolThemeDefinitionPrefixS60 "s60"

    34 

    35 using namespace osncore;

    36 

    37 class ResourcePoolImpl;

    38  

    39 /**

    40  *  Resoure pool is responsible of controlling commonly used image resources

    41  *  in an application. The resources will be indentified by tags, which are not

    42  *  case sensitive. 

    43  *

    44  *  @code

    45  *   // create image resources

    46  *   resourcePool->createLogicalImageResource( "qgn_indi_find_glass" );

    47  *   resourcePool->setInitialSize( "qgn_indi_find_glass", XYMetric( 64, 64 ) );

    48  *   resourcePool->setAspectRatio( "qgn_indi_find_glass", ResourcePool::aspectRatioPreserved );

    49  *

    50  *   resourcePool->createImageResource(

    51  *       "my_face",

    52  *       pic0001.jpg );

    53  *

    54  *   // utilize the resource

    55  *   imageVisual->setImage( 

    56  *       resourcePool->getImageResource( "qgn_indi_find_glass" ) );

    57  *

    58  *   sharpImageVisual->setImage( 

    59  *       resourcePool->getImageResource( "my_face" ),

    60  *       XYMetric( 256, 256 ) );

    61  *

    62  *   // when the resource in not used anymore, the resource can be deleted

    63  *   resourcePool->deleteImageResource( "qgn_indi_find_glass" );

    64  *   resourcePool->deleteImageResource( "my_face" );

    65  *   

    66  *  @endcode

    67  *

    68  *  @lib alfresourcepool.lib

    69  *  @since S60 v5.0.1

    70  */

    71 class ResourcePool

    72     {

    73 public:

    74 

    75     // Aspect ratio of the image resource

    76     // @see setAspectRatio

    77     enum AspectRatio

    78         {

    79         /*

    80         * Scales the icon to the maximum size that fits in the given size,

    81         * whilst preserving the aspect ratio of the icon. The sizes of the resulting

    82         * bitmaps are exactly of the given size. If the aspect ratio of

    83         * the given size differs from the aspect ratio of the icon,

    84         * the resulting bitmaps will contain an unused area.

    85         */

    86         aspectRatioPreserved = 0,

    87 

    88         /*

    89         * Scales the icon to the maximum size that fits in the given size,

    90         * whilst preserving the aspect ratio of the icon. The resulting bitmaps

    91         * are resized so that any unused portion of the given size is not

    92         * present in them.

    93         *

    94         * This mode should be used when only the height or the width of the icon

    95         * is known and the other should be based on the aspect ratio of the icon.

    96         * The unknown dimension should be defined high enough so

    97         * that it does not limit the scaling based on the aspect ratio of the icon.

    98         */

    99         aspectRatioPreservedAndUnusedSpaceRemoved = 1,

   100 

   101         /*

   102         * Scales the icon exactly to the given size. Does not preserve the aspect

   103         * ratio of the icon.

   104         */

   105         aspectRatioNotPreserved = 2,

   106             

   107         /*

   108         * Scales the icon to the minimum size that covers the given size,

   109         * whilst preserving the aspect ratio of the icon. The sizes of the resulting

   110         * bitmaps are exactly of the given size. If the aspect ratio of

   111         * the given size differs from the aspect ratio of the icon, some parts of the 

   112         * icon will be sliced from the resulting bitmaps.

   113         */

   114         aspectRatioPreservedSlice = 3

   115         };

   116     

   117 public:

   118 

   119     /** 

   120      * Constructs a resource pool

   121      *

   122      * @param aTextureManager Used texture manager.

   123      * @param aParentPool Chained parent pool (optional) - not supported currently

   124      */

   125     OSN_IMPORT ResourcePool( 

   126         CAlfTextureManager& aTextureManager,

   127         ResourcePool* aParentPool = NULL);

   128     

   129     /**

   130      * Destructor 

   131      */

   132     OSN_IMPORT ~ResourcePool();

   133     

   134 public: 

   135     

   136     /**

   137      * Creates an image resource based on a logical name. The name will

   138      * be also used as the image resource tag because the logical name

   139      * is unique in the system.

   140      *

   141      * The logical name should be format "qgn_xxx_xxx" i.e. as stated

   142      * in the S60 reference icons document.

   143      *

   144      * @note The KAknsIIDQgnXxxXxx format works for a while but it will be 

   145      *       deprecated -> use the qgn_xxx_xxx format.

   146      *

   147      * @param aTag Resource tag. NULL terminated 8-bit string

   148      *

   149      * @exception invalid_argument if the tag cannot be matched with any 

   150      *                              logical name

   151      */

   152     OSN_IMPORT void createLogicalImageResource( const Utf8* aTag );

   153     

   154     /**

   155      * Creates an image resource based on a theme definition. This definition

   156      * may concists of several different theme systems.

   157      * 

   158      * Currently supported formats:

   159      * #1 S60 Skin; 

   160      *    s60;mifFilePath;mifImageIndex;mifMaskIndex;majorID;minorId

   161      *

   162      *    s60:          literal "s60", which specifies that the following

   163      *                  item definition is based on the S60 Skin system

   164      *    mifFilePath:  literal into the multibitmap file (mif/mbm). Can be empty. 

   165      *    mifImageIndex:unsigned integer which is the index to the mifFilePath. Only used if mifFilePath is given.

   166      *    mifMaskIndex: unsigned integer which is the mask index to the mifFilePath. Only used if mifFilePath is given.

   167      *    majorID:      unsigned integer or hexadecimal starting with 0x of the Major skin ID. Can be empty.

   168      *    minorId:      unsigned integer or hexadecimal starting with 0x of the Minor skin ID. Only used if majorID is given.

   169      *    

   170      *    examples:     "s60;;;;268457670;76" // 0x100056c6;0x4c -> KAknsIIDQgnIndiFindGlass

   171      *                  "s60;c:\myFile.mif;1;2;;"

   172      *                  "s60;myMbmFile.mbm;435;;2342345;234" // If skin ID not found, use mbm file with index 435 (no mask)

   173      *

   174      * @param aTag Resource tag.

   175      * @param aThemeDefinition Definition of the theme element.

   176      *

   177      * @exception invalid_argument theme definition is not supported.

   178      */

   179     OSN_IMPORT void createThemeImageResource( 

   180         const Utf8* aTag,

   181         const UString& aThemeDefinition );

   182     

   183     /**

   184      * Creates an image resource based on a file name.

   185      * The aFileName can be a full path with the drive letter or it

   186      * can be relative path to the texture manager defaul path

   187      *

   188      * @param aTag Resource tag.

   189      * @param aFileName File name.

   190      * @param aFlag How to convert the bitmap to texture

   191      *               default all fileimages will be treated as nonanimated

   192      * @see TextureManager::setImagePath()

   193      */

   194     OSN_IMPORT void createFileImageResource( 

   195         const Utf8* aTag,

   196         const UString& aFileName ,TAlfTextureFlags aFlag = EAlfTextureFlagLoadAnimAsImage );

   197     

   198     /**

   199      * Deletes image resource

   200      *

   201      * @param aTag Resource tag.

   202      */    

   203     OSN_IMPORT void deleteImageResource( const Utf8* aTag );

   204     

   205     /**

   206      * Checks if the given resource identifier exists.

   207      *

   208      * @param aTag Resource tag.

   209      *

   210      * @return 'true' if the indentified resource exists.

   211      */

   212     OSN_IMPORT bool hasImageResource( const Utf8* aTag ) const;

   213     

   214     /**

   215      * Sets initial/default loading size for the image resource. The given size

   216      * is only a hint and the resource pool may used it or ignore it. Without the 

   217      * initial size hint, the image will be rasterized to size determined by the 

   218      * resource pool. The initial size hint can be overridden with the appropriate

   219      * getImageResource() function.

   220      *

   221      * @param aTag Resource tag.

   222      * @param aInitialSizeHint Initial/default size hint (only Pixel and RelativeToDisplay supported)

   223      */    

   224     OSN_IMPORT void setInitialSize( 

   225         const Utf8* aTag, 

   226         const TAlfXYMetric& aInitialSizeHint );

   227         

   228     /**

   229      * Sets aspect ratio mode. This affects to the aspect ratio of the loaded image

   230      * resource. The new setting will take place when the image resource is loaded.

   231      *

   232      * @note Currently only SVG icons are supported. For file image loading, the aspect ratio

   233      *       is preserved.

   234      *

   235      * @note The blitting of the image resource can still scale and change the aspect ratio

   236      *       of the drawn image. @see ImageVisual::setScaleMode

   237      *

   238      * @param aTag Resource tag.

   239      * @param aAspectRatio Used aspect ratio.

   240      */    

   241     OSN_IMPORT void setAspectRatio( 

   242         const Utf8* aTag, 

   243         AspectRatio aAspectRatio );

   244 

   245     /**

   246      * Finds a image resource with the given tag. The initial size or system

   247      * default size is used.

   248      *

   249      * If the given resource is not found, the Image::hasTexture() returns false.

   250      *

   251      * @param aTag Resource tag.

   252      * 

   253      * @return Image which can be passed to any visual/brush.

   254      *

   255      * @exception invalid_argument if the resource is found but cannot be instantiated

   256      */

   257     OSN_IMPORT TAlfImage getImageResource( const Utf8* aTag );

   258 

   259     /**

   260      * Finds a image resouce with the given tag. The size hint may be

   261      * used to find/re-rasterize the image resource. 

   262      * 

   263      * If the given resource is not found, the Image::hasTexture() returns false.

   264      *

   265      * @param aTag Resource tag.

   266      * @param aSizeHint Rasteration size hint (only Pixel and RelativeToDisplay supported)

   267      * 

   268      * @return Image which can be passed to any visual/brush.

   269      *

   270      * @exception invalid_argument if the resource is found but cannot be instantiated

   271      */

   272     OSN_IMPORT TAlfImage getImageResource( 

   273         const Utf8* aTag, 

   274         const TAlfXYMetric& aSizeHint );

   275     

   276 private:

   277    

   278     auto_ptr<ResourcePoolImpl> mResourcePoolImpl;

   279     };

   280 

   281 } // namespace Alf

   282 

   283 #endif // ALF_RESOURCEPOOL_H