1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @prototype

    20 */

    21 

    22 #ifndef _DISPLAYCONFIGURATION__INCLUDED_

    23 #define _DISPLAYCONFIGURATION__INCLUDED_

    24 

    25 #include <babitflags.h> 

    26 #include <gdi.h>

    27 

    28 

    29 /**

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

    31  * all configurations (size, mask, accessibility).

    32  */

    33 class TDisplayConfigurationBase

    34 	{

    35 public:

    36 	/**

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

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

    39 	 * corresponding enumeration bits must also be added.

    40 	 */

    41 	enum TAttribute

    42 		{

    43 		EResolution = 0,

    44 		ERotation,

    45 		EResolutionTwips,

    46 		

    47 		EAttributeMax	//this should safely work with value 32.

    48 		};

    49 	/**

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

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

    52 	 * 	

    53 	 **/

    54 	enum	TPanics

    55 		{

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

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

    58 			EPanicNonOpaqueBackground,	//<Input background color is not opaque

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

    60 			EPanicNegTwips,				//<Input twips size has negative ordinate 

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

    62 			EPanicConfigInvalid			//<Input config version is invalid

    63 		};

    64 public:

    65 	/**

    66 	 * Reads the version field.

    67 	 * 

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

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

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

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

    72 	 * 

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

    74 	 */

    75 	inline TInt Version() const;

    76 	/**

    77 	 * Marks the given attribute as undefined.

    78 	 * 

    79 	 * @param aAttribute The attribute to set as undefined.

    80 	 */

    81 	inline void Clear(TAttribute aAttribute);

    82 	/**

    83 	 * Marks all attributes as undefined.

    84 	 */

    85 	inline void ClearAll();

    86 	/**

    87 	 * Check if a particular member is defined.

    88 	 * 

    89 	 * @param aAttribute The attribute to check.

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

    91 	 */

    92 	inline TBool IsDefined(TAttribute aAttribute) const;

    93 protected:

    94 	/**

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

    96 	 * attributes undefined.

    97 	 * 

    98 	 * Generally used internally in the constructor chain.

    99 	 * 

   100 	 * @param aVersion The defined size of this object.

   101 	 */

   102 	inline TDisplayConfigurationBase(TInt aVersion);

   103 	/** 

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

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

   106 	 * 

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

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

   109 	 */

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

   111 		{

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

   113 		}

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

   115 	/**

   116 	 * Compares two TDisplayConfigurationBase instances.

   117 	 * 

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

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

   120 	 * 

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

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

   123 	 */

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

   125 private:

   126 	//Intentionally blocked functionality

   127 	inline TDisplayConfigurationBase();

   128 	inline TDisplayConfigurationBase(const TDisplayConfigurationBase& aDisplayConfigurationBase);

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

   130 

   131 protected:

   132 	/**

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

   134 	 * compatibility.

   135 	 */

   136 	TInt iVersion;

   137 	/**

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

   139 	 * contains an undefined value, it must be ignored.

   140 	 * See TAttribute for possible bit values.

   141 	 */

   142 	TBitFlags32 iDefined;

   143 	};

   144 

   145 /**

   146  * First collection of display configuration settings.

   147  * 

   148  */

   149 class TDisplayConfiguration1 : public TDisplayConfigurationBase

   150 	{

   151 public:

   152 	/** Defines possible rotation values. */

   153 	enum TRotation

   154 		{

   155 		/** Normal orientation is supported. */

   156 		ERotationNormal,

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

   158 		ERotation90CW,

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

   160 		ERotation180,

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

   162 		ERotation270CW,

   163 		/** Illegal rotation value. */

   164 		ERotationIllegal

   165 		};

   166 public:

   167 	/**

   168 	 * Construct a TDisplayConfiguration1 version object with all attributes undefined.

   169 	 * 

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

   171 	 * 	TDisplayConfiguration config(TDisplayConfiguration1.Version());

   172 	 */

   173 	inline TDisplayConfiguration1();

   174 	/**

   175 	 * Defines the resolution for the display, in pixels.

   176 	 * 

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

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

   179 	 * resolution list includes (0,0).

   180 	 * 

   181 	 * @param aSize The resolution in pixels.

   182 	 */

   183 	inline void SetResolution(const TSize& aSize);

   184 	/**

   185 	 * Retrieves the resolution, if defined.

   186 	 * 

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

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

   189 	 * 

   190 	 * @see IsDefined

   191 	 * @see TAttribute::EResolution

   192 	 * 

   193 	 * @param aSize Receives the resolution.

   194 	 */

   195 	inline TBool GetResolution(TSize& aSize) const;

   196 	/**

   197 	 * Defines the rotation for the display.

   198 	 * 

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

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

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

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

   203 	 * 

   204 	 * @see CFbsBitGc::TGraphicsOrientation

   205 	 * @see CWsScreenDevice

   206 	 * 

   207 	 * @param aRotation The display rotation.

   208 	 */

   209 	inline void SetRotation(TRotation);

   210 	/**

   211 	 * Retrieves the rotation, if defined.

   212 	 * 

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

   214 	 * 

   215 	 * @see IsDefined

   216 	 * @see TAttribute::ERotation

   217 	 * 

   218 	 * @param aSize Receives the rotation

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

   220 	 */

   221 	inline TBool GetRotation(TRotation&)const;

   222 	/**

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

   224 	 * 

   225 	 * @param aSizeInTwips Provides the size in twips.

   226 	 */

   227 	inline void SetResolutionTwips(const TSize& aSize);

   228 	/**

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

   230 	 * 

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

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

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

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

   235 	 * 

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

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

   238 	 * 

   239 	 * @see IsDefined

   240 	 * @see TAttribute::EResolutionTwips

   241 	 * 

   242 	 * @param aSizeInTwips Receives size in twips.

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

   244 	 */

   245 	inline TBool GetResolutionTwips(TSize& aSize) const;

   246 protected:

   247 	/**

   248 	 * Constructor for passing through a version already supplied.

   249 	 * 

   250 	 * Generally used internally in the constructor chain.

   251 	 * 

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

   253 	 * through the classes.

   254 	 */

   255 	inline TDisplayConfiguration1(TInt aVersion);

   256 	/**

   257 	 * Compares two TDisplayConfiguration1 instances.

   258 	 * 

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

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

   261 	 * same. Undefined attributes are not compared.

   262 	 * 

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

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

   265 	 */

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

   267 private:

   268 	//Intentionally blocked functionality

   269 	inline TDisplayConfiguration1(const TDisplayConfiguration1& aDisplayConfiguration1);

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

   271 

   272 private:

   273 	//Streamable data members

   274 	TSize 	iResolution;

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

   276 	TSize	iTwipsSize;

   277 	};

   278 

   279 /**

   280  * The display configuration class for general use.

   281  * 

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

   283  * If so, also update the typedef TDisplayConfigurationTop.

   284  * 

   285  */

   286 class TDisplayConfiguration : public TDisplayConfiguration1

   287 	{

   288 private:	

   289 	typedef TDisplayConfiguration1	TDisplayConfigurationTop;

   290 public:

   291 	/**

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

   293 	 */

   294 	inline TDisplayConfiguration():	TDisplayConfigurationTop()

   295 		{}

   296 	/**

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

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

   299 	 * object will be set as undefined.

   300 	 * 

   301 	 * @param aDisplayConfiguration Configuration to be copied.

   302 	 */

   303 	inline TDisplayConfiguration(const TDisplayConfiguration& aDisplayConfiguration);

   304 	/**

   305 	 * Constructs a display configuration for a particular version.

   306 	 * 

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

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

   309 	 * to represent an object compatible with that.

   310 	 * 

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

   312 	 * of TDisplayConfiguration.

   313 	 * 

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

   315 	 */

   316 	inline TDisplayConfiguration(TInt aVersion);

   317 	/**

   318 	 * Compares two TDisplayConfiguration instances.

   319 	 * 

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

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

   322 	 * 

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

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

   325 	 */

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

   327 		{

   328 		return TDisplayConfiguration1::operator==(aRhs);

   329 		}

   330 private:

   331 	//Intentionally blocked functionality

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

   333 	};

   334 

   335 #include <graphics/displayconfiguration.inl>

   336 #endif // _DISPLAYCONFIGURATION__INCLUDED_