/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  ?Description

*

*/

#ifndef AKNSITEMDEF_H

#define AKNSITEMDEF_H

//  INCLUDES

#include <AknsItemID.h>

#include <gdi.h>

// FORWARD DECLARATIONS

struct TAknsImageAttributeData;

// CLASS DECLARATIONS

/**

* Base class for item definitions.

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

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

* depending of the type of the resource. 

*

* CAknsItemDef does not itself have any dynamically allocated members.

* Therefore the members of its friend classes can instantiate CAknsItemDef

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

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

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

* proper destruction.

*

* This is a public class with exported functions.

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

*

* @lib AknSkinSrv.lib

*

* @since 2.0

*/

class CAknsItemDef : public CBase

    {    

    public: // Constructors and destructors        

        /**

        * Two-phased constructor.

        * Constructs item definition object with specified ID, item type

        * ::EAknsITUnknown and localization type ::EAknsIDLTDefault.

        *

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

        *

        * @return Newly constructed CAknsItemDef object.

        *

        * @par Exceptions:

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

        */

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

        /**

        * Destructor.

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

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

        */

        IMPORT_C virtual ~CAknsItemDef();

    public: // New functions

        /**

        * Returns the item type of this item definition.

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

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

        *

        * @since 2.0

        *

        * @return Type of the item definition as TAknsItemType.

        */

        IMPORT_C TAknsItemType Type() const;

        /**

        * Returns the item ID of this item definition.

        *

        * @since 2.0

        *

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

        */

        IMPORT_C TAknsItemID ID() const;

        /**

        * Determines the order of two CAknsItemDef objects.

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

        * in TAknsItemID::LinearOrder().

        *

        * @since 2.0

        *

        * @param aFirst First object to be compared.

        *

        * @param aSecond Second object to be compared.

        *

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

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

        *   object is greater than the second.

        */

        IMPORT_C static TInt LinearOrder( const CAknsItemDef& aFirst, 

            const CAknsItemDef& aSecond );

    private: // Reserved exports

        /**

        * Reserved for future use.

        *

        * @since 2.0        

        */

        IMPORT_C void Reserved1();

        /**

        * Reserved for future use.

        *

        * @since 2.0        

        */

        IMPORT_C void Reserved2();

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

        /**

        * C++ constructor for derived classes.

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

        * and localization type ::EAknsIDLTDefault.

        *

        * @param aType Item type of the new object.

        *

        * @param aID Item ID of the new object.

        *

        * @internal

        */

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

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

        /**

        * C++ constructor for internal use.

        * Constructs item definition object with specified ID and item type

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

        *

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

        *

        * @internal

        */

        IMPORT_C CAknsItemDef( const TAknsItemID& aID );

    protected:  // Data

        TAknsItemType iType;            //!< Item type.

        TAknsItemID iID;                //!< Item ID.

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

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

    private:    // Friend classes

        friend class CAknsAppSkinInstance;

    };

/**

* Image item definition.

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

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

* is ::EAknsITImage

*

* This is a public class with exported functions.

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

*

* @lib AknSkinSrv.lib

*

* @since 2.0

*/

NONSHARABLE_CLASS(CAknsImageItemDef) : public CAknsItemDef

    {

    public:  // Constructors and destructor        

        /**

        * Two-phased constructor.

        * Constructs a new image item definition object. 

        *

        * @param aID Item ID of the new object.

        *        

        * @return Newly constructed CAknsImageItemDef object.

        *

        * @par Exceptions:

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

        *   code.

        */

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

        /**

        * Destructor.

        */

        virtual ~CAknsImageItemDef();

    public: // New functions

        /**

        * Sets the image attributes for this image definition.

        *

        * @since 2.0

        */

        IMPORT_C void SetAttributesL( const TAknsImageAttributeData& aAttributes );

        /**

        * Returns the image attributes for this image definition.

        *

        * @since 2.0

        */

        IMPORT_C const TAknsImageAttributeData* Attributes() const;

    protected: // C++ protected constructor

        /**

        * C++ constructor for internal use.

        * Constructs an image item definition object with given ID.

        *

        * @since 2.0

        *

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

        *   ::EAknsITImage for CAknsImageItemDef objects, derived classes

        *   may specify other values.

        *

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

        *        

        * @internal

        */

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

    protected:  // Data

        // Image attributes

        TAknsImageAttributeData* iAttributeData;

    };

/**

* Bitmap item definition.

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

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

* is always ::EAknsITBitmap.

*

* This is a public class with exported functions.

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

*

* @lib AknSkinSrv.lib

*

* @since 2.0

*/

