// Copyright (c) 2008-2009 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:

//

/**

 @file

 @publishedPartner

 @prototype

*/

#ifndef _DISPLAYCONFIGURATION__INCLUDED_

#define _DISPLAYCONFIGURATION__INCLUDED_

#include <babitflags.h> 

#include <gdi.h>

/**

 * Base class for display configuration hierarchy. Defines common facilities for

 * all configurations (size, mask, accessibility).

 */

class TDisplayConfigurationBase

	{

public:

	/**

	 * Enumeration of all of the display configuration attributes. Used in combination

	 * when calling ClearSettings() and SettingsDefined(). If attributes are added,

	 * corresponding enumeration bits must also be added.

	 */

	enum TAttribute

		{

		EResolution = 0,

		ERotation,

		EResolutionTwips,

		EAttributeMax	//this should safely work with value 32.

		};

	/**

	 * 	Enumeration of the panics that may be raised when filling the display configuration

	 * 	These are all contractual input checks and should be avoidable by correctly written callers.

	 * 	

	 **/

	enum	TPanics

		{

			EPanicNegResolution=1,		//<Input resolution size has negative ordinate

			EPanicSemiZeroResolution,	//<Input resolution size has only 1 zero ordinate

			EPanicNonOpaqueBackground,	//<Input background color is not opaque

			EPanicIllegalRotation,		//<Input rotation value is out of range

			EPanicNegTwips,				//<Input twips size has negative ordinate 

			EPanicSemiZeroTwips,		//<Input twips size has only 1 zero ordinate 

			EPanicConfigInvalid			//<Input config version is invalid

		};

public:

	/**

	 * Reads the version field.

	 * 

	 * The version is set automatically in the constructor, or by the GetDisplayConfiguration() 

	 * method to indicate the sender's supported structure version. The version reported after 

	 * GetDisplayConfiguration() will match the version of one of the hierarchy of TDisplayConfiguration 

	 * classes documented in the header, and will never exceed the constructed version.

	 * 

	 * @return The defined version of this display configuration instance, in bytes.

	 */

	inline TInt Version() const;

	/**

	 * Marks the given attribute as undefined.

	 * 

	 * @param aAttribute The attribute to set as undefined.

	 */

	inline void Clear(TAttribute aAttribute);

	/**

	 * Marks all attributes as undefined.

	 */

	inline void ClearAll();

	/**

	 * Check if a particular member is defined.

	 * 

	 * @param aAttribute The attribute to check.

	 * @return ETrue if the attribute is defined, EFalse otherwise.

	 */

	inline TBool IsDefined(TAttribute aAttribute) const;

protected:

	/**

	 * Constructs a TDisplayConfigurationBase, setting the version to aVersion and all 

	 * attributes undefined.

	 * 

	 * Generally used internally in the constructor chain.

	 * 

	 * @param aVersion The defined size of this object.

	 */

	inline TDisplayConfigurationBase(TInt aVersion);

	/** 

	 * Internal function for determining whether a given field name is accessible for an 

	 * object of the current defined size. This must be used before trying to access any field.

	 * 

	 * @param aMember The name of the field to check.

	 * @return ETrue if the field is accessible, EFalse if not.

	 */

	template <class TMember> TBool MemberAccessible(const TMember& aMember) const

		{

		return iVersion>=sizeof(TMember)+TInt(&aMember)-TInt(this);

		}

	inline void Panic(TInt aPanicNo);	//Should be a TPanic

	/**

	 * Compares two TDisplayConfigurationBase instances.

	 * 

	 * Generally used internally in the comparison chain. The two objects are equivalent if 

	 * they have the same version and the same set of attributes defined.

	 * 

	 * @param aRhs The object to compare with this object

	 * @return ETrue if the objects are equivalent, EFalse if not.

	 */

	inline TBool operator == (const TDisplayConfigurationBase& aRhs) const;

private:

	//Intentionally blocked functionality

	inline TDisplayConfigurationBase();

	inline TDisplayConfigurationBase(const TDisplayConfigurationBase& aDisplayConfigurationBase);

	inline TDisplayConfigurationBase operator=(const TDisplayConfigurationBase& aRhs) const;

protected:

	/**

	 * Size to treat this object in bytes. Used to provide backward and forward

	 * compatibility.

	 */

	TInt iVersion;

	/**

	 * Indicates which fields in the configuration have defined values. If a field

	 * contains an undefined value, it must be ignored.

	 * See TAttribute for possible bit values.

	 */

	TBitFlags32 iDefined;

	};

/**

 * First collection of display configuration settings.

 * 

 */

