// 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_