NONSHARABLE_CLASS(CAknsBitmapItemDef) : public CAknsImageItemDef

    {

    public:  // Constructors and destructor        

        /**

        * Two-phased constructor, complete initialization.

        * Constructs a new bitmap item definition object. 

        *

        * @param aID Item ID of the new object.

        *

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

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

        *   Ownership of the original descriptor stays with the caller and

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

        *

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

        *

        * @return Newly constructed CAknsBitmapItemDef object.

        *

        * @par Exceptions:

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

        *   code.

        */

        IMPORT_C static CAknsBitmapItemDef* NewL( const TAknsItemID& aID, 

            const TDesC& aFilename, const TInt aIndex );

        /**

        * Two-phased constructor, partial initialization.

        * Constructs a new bitmap item definition object. Bitmap filename

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

        *

        * @param aID Item ID of the new object.        

        *

        * @return Newly constructed CAknsBitmapItemDef object.

        *

        * @par Exceptions:

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

        *   code.

        */

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

        /**

        * Destructor.

        * Deletes the internal buffer reserved for bitmap filename.

        */

        virtual ~CAknsBitmapItemDef();

    public: // New functions

        /**

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

        * If CAknsBitmapItemDef object already owns a filename descriptor, it

        * is deleted.

        *

        * @since 2.0

        *

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

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

        *   is appropriate.

        */

        IMPORT_C void SetFilename( const TDesC& aFilename );

        /**

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

        * internal buffer. If CAknsBitmapItemDef object already owns a filename 

        * descriptor, it is deleted.

        *

        * @since 2.0

        *

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

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

        *   by CAknsBitmapItemDef.

        *

        * @par Exceptions:

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

        */

        IMPORT_C void SetFilenameL( const TDesC& aFilename );

        /**

        * Returns a reference to filename of this item definition.

        *

        * @since 2.0

        *

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

        *   the descriptor may end when SetFilename or SetFilenameL is called 

        *   or CAknsBitmapItemDef object is deleted.

        */

        IMPORT_C const TDesC& Filename() const;

        /**

        * Sets bitmap file index of this item definition.

        *

        * @since 2.0

        *

        * @param aIndex New index.

        */

        IMPORT_C void SetIndex( const TInt aIndex );

        /**

        * Returns bitmap file index of this item definition.

        *

        * @since 2.0

        *

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

        */

        IMPORT_C TInt Index() const;

    protected: // C++ protected constructor

        /**

        * C++ constructor for internal use.

        * Constructs bitmap item definition object with given ID and bitmap

        * index. Filename needs to be set separately.

        *

        * @since 2.0

        *

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

        *   ::EAknsITBitmap for CAknsBitmapItemDef objects, derived classes

        *   may specify other values.

        *

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

        *

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

        *

        * @internal

        */

        CAknsBitmapItemDef( const TAknsItemType aType, const TAknsItemID& aID, 

            const TInt aIndex );    

    protected:  // Data

        TPtrC iFilename;        //!< Bitmap filename.

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

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

    };

/**

* Masked bitmap item definition.

* Masked bitmap item definition is derived from CAknsBitmapItemDef

* but additionally contains a second index specifying the mask.

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

*

* This is a public class with exported functions.

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

*

* @lib AknSkinSrv.lib

*

* @since 2.0

*/

NONSHARABLE_CLASS(CAknsMaskedBitmapItemDef) :public CAknsBitmapItemDef

    {

    public:  // Constructors and destructor        

        /**

        * Two-phased constructor, complete initialization.

        * Constructs a new masked bitmap item definition object. 

        *

        * @param aID Item ID of the new object.

        *

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

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

        *   Ownership of the original descriptor stays with the caller and

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

        *

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

        *

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

        *

        * @return Newly constructed CAknsMaskedBitmapItemDef object.

        *

        * @par Exceptions:

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

        *   code.

        */

        IMPORT_C static CAknsMaskedBitmapItemDef* NewL( const TAknsItemID& aID, 

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

        /**

        * Two-phased constructor, partial initialization.

        * Constructs a new masked bitmap item definition object. Bitmap 

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

        * SetIndex and SetMaskIndex.

        *

        * @param aID Item ID of the new object.        

        *

        * @return Newly constructed CAknsMaskedBitmapItemDef object.

        *

        * @par Exceptions:

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

        *   code.

        */

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

        /**

        * Destructor.

        * Provided for completeness, does not actually do anything.

        */

        virtual ~CAknsMaskedBitmapItemDef();

    public: // New functions

        /**

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

        *

        * @since 2.0

        *

        * @param aMaskIndex New index.

        */

        IMPORT_C void SetMaskIndex( const TInt aMaskIndex );

        /**

        * Returns bitmap file index for bitmap mask.

        *

        * @since 2.0

        *

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

        */

        IMPORT_C TInt MaskIndex() const;

    protected: // C++ protected constructor

        /**

        * C++ constructor for internal use.

        * Constructs masked bitmap item definition object with given ID and 

        * bitmap indices. Filename needs to be set separately.

        *

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

        *   ::EAknsITMaskedBitmap for CAknsMaskedBitmapItemDef objects, 

        *   derived classes may specify other values.

        *

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

        *

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

        *

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

        *

        * @internal

        */

        CAknsMaskedBitmapItemDef( const TAknsItemType aType, 

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

    protected:  // Data

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

    };

/**

* Data structure for color values.

*

* @since 2.0

*

* @internal

*/

struct TAknsColorTableEntry

    {

    /**

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

    */

    TInt iIndex;

    /**

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

    */

    TUint32 iRgb;

    };