class TDisplayConfiguration1 : public TDisplayConfigurationBase

	{

public:

	/** Defines possible rotation values. */

	enum TRotation

		{

		/** Normal orientation is supported. */

		ERotationNormal,

		/** A 90 degree rotation is supported. */

		ERotation90CW,

		/** A 180 degree rotation is supported. */

		ERotation180,

		/** A 270 degree rotation is supported. */

		ERotation270CW,

		/** Illegal rotation value. */

		ERotationIllegal

		};

public:

	/**

	 * Construct a TDisplayConfiguration1 version object with all attributes undefined.

	 * 

	 * This can be used to create a specific version of configuration:

	 * 	TDisplayConfiguration config(TDisplayConfiguration1.Version());

	 */

	inline TDisplayConfiguration1();

	/**

	 * Defines the resolution for the display, in pixels.

	 * 

	 * This always corresponds to a rotation of ERotationNormal. If a display can be 

	 * disabled, (0,0) can be used to do so. A display can be disabled if the 

	 * resolution list includes (0,0).

	 * 

	 * @param aSize The resolution in pixels.

	 */

	inline void SetResolution(const TSize& aSize);

	/**

	 * Retrieves the resolution, if defined.

	 * 

	 * If the resolution is undefined, the parameter is left unchanged. A resolution 

	 * of (0,0) means the display is disabled.

	 * 

	 * @see IsDefined

	 * @see TAttribute::EResolution

	 * 

	 * @param aSize Receives the resolution.

	 */

	inline TBool GetResolution(TSize& aSize) const;

	/**

	 * Defines the rotation for the display.

	 * 

	 * The values that can be passed in here correspond directly to UI rotation values that can be 

	 * passed in to CWsScreenDevice::SetScreenSizeAndRotation(), CWsScreenDevice::SetCurrentRotations() 

	 * and so on, although the type is defined locally to avoid undesirable interdependencies in 

	 * the interface. Variables of the two types may be freely cast to the other type.

	 * 

	 * @see CFbsBitGc::TGraphicsOrientation

	 * @see CWsScreenDevice

	 * 

	 * @param aRotation The display rotation.

	 */

	inline void SetRotation(TRotation);

	/**

	 * Retrieves the rotation, if defined.

	 * 

	 * If the rotation is undefined, the parameter is left unchanged.

	 * 

	 * @see IsDefined

	 * @see TAttribute::ERotation

	 * 

	 * @param aSize Receives the rotation

	 * @return ETrue if the rotation is defined, EFalse otherwise.

	 */

	inline TBool GetRotation(TRotation&)const;

	/**

	 * Defines the physical size of the display resolution area, in twips.

	 * 

	 * @param aSizeInTwips Provides the size in twips.

	 */

	inline void SetResolutionTwips(const TSize& aSize);

	/**

	 * Retrieves the physical size of the display resolution area, in twips, if defined.

	 * 

	 * For displays that have a fixed size, or can report their size, the physical 

	 * dimensions corresponding to the current resolution shall be defined. Where the display's 

	 * physical size cannot be determined (such as with composite video output, or a projector) 

	 * an arbitrary size shall be defined that reflects the pixel aspect ratio.

	 * 

	 * If the display is not connected or output is disabled, the physical size shall not 

	 * be defined. If the physical size is undefined, the parameter is left unchanged.

	 * 

	 * @see IsDefined

	 * @see TAttribute::EResolutionTwips

	 * 

	 * @param aSizeInTwips Receives size in twips.

	 * @return ETrue if the size is defined, EFalse if not.

	 */

	inline TBool GetResolutionTwips(TSize& aSize) const;

protected:

	/**

	 * Constructor for passing through a version already supplied.

	 * 

	 * Generally used internally in the constructor chain.

	 * 

	 * @param aVersion - Version of the class already calculated and being passed up 

	 * through the classes.

	 */

	inline TDisplayConfiguration1(TInt aVersion);

	/**

	 * Compares two TDisplayConfiguration1 instances.

	 * 

	 * Generally used internally in the comparison chain. The two objects are equivalent if they have 

	 * the same version, the same set of attributes defined and all the defined attributes are the 

	 * same. Undefined attributes are not compared.

	 * 

	 * @param aRhs The object to compare with this object.

	 * @return ETrue if the objects are equivalent, EFalse if not.

	 */

	inline TBool operator == (const TDisplayConfiguration1& aRhs)const;

private:

	//Intentionally blocked functionality

	inline TDisplayConfiguration1(const TDisplayConfiguration1& aDisplayConfiguration1);

	inline TDisplayConfiguration1 operator=(const TDisplayConfiguration1& aRhs) const;

private:

	//Streamable data members

	TSize 	iResolution;

	TInt	iRotation;	//0,1,2,3

	TSize	iTwipsSize;

	};

/**

 * The display configuration class for general use.

 * 

 * May be extended by adding a chain of classes between this and TDisplayConfiguration1.

 * If so, also update the typedef TDisplayConfigurationTop.

 * 

 */

class TDisplayConfiguration : public TDisplayConfiguration1

	{

private:	

	typedef TDisplayConfiguration1	TDisplayConfigurationTop;

public:

	/**

	 * Construct a configuration of the default version with all attributes undefined.

	 */

	inline TDisplayConfiguration():	TDisplayConfigurationTop()

		{}

	/**

	 * Copy constructor. This constructor will read the version field of the source and target 

	 * objects and only copy the common set of fields. Any remaining fields in the target 

	 * object will be set as undefined.

	 * 

	 * @param aDisplayConfiguration Configuration to be copied.

	 */

	inline TDisplayConfiguration(const TDisplayConfiguration& aDisplayConfiguration);

	/**

	 * Constructs a display configuration for a particular version.

	 * 

	 * This constructor is designed to be used with the value returned by 

	 * MDisplayControlBase::PreferredDisplayConfigurationVersion(), and initializes the members 

	 * to represent an object compatible with that.

	 * 

	 * The version used is the earlier of aVersion and the compile time version 

	 * of TDisplayConfiguration.

	 * 

	 * @param aVersion Caller-defined maximum version of configuration.

	 */

	inline TDisplayConfiguration(TInt aVersion);

	/**

	 * Compares two TDisplayConfiguration instances.

	 * 

	 * The two objects are equivalent if they have the same version, the same set of attributes defined

	 * and all the defined attributes are the same. Undefined attributes are not compared.

	 * 

	 * @param aRhs The object to compare with this object.

	 * @return ETrue if the objects are equivalent, EFalse if not.

	 */

	inline TBool operator == (const TDisplayConfiguration& aRhs)const

		{

		return TDisplayConfiguration1::operator==(aRhs);

		}

private:

	//Intentionally blocked functionality

	inline TDisplayConfiguration operator=(const TDisplayConfiguration& aRhs) const;

	};

#include <graphics/displayconfiguration.inl>

#endif // _DISPLAYCONFIGURATION__INCLUDED_