1 /*

     2 * Copyright (c) 2002-2004 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:  ?Description

    15 *

    16 */

    17 

    18 

    19 #ifndef AKNSITEMDEF_H

    20 #define AKNSITEMDEF_H

    21 

    22 //  INCLUDES

    23 #include <AknsItemID.h>

    24 #include <gdi.h>

    25 

    26 // FORWARD DECLARATIONS

    27 struct TAknsImageAttributeData;

    28 

    29 // CLASS DECLARATIONS

    30 

    31 /**

    32 * Base class for item definitions.

    33 * Item definition maps item ID specified as TAknsItemID to a specific resource

    34 * (such as bitmap filename and index). Content of the definition varies 

    35 * depending of the type of the resource. 

    36 *

    37 * CAknsItemDef does not itself have any dynamically allocated members.

    38 * Therefore the members of its friend classes can instantiate CAknsItemDef

    39 * into stack (e.g. to perform binary search with LineraOrder without heap 

    40 * allocation) using CAknsItemDef::CAknsItemDef(const TAknsItemID aID) 

    41 * constructor. Derived classes, however, require two-phased construction and 

    42 * proper destruction.

    43 *

    44 * This is a public class with exported functions.

    45 * The class is not intended for derivation outside the library.

    46 *

    47 * @lib AknSkinSrv.lib

    48 *

    49 * @since 2.0

    50 */

    51 class CAknsItemDef : public CBase

    52     {    

    53 

    54     public: // Constructors and destructors        

    55 

    56         /**

    57         * Two-phased constructor.

    58         * Constructs item definition object with specified ID, item type

    59         * ::EAknsITUnknown and localization type ::EAknsIDLTDefault.

    60         *

    61         * @param aID Item ID of the newly created item definition.

    62         *

    63         * @return Newly constructed CAknsItemDef object.

    64         *

    65         * @par Exceptions:

    66         *   If allocation fails, function leaves with a system-wide error code.

    67         */

    68         IMPORT_C static CAknsItemDef* NewL( const TAknsItemID& aID );

    69         

    70         /**

    71         * Destructor.

    72         * Base-class destructor does nothing. It exists only to enable 

    73         * destruction of derived objects using pointer to base class object.

    74         */

    75         IMPORT_C virtual ~CAknsItemDef();

    76 

    77     public: // New functions

    78         

    79         /**

    80         * Returns the item type of this item definition.

    81         * This method can be used to provide run-time type information.

    82         * Corresponding classes are listed in definition of ::TAknsItemType.

    83         *

    84         * @since 2.0

    85         *

    86         * @return Type of the item definition as TAknsItemType.

    87         */

    88         IMPORT_C TAknsItemType Type() const;

    89 

    90         /**

    91         * Returns the item ID of this item definition.

    92         *

    93         * @since 2.0

    94         *

    95         * @return Item ID of the item definition as TAknsItemID.

    96         */

    97         IMPORT_C TAknsItemID ID() const;

    98 

    99         /**

   100         * Determines the order of two CAknsItemDef objects.

   101         * Order is determined based on the item ID of the object, as described

   102         * in TAknsItemID::LinearOrder().

   103         *

   104         * @since 2.0

   105         *

   106         * @param aFirst First object to be compared.

   107         *

   108         * @param aSecond Second object to be compared.

   109         *

   110         * @return 0 if the two objects are equal, negative value if the first 

   111         *   object is less than the second and positive value if the first 

   112         *   object is greater than the second.

   113         */

   114         IMPORT_C static TInt LinearOrder( const CAknsItemDef& aFirst, 

   115             const CAknsItemDef& aSecond );

   116 

   117     private: // Reserved exports

   118 

   119         /**

   120         * Reserved for future use.

   121         *

   122         * @since 2.0        

   123         */

   124         IMPORT_C void Reserved1();

   125 

   126         /**

   127         * Reserved for future use.

   128         *

   129         * @since 2.0        

   130         */

   131         IMPORT_C void Reserved2();

   132             

   133     protected: // C++ protected constructor for derived classes

   134                 

   135         /**

   136         * C++ constructor for derived classes.

   137         * Constructs item definition object with given item type and ID,

   138         * and localization type ::EAknsIDLTDefault.

   139         *

   140         * @param aType Item type of the new object.

   141         *

   142         * @param aID Item ID of the new object.

   143         *

   144         * @internal

   145         */

   146         CAknsItemDef( const TAknsItemType aType, const TAknsItemID& aID );

   147 

   148     private: // C++ private constructor for friend classes

   149 

   150         /**

   151         * C++ constructor for internal use.

   152         * Constructs item definition object with specified ID and item type

   153         * ::EAknsITUnknown, and localization type ::EAknsIDLTDefault.

   154         *

   155         * @param aID Item ID of the new item definition.

   156         *

   157         * @internal

   158         */

   159         IMPORT_C CAknsItemDef( const TAknsItemID& aID );

   160     

   161     protected:  // Data

   162 

   163         TAknsItemType iType;            //!< Item type.

   164         TAknsItemID iID;                //!< Item ID.

   165         TInt iSpare1;                   //!< Reserved for future use.

   166         TInt iSpare2;                   //!< Reserved for future use.

   167 

   168     private:    // Friend classes

   169         friend class CAknsAppSkinInstance;

   170 

   171     };

   172 

   173 /**

   174 * Image item definition.

   175 * Image item definition consists of (in addition to base class data) 

   176 * image attributes and their values. Item type for image item definitions

   177 * is ::EAknsITImage

   178 *

   179 * This is a public class with exported functions.

   180 * The class is not intended for derivation outside the library.

   181 *

   182 * @lib AknSkinSrv.lib

   183 *

   184 * @since 2.0

   185 */

   186 NONSHARABLE_CLASS(CAknsImageItemDef) : public CAknsItemDef

   187     {

   188     public:  // Constructors and destructor        

   189 

   190         /**

   191         * Two-phased constructor.

   192         * Constructs a new image item definition object. 

   193         *

   194         * @param aID Item ID of the new object.

   195         *        

   196         * @return Newly constructed CAknsImageItemDef object.

   197         *

   198         * @par Exceptions:

   199         *   If allocation fails, function leaves with a system-wide error 

   200         *   code.

   201         */

   202         IMPORT_C static CAknsImageItemDef* NewL( const TAknsItemID& aID );

   203         

   204         /**

   205         * Destructor.

   206         */

   207         virtual ~CAknsImageItemDef();

   208 

   209     public: // New functions

   210 

   211         /**

   212         * Sets the image attributes for this image definition.

   213         *

   214         * @since 2.0

   215         */

   216         IMPORT_C void SetAttributesL( const TAknsImageAttributeData& aAttributes );

   217 

   218         /**

   219         * Returns the image attributes for this image definition.

   220         *

   221         * @since 2.0

   222         */

   223         IMPORT_C const TAknsImageAttributeData* Attributes() const;

   224     

   225     protected: // C++ protected constructor

   226 

   227         /**

   228         * C++ constructor for internal use.

   229         * Constructs an image item definition object with given ID.

   230         *

   231         * @since 2.0

   232         *

   233         * @param aType Type of the definition object. While this is always

   234         *   ::EAknsITImage for CAknsImageItemDef objects, derived classes

   235         *   may specify other values.

   236         *

   237         * @param aID Item ID of the new item definition.

   238         *        

   239         * @internal

   240         */

   241         CAknsImageItemDef( const TAknsItemType aType, const TAknsItemID& aID );

   242     

   243     protected:  // Data

   244 

   245         // Image attributes

   246         TAknsImageAttributeData* iAttributeData;

   247         

   248     };

   249 

   250 /**

   251 * Bitmap item definition.

   252 * Bitmap item definition consists of (in addition to base class data) bitmap

   253 * filename and index in bitmap file. Item type for bitmap item definitions

   254 * is always ::EAknsITBitmap.

   255 *

   256 * This is a public class with exported functions.

   257 * The class is not intended for derivation outside the library.

   258 *

   259 * @lib AknSkinSrv.lib

   260 *

   261 * @since 2.0

   262 */

   263 NONSHARABLE_CLASS(CAknsBitmapItemDef) : public CAknsImageItemDef

   264     {

   265     public:  // Constructors and destructor        

   266 

   267         /**

   268         * Two-phased constructor, complete initialization.

   269         * Constructs a new bitmap item definition object. 

   270         *

   271         * @param aID Item ID of the new object.

   272         *

   273         * @param aFilename Filename of the bitmap. Internal descriptor is

   274         *   constructed to point to the same data as the given one.

   275         *   Ownership of the original descriptor stays with the caller and

   276         *   it must ensure that the lifetime of the descriptor is appropriate.

   277         *

   278         * @param aIndex Index of the bitmap in the bitmap file.

   279         *

   280         * @return Newly constructed CAknsBitmapItemDef object.

   281         *

   282         * @par Exceptions:

   283         *   If allocation fails, function leaves with a system-wide error 

   284         *   code.

   285         */

   286         IMPORT_C static CAknsBitmapItemDef* NewL( const TAknsItemID& aID, 

   287             const TDesC& aFilename, const TInt aIndex );

   288 

   289         /**

   290         * Two-phased constructor, partial initialization.

   291         * Constructs a new bitmap item definition object. Bitmap filename

   292         * and index must be set by SetFilename or SetFilenameL and SetIndex.

   293         *

   294         * @param aID Item ID of the new object.        

   295         *

   296         * @return Newly constructed CAknsBitmapItemDef object.

   297         *

   298         * @par Exceptions:

   299         *   If allocation fails, function leaves with a system-wide error 

   300         *   code.

   301         */

   302         IMPORT_C static CAknsBitmapItemDef* NewL( const TAknsItemID& aID );

   303         

   304         /**

   305         * Destructor.

   306         * Deletes the internal buffer reserved for bitmap filename.

   307         */

   308         virtual ~CAknsBitmapItemDef();

   309 

   310     public: // New functions

   311 

   312         /**

   313         * Sets the filename, ownership of the descriptor stays with the caller.

   314         * If CAknsBitmapItemDef object already owns a filename descriptor, it

   315         * is deleted.

   316         *

   317         * @since 2.0

   318         *

   319         * @param aFilename Reference to the descriptor containing new filename.

   320         *   Caller still owns the descriptor and must ensure that its lifetime

   321         *   is appropriate.

   322         */

   323         IMPORT_C void SetFilename( const TDesC& aFilename );

   324 

   325         /**

   326         * Sets the filename, content of the descriptor is copied into an

   327         * internal buffer. If CAknsBitmapItemDef object already owns a filename 

   328         * descriptor, it is deleted.

   329         *

   330         * @since 2.0

   331         *

   332         * @param aFilename Reference to the descriptor containing new filename.

   333         *   Content of the descriptor is copied into an internal buffer owned

   334         *   by CAknsBitmapItemDef.

   335         *

   336         * @par Exceptions:

   337         *   If allocation fails, function leaves with a system-wide error code.

   338         */

   339         IMPORT_C void SetFilenameL( const TDesC& aFilename );

   340         

   341         /**

   342         * Returns a reference to filename of this item definition.

   343         *

   344         * @since 2.0

   345         *

   346         * @return Reference to descriptor containing the filename. Lifetime of

   347         *   the descriptor may end when SetFilename or SetFilenameL is called 

   348         *   or CAknsBitmapItemDef object is deleted.

   349         */

   350         IMPORT_C const TDesC& Filename() const;

   351 

   352         /**

   353         * Sets bitmap file index of this item definition.

   354         *

   355         * @since 2.0

   356         *

   357         * @param aIndex New index.

   358         */

   359         IMPORT_C void SetIndex( const TInt aIndex );

   360 

   361         /**

   362         * Returns bitmap file index of this item definition.

   363         *

   364         * @since 2.0

   365         *

   366         * @return Index of the bitmap (in the bitmap file) as integer value.

   367         */

   368         IMPORT_C TInt Index() const;

   369     

   370     protected: // C++ protected constructor

   371 

   372         /**

   373         * C++ constructor for internal use.

   374         * Constructs bitmap item definition object with given ID and bitmap

   375         * index. Filename needs to be set separately.

   376         *

   377         * @since 2.0

   378         *

   379         * @param aType Type of the definition object. While this is always

   380         *   ::EAknsITBitmap for CAknsBitmapItemDef objects, derived classes

   381         *   may specify other values.

   382         *

   383         * @param aID Item ID of the new item definition.

   384         *

   385         * @param aIndex Index of the bitmap of the new item definition.

   386         *

   387         * @internal

   388         */

   389         CAknsBitmapItemDef( const TAknsItemType aType, const TAknsItemID& aID, 

   390             const TInt aIndex );    

   391     

   392     protected:  // Data

   393 

   394         TPtrC iFilename;        //!< Bitmap filename.

   395         HBufC* iFilenameBuf;    //!< Internal filename buffer.

   396         TInt iIndex;            //!< Index of bitmap in bitmap file.

   397         

   398     };

   399 

   400 /**

   401 * Masked bitmap item definition.

   402 * Masked bitmap item definition is derived from CAknsBitmapItemDef

   403 * but additionally contains a second index specifying the mask.

   404 * Item type for masked bitmap item definitions is always ::EAknsITMaskedBitmap.

   405 *

   406 * This is a public class with exported functions.

   407 * The class is not intended for derivation outside the library.

   408 *

   409 * @lib AknSkinSrv.lib

   410 *

   411 * @since 2.0

   412 */

   413 NONSHARABLE_CLASS(CAknsMaskedBitmapItemDef) :public CAknsBitmapItemDef

   414     {

   415     public:  // Constructors and destructor        

   416 

   417         /**

   418         * Two-phased constructor, complete initialization.

   419         * Constructs a new masked bitmap item definition object. 

   420         *

   421         * @param aID Item ID of the new object.

   422         *

   423         * @param aFilename Filename of the bitmap. Internal descriptor is

   424         *   constructed to point to the same data as the given one.

   425         *   Ownership of the original descriptor stays with the caller and

   426         *   it must ensure that the lifetime of the descriptor is appropriate.

   427         *

   428         * @param aIndex Index of the bitmap in the bitmap file.

   429         *

   430         * @param aMaskIndex Index of the mask in the same bitmap file.

   431         *

   432         * @return Newly constructed CAknsMaskedBitmapItemDef object.

   433         *

   434         * @par Exceptions:

   435         *   If allocation fails, function leaves with a system-wide error 

   436         *   code.

   437         */

   438         IMPORT_C static CAknsMaskedBitmapItemDef* NewL( const TAknsItemID& aID, 

   439             const TDesC& aFilename, const TInt aIndex, const TInt aMaskIndex );

   440 

   441         /**

   442         * Two-phased constructor, partial initialization.

   443         * Constructs a new masked bitmap item definition object. Bitmap 

   444         * filename and indices must be set by SetFilename or SetFilenameL,

   445         * SetIndex and SetMaskIndex.

   446         *

   447         * @param aID Item ID of the new object.        

   448         *

   449         * @return Newly constructed CAknsMaskedBitmapItemDef object.

   450         *

   451         * @par Exceptions:

   452         *   If allocation fails, function leaves with a system-wide error 

   453         *   code.

   454         */

   455         IMPORT_C static CAknsMaskedBitmapItemDef* NewL( const TAknsItemID& aID );

   456         

   457         /**

   458         * Destructor.

   459         * Provided for completeness, does not actually do anything.

   460         */

   461         virtual ~CAknsMaskedBitmapItemDef();

   462 

   463     public: // New functions

   464 

   465         /**

   466         * Sets index of mask in the bitmap file for this item definition.

   467         *

   468         * @since 2.0

   469         *

   470         * @param aMaskIndex New index.

   471         */

   472         IMPORT_C void SetMaskIndex( const TInt aMaskIndex );

   473 

   474         /**

   475         * Returns bitmap file index for bitmap mask.

   476         *

   477         * @since 2.0

   478         *

   479         * @return Index of the mask (in the bitmap file) as integer value.

   480         */

   481         IMPORT_C TInt MaskIndex() const;

   482     

   483     protected: // C++ protected constructor

   484 

   485         /**

   486         * C++ constructor for internal use.

   487         * Constructs masked bitmap item definition object with given ID and 

   488         * bitmap indices. Filename needs to be set separately.

   489         *

   490         * @param aType Type of the definition object. While this is always

   491         *   ::EAknsITMaskedBitmap for CAknsMaskedBitmapItemDef objects, 

   492         *   derived classes may specify other values.

   493         *

   494         * @param aID Item ID of the new item definition.

   495         *

   496         * @param aIndex Index of the bitmap of the new item definition.

   497         *

   498         * @param aMaskIndex Index of the bitmap mask of the new definition.

   499         *

   500         * @internal

   501         */

   502         CAknsMaskedBitmapItemDef( const TAknsItemType aType, 

   503             const TAknsItemID& aID, const TInt aIndex, const TInt aMaskIndex );

   504     

   505     protected:  // Data

   506         

   507         TInt iMaskIndex; //!< Index of mask in bitmap file.

   508         

   509     };

   510 

   511 /**

   512 * Data structure for color values.

   513 *

   514 * @since 2.0

   515 *

   516 * @internal

   517 */

   518 struct TAknsColorTableEntry

   519     {

   520     /**

   521     * Indexed color value, or -1 if RGB value is used instead.

   522     */

   523     TInt iIndex;

   524 

   525     /**

   526     * RGB-value, used only if iIndex is -1.

   527     */

   528     TUint32 iRgb;

   529     };

   530 

   531 /**

   532 * Color table item definition.

   533 * Color table item definition contains (in addition to base class data) an 

   534 * array of color values. Item type for color table item definitions is always 

   535 * ::EAknsITColorTable.

   536 *

   537 * This is a public class with exported functions.

   538 * The class is not intended for derivation outside the library.

   539 *

   540 * @lib AknSkinSrv.lib

   541 *

   542 * @since 2.0

   543 */

   544 NONSHARABLE_CLASS(CAknsColorTableItemDef) :public CAknsImageItemDef

   545     {

   546     public:  // Constructors and destructor        

   547 

   548         /**

   549         * Two-phased constructor, complete initialization.

   550         * Constructs a new color table item definition object. 

   551         *

   552         * @param aID Item ID of the new object.

   553         *

   554         * @param aNumberOfColors Number of colors available in aColors.

   555         *

   556         * @param aColors Pointer to the first color. Internal pointer is set

   557         *   to point to the same place as the given one. Ownership of the 

   558         *   color array stays with the caller and it must ensure that its 

   559         *   lifetime is appropriate.

   560         *        

   561         * @return Newly constructed CAknsColorTableItemDef object.

   562         *

   563         * @par Exceptions:

   564         *   If allocation fails, function leaves with a system-wide error 

   565         *   code.

   566         */

   567         IMPORT_C static CAknsColorTableItemDef* NewL( const TAknsItemID& aID, 

   568             const TInt aNumberOfColors, 

   569             const TAknsColorTableEntry *const aColors );

   570 

   571         /**

   572         * Two-phased constructor, partial initialization.

   573         * Constructs a new color table item definition object. Colors must

   574         * be set separately by using SetColorsL or SetColors.

   575         *

   576         * @param aID Item ID of the new object.

   577         *

   578         * @return Newly constructed CAknsColorTableItemDef object.

   579         *

   580         * @par Exceptions:

   581         *   If allocation fails, function leaves with a system-wide error 

   582         *   code.

   583         */

   584         IMPORT_C static CAknsColorTableItemDef* NewL( const TAknsItemID& aID );

   585         

   586         /**

   587         * Destructor.

   588         * If the object owns a color array, it is destroyed.

   589         */

   590         virtual ~CAknsColorTableItemDef();

   591 

   592     public: // New functions

   593 

   594         /**

   595         * Sets the colors, ownership of the color array stays with the caller.

   596         * If this object already owns a color array, it is destroyed.

   597         *

   598         * @since 2.0

   599         *

   600         * @param aNumberOfColors Number of colors in aColors.

   601         *

   602         * @param aColors Pointer to the first color. The caller still owns

   603         *   the color array and must ensure that its lifetime is appropriate.

   604         */

   605         IMPORT_C void SetColors( const TInt aNumberOfColors, 

   606             const TAknsColorTableEntry *const aColors );

   607 

   608         /**

   609         * Sets the colors, content of the array is copied to an internal

   610         * array. If this object already owns a color array, it is destroyed.

   611         *

   612         * @since 2.0

   613         *

   614         * @param aNumberOfColors Number of colors in aColors.

   615         *

   616         * @param aColors Pointer to the first color. 

   617         *

   618         * @par Exceptions:

   619         *   If allocation fails, returns with an error code.

   620         */

   621         IMPORT_C void SetColorsL( const TInt aNumberOfColors, 

   622             const TAknsColorTableEntry *const aColors );

   623 

   624         /**

   625         * Returns pointer to color values.

   626         *

   627         * @since 2.0

   628         *        

   629         * @return Pointer to color values. The array is still owned by this 

   630         *   object.

   631         */

   632         IMPORT_C const TAknsColorTableEntry* Colors() const;

   633 

   634         /**

   635         * Returns the number of colors.

   636         *

   637         * @since 2.0

   638         * 

   639         * @return Number of colors.

   640         */

   641         IMPORT_C TInt NumberOfColors() const;

   642     

   643     protected: // C++ protected constructor

   644 

   645         /**

   646         * C++ constructor for internal use.

   647         * Constructs color item definition object with given ID. Color

   648         * array must be set separately.

   649         *

   650         * @param aType Type of the definition object. While this is always

   651         *   ::EAknsITColorTable for CAknsColorTableItemDef objects, derived 

   652         *   classes may specify other values.

   653         *

   654         * @param aID Item ID of the new item definition.

   655         *

   656         * @internal

   657         */

   658         CAknsColorTableItemDef( const TAknsItemType aType, 

   659             const TAknsItemID& aID );

   660     

   661     protected:  // Data

   662 

   663         // Color array

   664         const TAknsColorTableEntry* iColorArray;

   665         // Internal (owned) color array

   666         TAknsColorTableEntry* iInternalColorArray;

   667         // Number of colors

   668         TInt iNumberOfColors;

   669     };

   670 

   671 /**

   672 * Image table item definition.

   673 * Image table item definition contains (in addition to base class data) 

   674 * an array containing image IDs. Item type for image table item definitions is

   675 * always ::EAknsITImageTable.

   676 *

   677 * This is a public class with exported functions.

   678 * The class is not intended for derivation outside the library.

   679 *

   680 * @lib AknSkinSrv.lib

   681 *

   682 * @since 2.0

   683 */

   684 NONSHARABLE_CLASS(CAknsImageTableItemDef) : public CAknsImageItemDef

   685     {

   686     public:  // Constructors and destructor        

   687 

   688         /**

   689         * Two-phased constructor, complete initialization.

   690         * Constructs an image table item definition object. 

   691         *

   692         * @param aID Item ID of the new object.

   693         *

   694         * @param aNumberOfImages Number of entries in aImages.

   695         *

   696         * @param aImages Pointer to the first item ID.

   697         *   An internal pointer is set to point to the same place as the 

   698         *   given one. Ownership of the array stays with the caller and it 

   699         *   must ensure that its lifetime is appropriate.

   700         *        

   701         * @return Newly constructed CAknsImageTableItemDef object.

   702         *

   703         * @par Exceptions:

   704         *   If allocation fails, function leaves with a system-wide error 

   705         *   code.

   706         */

   707         IMPORT_C static CAknsImageTableItemDef* NewL( const TAknsItemID& aID, 

   708             const TInt aNumberOfImages, const TAknsItemID *const aImages );

   709 

   710         /**

   711         * Two-phased constructor, partial initialization.

   712         * Constructs a new image table item definition object. Images must

   713         * be set separately by using SetImagesL or SetImages.

   714         *

   715         * @param aID Item ID of the new object.

   716         *

   717         * @return Newly constructed CAknsImageTableItemDef object.

   718         *

   719         * @par Exceptions:

   720         *   If allocation fails, function leaves with a system-wide error 

   721         *   code.

   722         */

   723         IMPORT_C static CAknsImageTableItemDef* NewL( const TAknsItemID& aID );

   724         

   725         /**

   726         * Destructor.

   727         * If the object owns an array, it is destroyed.

   728         */

   729         virtual ~CAknsImageTableItemDef();

   730 

   731     public: // New functions

   732 

   733         /**

   734         * Sets the images, ownership of the image item ID array stays with 

   735         * the caller. If this object already owns an array, it is destroyed.

   736         *

   737         * @since 2.0

   738         *

   739         * @param aNumberOfImages Number of images in aImages.

   740         *

   741         * @param aImages Pointer to the first TAknsItemID. The caller 

   742         *   still owns the array and must ensure that its lifetime is 

   743         *   appropriate.

   744         */

   745         IMPORT_C void SetImages( const TInt aNumberOfImages, 

   746             const TAknsItemID *const aImages );

   747 

   748         /**

   749         * Sets the images, content of the array is copied to an internal

   750         * array. If this object already owns an array, it is destroyed.

   751         *

   752         * @since 2.0

   753         *

   754         * @param aNumberOfImages Number of images in aImages.

   755         *

   756         * @param aImages Pointer to the first image item ID. 

   757         *

   758         * @par Exceptions:

   759         *   If allocation fails, returns with an error code.

   760         */

   761         IMPORT_C void SetImagesL( const TInt aNumberOfImages, 

   762             const TAknsItemID *const aImages );

   763 

   764         /**

   765         * Returns pointer to the first element of the image array.

   766         *

   767         * @since 2.0

   768         *        

   769         * @return Pointer to the first entry. The array is still owned 

   770         *   by this object.

   771         */

   772         IMPORT_C const TAknsItemID* Images() const;

   773 

   774         /**

   775         * Returns the number of images.

   776         *

   777         * @since 2.0

   778         * 

   779         * @return Number of images.

   780         */

   781         IMPORT_C TInt NumberOfImages() const;

   782     

   783     protected: // C++ protected constructor

   784 

   785         /**

   786         * C++ constructor for internal use.

   787         * Constructs image table item definition object with given ID.

   788         * The image array must be set separately.

   789         *

   790         * @param aType Type of the definition object. While this is always

   791         *   ::EAknsITImageTable for CAknsImageTableItemDef objects, derived 

   792         *   classes may specify other values.

   793         *

   794         * @param aID Item ID of the new item definition.

   795         *

   796         * @internal

   797         */

   798         CAknsImageTableItemDef( const TAknsItemType aType, 

   799             const TAknsItemID& aID );

   800     

   801     protected:  // Data

   802 

   803         const TAknsItemID* iImageArray;     //!< Image ID array.

   804         TAknsItemID* iInternalImageArray;   //!< Internal (owned) image ID array.

   805         TInt iNumberOfImages;               //!< Number of images in the array.

   806     };

   807 

   808 /**

   809 * Data structure for animation frame properties.

   810 *

   811 * @since 2.0

   812 *

   813 * @internal

   814 */

   815 struct TAknsBmpAnimFrameInfo

   816     {

   817     /**

   818     * Frame time in milliseconds or -1 if not defined.

   819     */

   820     TInt16 iTime;

   821 

   822     /**

   823     * Frame position X-coordinate.

   824     */

   825     TInt16 iPosX;

   826 

   827     /**

   828     * Frame position Y-coordinate.

   829     */

   830     TInt16 iPosY;

   831     };

   832 

   833 /**

   834 * Bitmap animation item definition.

   835 * Bitmap animationitem definition contains (in addition to base class data) 

   836 * animation properties and an array containing frame properties.

   837 * Item type for image table item definitions is

   838 * always ::EAknsITBmpAnim.

   839 *

   840 * This is a public class with exported functions.

   841 * The class is not intended for derivation outside the library.

   842 *

   843 * @lib AknSkinSrv.lib

   844 *

   845 * @since 2.0

   846 */

   847 NONSHARABLE_CLASS(CAknsBmpAnimItemDef) : public CAknsImageTableItemDef

   848     {

   849     public:  // Constructors and destructor        

   850 

   851         /**

   852         * Two-phased constructor, complete initialization.

   853         * Constructs a bitmap animation item definition object. 

   854         *

   855         * @param aID Item ID of the new object.

   856         *

   857         * @param aNumberOfImages Number of entries in aImages.

   858         *

   859         * @param aImages Pointer to the first item ID.

   860         *   An internal pointer is set to point to the same place as the 

   861         *   given one. Ownership of the array stays with the caller and it 

   862         *   must ensure that its lifetime is appropriate.

   863         *

   864         * @param aFrameInfos Pointer to the first frame info.

   865         *   Ownership is handled as with aImages.

   866         *        

   867         * @return Newly constructed CAknsBmpAnimItemDef object.

   868         *

   869         * @par Exceptions:

   870         *   If allocation fails, function leaves with a system-wide error 

   871         *   code.

   872         */

   873         IMPORT_C static CAknsBmpAnimItemDef* NewL( const TAknsItemID& aID, 

   874             const TInt aNumberOfImages, const TAknsItemID *const aImages,

   875             const TAknsBmpAnimFrameInfo *const aFrameInfos );

   876 

   877         /**

   878         * Two-phased constructor, partial initialization.

   879         * Constructs a new bitmap animation item definition object. Images must

   880         * be set separately by using SetImagesL and SetFrameInfosL or SetImages

   881         * and SetFrameInfos.

   882         *

   883         * @param aID Item ID of the new object.

   884         *

   885         * @return Newly constructed CAknsBmpAnimItemDef object.

   886         *

   887         * @par Exceptions:

   888         *   If allocation fails, function leaves with a system-wide error 

   889         *   code.

   890         */

   891         IMPORT_C static CAknsBmpAnimItemDef* NewL( const TAknsItemID& aID );

   892         

   893         /**

   894         * Destructor.

   895         * If the object owns an array, it is destroyed.

   896         */

   897         virtual ~CAknsBmpAnimItemDef();

   898 

   899     public: // New functions

   900 

   901         /**

   902         * Sets frame properties, ownership of the frame info array stays with 

   903         * the caller. If this object already owns an array, it is destroyed.

   904         *

   905         * The number of frame info objects in the array must match the number

   906         * of images. This implies that SetFrameInfos can not be called before

   907         * images have been set.

   908         *

   909         * @since 2.0

   910         *        

   911         * @param aFrameInfos Pointer to the first TAknsBmpAnimFrameInfo. The 

   912         *   caller still owns the array and must ensure that its lifetime is 

   913         *   appropriate.

   914         */

   915         IMPORT_C void SetFrameInfos( 

   916             const TAknsBmpAnimFrameInfo *const aFrameInfos );

   917 

   918         /**

   919         * Sets frame propertis, content of the array is copied to an internal

   920         * array. If this object already owns an array, it is destroyed.

   921         *

   922         * The number of frame info objects in the array must match the number

   923         * of images. This implies that SetFrameInfosL can not be called before

   924         * images have been set.

   925         *

   926         * @since 2.0

   927         *

   928         * @param aFrameInfos Pointer to the first TAknsBmpAnimFrameInfo. 

   929         *

   930         * @par Exceptions:

   931         *   If allocation fails, returns with an error code.

   932         */

   933         IMPORT_C void SetFrameInfosL(

   934             const TAknsBmpAnimFrameInfo *const aFrameInfos );

   935 

   936         /**

   937         * Returns pointer to the first element of the frame info array.

   938         *

   939         * @since 2.0

   940         *        

   941         * @return Pointer to the first entry. The array is still owned 

   942         *   by this object.

   943         */

   944         IMPORT_C const TAknsBmpAnimFrameInfo* FrameInfos() const;

   945 

   946         /**

   947         * Sets the flag indicating whether the last frame should be

   948         * interpreted as the background (i.e. excluded from the animation

   949         * itself).

   950         *

   951         * @since 2.0

   952         *

   953         * @param aLastFrameBg Boolean value.

   954         */

   955         IMPORT_C void SetLastFrameBackground( TBool aLastFrameBg );

   956 

   957         /**

   958         * Retrieves the flag value indicating whether the last frame

   959         * should be interpreted as the background.

   960         *

   961         * @since 2.0

   962         *

   963         * @return Boolean value.

   964         */

   965         IMPORT_C TBool LastFrameBackground() const;

   966 

   967         /**

   968         * Sets the frame interval for the entire animation.

   969         *

   970         * @since 2.0

   971         *

   972         * @param aFrameInterval Frame interval in milliseconds or -1.

   973         */

   974         IMPORT_C void SetFrameInterval( const TInt16 aFrameInterval );

   975 

   976         /**

   977         * Retrieves the frame interval.

   978         *

   979         * @since 2.0

   980         *

   981         * @return Frame interval in milliseconds or -1.

   982         */

   983         IMPORT_C TInt16 FrameInterval() const;

   984 

   985         /**

   986         * Sets the play mode for the entire animation.

   987         *

   988         * @since 2.0

   989         *

   990         * @param aPlayMode Play mode.

   991         */

   992         IMPORT_C void SetPlayMode( const TInt16 aPlayMode );

   993 

   994         /**

   995         * Retrieves the play mode.

   996         *

   997         * @since 2.0

   998         *

   999         * @return Play mode.

  1000         */

  1001         IMPORT_C TInt16 PlayMode() const;

  1002 

  1003         /**

  1004         * Sets the flash property for the entire animation.

  1005         *

  1006         * @since 2.0

  1007         *

  1008         * @param aFlash Flash flag value.

  1009         */

  1010         IMPORT_C void SetFlash( const TBool aFlash );

  1011 

  1012         /**

  1013         * Retrieves the flash property.

  1014         *

  1015         * @since 2.0

  1016         *

  1017         * @return Flash flag value.

  1018         */

  1019         IMPORT_C TBool Flash() const;

  1020     

  1021     protected: // C++ protected constructor

  1022 

  1023         /**

  1024         * C++ constructor for internal use.

  1025         * Constructs bitmap animation item definition object with given ID.

  1026         * The image array and frame properties must be set separately.

  1027         *

  1028         * @param aType Type of the definition object. While this is always

  1029         *   ::EAknsITBmpAnim for CAknsBmpAnimItemDef objects, derived 

  1030         *   classes may specify other values.

  1031         *

  1032         * @param aID Item ID of the new item definition.

  1033         *

  1034         * @internal

  1035         */

  1036         CAknsBmpAnimItemDef( const TAknsItemType aType, 

  1037             const TAknsItemID& aID );

  1038     

  1039     protected: // Data

  1040 

  1041         const TAknsBmpAnimFrameInfo* iFrameArray;   //!< Frame array.

  1042         TAknsBmpAnimFrameInfo* iInternalFrameArray; //!< Internal (owned) image frame array.

  1043 

  1044         TBool iLastFrameBackground; //!< Last frame used as background flag.

  1045         TInt16 iFrameInterval;  //!< Frame interval.

  1046         TInt16 iPlayMode;       //!< Play mode.

  1047         TBool iFlash;           //!< Flash flag.

  1048     };

  1049 

  1050 /**

  1051 * String item definition.

  1052 * String item definition consists of (in addition to base class data) 

  1053 * a single string value. Item type for string item definitions is 

  1054 * ::EAknsITString

  1055 *

  1056 * This is a public class with exported functions.

  1057 * The class is not intended for derivation outside the library.

  1058 *

  1059 * @lib AknSkinSrv.lib

  1060 *

  1061 * @since 2.6

  1062 */

  1063 NONSHARABLE_CLASS(CAknsStringItemDef) : public CAknsItemDef

  1064     {

  1065     public:  // Constructors and destructor        

  1066 

  1067         /**

  1068         * Two-phased constructor.

  1069         * Constructs a new string item definition object. 

  1070         *

  1071         * @since 2.6

  1072         *

  1073         * @param aID Item ID of the new object.

  1074         *        

  1075         * @return Newly constructed CAknsStringItemDef object.

  1076         *

  1077         * @par Exceptions:

  1078         *   If allocation fails, function leaves with a system-wide error 

  1079         *   code.

  1080         */

  1081         IMPORT_C static CAknsStringItemDef* NewL( const TAknsItemID& aID );

  1082         

  1083         /**

  1084         * Destructor.

  1085         */

  1086         virtual ~CAknsStringItemDef();

  1087 

  1088     public: // New functions

  1089 

  1090         /**

  1091         * Sets the string, content of the descriptor is copied into an

  1092         * internal buffer. If CAknsStringItemDef object already owns a filename

  1093         * descriptor, it is deleted.

  1094         *

  1095         * @since 2.6

  1096         *

  1097         * @param aString Reference to the descriptor containing new value.

  1098         *   Content of the descriptor is copied into an internal buffer owned

  1099         *   by CAknsStringItemDef.

  1100         *

  1101         * @par Exceptions:

  1102         *   If allocation fails, function leaves with a system-wide error code.

  1103         */

  1104         IMPORT_C void SetStringL( const TDesC& aString );

  1105         

  1106         /**

  1107         * Returns a reference to the string value of this item definition.

  1108         *

  1109         * @since 2.6

  1110         *

  1111         * @return Reference to descriptor containing the value. Lifetime of

  1112         *   the descriptor may end when SetStringL is called 

  1113         *   or CAknsStringItemDef object is deleted.

  1114         */

  1115         IMPORT_C const TDesC& String() const;

  1116     

  1117     protected: // C++ protected constructor

  1118 

  1119         /**

  1120         * C++ constructor for internal use.

  1121         * Constructs an string item definition object with given ID.

  1122         *

  1123         * @since 2.6

  1124         *

  1125         * @param aType Type of the definition object. While this is always

  1126         *   ::EAknsITString for CAknsStringItemDef objects, derived classes

  1127         *   may specify other values.

  1128         *

  1129         * @param aID Item ID of the new item definition.

  1130         *        

  1131         * @internal

  1132         */

  1133         CAknsStringItemDef( const TAknsItemType aType, const TAknsItemID& aID );

  1134