1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicsutils/commongraphicsheaders/inc/displayconfiguration.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,336 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +/**
1.20 + @file
1.21 + @publishedPartner
1.22 + @prototype
1.23 +*/
1.24 +
1.25 +#ifndef _DISPLAYCONFIGURATION__INCLUDED_
1.26 +#define _DISPLAYCONFIGURATION__INCLUDED_
1.27 +
1.28 +#include <babitflags.h>
1.29 +#include <gdi.h>
1.30 +
1.31 +
1.32 +/**
1.33 + * Base class for display configuration hierarchy. Defines common facilities for
1.34 + * all configurations (size, mask, accessibility).
1.35 + */
1.36 +class TDisplayConfigurationBase
1.37 + {
1.38 +public:
1.39 + /**
1.40 + * Enumeration of all of the display configuration attributes. Used in combination
1.41 + * when calling ClearSettings() and SettingsDefined(). If attributes are added,
1.42 + * corresponding enumeration bits must also be added.
1.43 + */
1.44 + enum TAttribute
1.45 + {
1.46 + EResolution = 0,
1.47 + ERotation,
1.48 + EResolutionTwips,
1.49 +
1.50 + EAttributeMax //this should safely work with value 32.
1.51 + };
1.52 + /**
1.53 + * Enumeration of the panics that may be raised when filling the display configuration
1.54 + * These are all contractual input checks and should be avoidable by correctly written callers.
1.55 + *
1.56 + **/
1.57 + enum TPanics
1.58 + {
1.59 + EPanicNegResolution=1, //<Input resolution size has negative ordinate
1.60 + EPanicSemiZeroResolution, //<Input resolution size has only 1 zero ordinate
1.61 + EPanicNonOpaqueBackground, //<Input background color is not opaque
1.62 + EPanicIllegalRotation, //<Input rotation value is out of range
1.63 + EPanicNegTwips, //<Input twips size has negative ordinate
1.64 + EPanicSemiZeroTwips, //<Input twips size has only 1 zero ordinate
1.65 + EPanicConfigInvalid //<Input config version is invalid
1.66 + };
1.67 +public:
1.68 + /**
1.69 + * Reads the version field.
1.70 + *
1.71 + * The version is set automatically in the constructor, or by the GetDisplayConfiguration()
1.72 + * method to indicate the sender's supported structure version. The version reported after
1.73 + * GetDisplayConfiguration() will match the version of one of the hierarchy of TDisplayConfiguration
1.74 + * classes documented in the header, and will never exceed the constructed version.
1.75 + *
1.76 + * @return The defined version of this display configuration instance, in bytes.
1.77 + */
1.78 + inline TInt Version() const;
1.79 + /**
1.80 + * Marks the given attribute as undefined.
1.81 + *
1.82 + * @param aAttribute The attribute to set as undefined.
1.83 + */
1.84 + inline void Clear(TAttribute aAttribute);
1.85 + /**
1.86 + * Marks all attributes as undefined.
1.87 + */
1.88 + inline void ClearAll();
1.89 + /**
1.90 + * Check if a particular member is defined.
1.91 + *
1.92 + * @param aAttribute The attribute to check.
1.93 + * @return ETrue if the attribute is defined, EFalse otherwise.
1.94 + */
1.95 + inline TBool IsDefined(TAttribute aAttribute) const;
1.96 +protected:
1.97 + /**
1.98 + * Constructs a TDisplayConfigurationBase, setting the version to aVersion and all
1.99 + * attributes undefined.
1.100 + *
1.101 + * Generally used internally in the constructor chain.
1.102 + *
1.103 + * @param aVersion The defined size of this object.
1.104 + */
1.105 + inline TDisplayConfigurationBase(TInt aVersion);
1.106 + /**
1.107 + * Internal function for determining whether a given field name is accessible for an
1.108 + * object of the current defined size. This must be used before trying to access any field.
1.109 + *
1.110 + * @param aMember The name of the field to check.
1.111 + * @return ETrue if the field is accessible, EFalse if not.
1.112 + */
1.113 + template <class TMember> TBool MemberAccessible(const TMember& aMember) const
1.114 + {
1.115 + return iVersion>=sizeof(TMember)+TInt(&aMember)-TInt(this);
1.116 + }
1.117 + inline void Panic(TInt aPanicNo); //Should be a TPanic
1.118 + /**
1.119 + * Compares two TDisplayConfigurationBase instances.
1.120 + *
1.121 + * Generally used internally in the comparison chain. The two objects are equivalent if
1.122 + * they have the same version and the same set of attributes defined.
1.123 + *
1.124 + * @param aRhs The object to compare with this object
1.125 + * @return ETrue if the objects are equivalent, EFalse if not.
1.126 + */
1.127 + inline TBool operator == (const TDisplayConfigurationBase& aRhs) const;
1.128 +private:
1.129 + //Intentionally blocked functionality
1.130 + inline TDisplayConfigurationBase();
1.131 + inline TDisplayConfigurationBase(const TDisplayConfigurationBase& aDisplayConfigurationBase);
1.132 + inline TDisplayConfigurationBase operator=(const TDisplayConfigurationBase& aRhs) const;
1.133 +
1.134 +protected:
1.135 + /**
1.136 + * Size to treat this object in bytes. Used to provide backward and forward
1.137 + * compatibility.
1.138 + */
1.139 + TInt iVersion;
1.140 + /**
1.141 + * Indicates which fields in the configuration have defined values. If a field
1.142 + * contains an undefined value, it must be ignored.
1.143 + * See TAttribute for possible bit values.
1.144 + */
1.145 + TBitFlags32 iDefined;
1.146 + };
1.147 +
1.148 +/**
1.149 + * First collection of display configuration settings.
1.150 + *
1.151 + */
1.152 +class TDisplayConfiguration1 : public TDisplayConfigurationBase
1.153 + {
1.154 +public:
1.155 + /** Defines possible rotation values. */
1.156 + enum TRotation
1.157 + {
1.158 + /** Normal orientation is supported. */
1.159 + ERotationNormal,
1.160 + /** A 90 degree rotation is supported. */
1.161 + ERotation90CW,
1.162 + /** A 180 degree rotation is supported. */
1.163 + ERotation180,
1.164 + /** A 270 degree rotation is supported. */
1.165 + ERotation270CW,
1.166 + /** Illegal rotation value. */
1.167 + ERotationIllegal
1.168 + };
1.169 +public:
1.170 + /**
1.171 + * Construct a TDisplayConfiguration1 version object with all attributes undefined.
1.172 + *
1.173 + * This can be used to create a specific version of configuration:
1.174 + * TDisplayConfiguration config(TDisplayConfiguration1.Version());
1.175 + */
1.176 + inline TDisplayConfiguration1();
1.177 + /**
1.178 + * Defines the resolution for the display, in pixels.
1.179 + *
1.180 + * This always corresponds to a rotation of ERotationNormal. If a display can be
1.181 + * disabled, (0,0) can be used to do so. A display can be disabled if the
1.182 + * resolution list includes (0,0).
1.183 + *
1.184 + * @param aSize The resolution in pixels.
1.185 + */
1.186 + inline void SetResolution(const TSize& aSize);
1.187 + /**
1.188 + * Retrieves the resolution, if defined.
1.189 + *
1.190 + * If the resolution is undefined, the parameter is left unchanged. A resolution
1.191 + * of (0,0) means the display is disabled.
1.192 + *
1.193 + * @see IsDefined
1.194 + * @see TAttribute::EResolution
1.195 + *
1.196 + * @param aSize Receives the resolution.
1.197 + */
1.198 + inline TBool GetResolution(TSize& aSize) const;
1.199 + /**
1.200 + * Defines the rotation for the display.
1.201 + *
1.202 + * The values that can be passed in here correspond directly to UI rotation values that can be
1.203 + * passed in to CWsScreenDevice::SetScreenSizeAndRotation(), CWsScreenDevice::SetCurrentRotations()
1.204 + * and so on, although the type is defined locally to avoid undesirable interdependencies in
1.205 + * the interface. Variables of the two types may be freely cast to the other type.
1.206 + *
1.207 + * @see CFbsBitGc::TGraphicsOrientation
1.208 + * @see CWsScreenDevice
1.209 + *
1.210 + * @param aRotation The display rotation.
1.211 + */
1.212 + inline void SetRotation(TRotation);
1.213 + /**
1.214 + * Retrieves the rotation, if defined.
1.215 + *
1.216 + * If the rotation is undefined, the parameter is left unchanged.
1.217 + *
1.218 + * @see IsDefined
1.219 + * @see TAttribute::ERotation
1.220 + *
1.221 + * @param aSize Receives the rotation
1.222 + * @return ETrue if the rotation is defined, EFalse otherwise.
1.223 + */
1.224 + inline TBool GetRotation(TRotation&)const;
1.225 + /**
1.226 + * Defines the physical size of the display resolution area, in twips.
1.227 + *
1.228 + * @param aSizeInTwips Provides the size in twips.
1.229 + */
1.230 + inline void SetResolutionTwips(const TSize& aSize);
1.231 + /**
1.232 + * Retrieves the physical size of the display resolution area, in twips, if defined.
1.233 + *
1.234 + * For displays that have a fixed size, or can report their size, the physical
1.235 + * dimensions corresponding to the current resolution shall be defined. Where the display's
1.236 + * physical size cannot be determined (such as with composite video output, or a projector)
1.237 + * an arbitrary size shall be defined that reflects the pixel aspect ratio.
1.238 + *
1.239 + * If the display is not connected or output is disabled, the physical size shall not
1.240 + * be defined. If the physical size is undefined, the parameter is left unchanged.
1.241 + *
1.242 + * @see IsDefined
1.243 + * @see TAttribute::EResolutionTwips
1.244 + *
1.245 + * @param aSizeInTwips Receives size in twips.
1.246 + * @return ETrue if the size is defined, EFalse if not.
1.247 + */
1.248 + inline TBool GetResolutionTwips(TSize& aSize) const;
1.249 +protected:
1.250 + /**
1.251 + * Constructor for passing through a version already supplied.
1.252 + *
1.253 + * Generally used internally in the constructor chain.
1.254 + *
1.255 + * @param aVersion - Version of the class already calculated and being passed up
1.256 + * through the classes.
1.257 + */
1.258 + inline TDisplayConfiguration1(TInt aVersion);
1.259 + /**
1.260 + * Compares two TDisplayConfiguration1 instances.
1.261 + *
1.262 + * Generally used internally in the comparison chain. The two objects are equivalent if they have
1.263 + * the same version, the same set of attributes defined and all the defined attributes are the
1.264 + * same. Undefined attributes are not compared.
1.265 + *
1.266 + * @param aRhs The object to compare with this object.
1.267 + * @return ETrue if the objects are equivalent, EFalse if not.
1.268 + */
1.269 + inline TBool operator == (const TDisplayConfiguration1& aRhs)const;
1.270 +private:
1.271 + //Intentionally blocked functionality
1.272 + inline TDisplayConfiguration1(const TDisplayConfiguration1& aDisplayConfiguration1);
1.273 + inline TDisplayConfiguration1 operator=(const TDisplayConfiguration1& aRhs) const;
1.274 +
1.275 +private:
1.276 + //Streamable data members
1.277 + TSize iResolution;
1.278 + TInt iRotation; //0,1,2,3
1.279 + TSize iTwipsSize;
1.280 + };
1.281 +
1.282 +/**
1.283 + * The display configuration class for general use.
1.284 + *
1.285 + * May be extended by adding a chain of classes between this and TDisplayConfiguration1.
1.286 + * If so, also update the typedef TDisplayConfigurationTop.
1.287 + *
1.288 + */
1.289 +class TDisplayConfiguration : public TDisplayConfiguration1
1.290 + {
1.291 +private:
1.292 + typedef TDisplayConfiguration1 TDisplayConfigurationTop;
1.293 +public:
1.294 + /**
1.295 + * Construct a configuration of the default version with all attributes undefined.
1.296 + */
1.297 + inline TDisplayConfiguration(): TDisplayConfigurationTop()
1.298 + {}
1.299 + /**
1.300 + * Copy constructor. This constructor will read the version field of the source and target
1.301 + * objects and only copy the common set of fields. Any remaining fields in the target
1.302 + * object will be set as undefined.
1.303 + *
1.304 + * @param aDisplayConfiguration Configuration to be copied.
1.305 + */
1.306 + inline TDisplayConfiguration(const TDisplayConfiguration& aDisplayConfiguration);
1.307 + /**
1.308 + * Constructs a display configuration for a particular version.
1.309 + *
1.310 + * This constructor is designed to be used with the value returned by
1.311 + * MDisplayControlBase::PreferredDisplayConfigurationVersion(), and initializes the members
1.312 + * to represent an object compatible with that.
1.313 + *
1.314 + * The version used is the earlier of aVersion and the compile time version
1.315 + * of TDisplayConfiguration.
1.316 + *
1.317 + * @param aVersion Caller-defined maximum version of configuration.
1.318 + */
1.319 + inline TDisplayConfiguration(TInt aVersion);
1.320 + /**
1.321 + * Compares two TDisplayConfiguration instances.
1.322 + *
1.323 + * The two objects are equivalent if they have the same version, the same set of attributes defined
1.324 + * and all the defined attributes are the same. Undefined attributes are not compared.
1.325 + *
1.326 + * @param aRhs The object to compare with this object.
1.327 + * @return ETrue if the objects are equivalent, EFalse if not.
1.328 + */
1.329 + inline TBool operator == (const TDisplayConfiguration& aRhs)const
1.330 + {
1.331 + return TDisplayConfiguration1::operator==(aRhs);
1.332 + }
1.333 +private:
1.334 + //Intentionally blocked functionality
1.335 + inline TDisplayConfiguration operator=(const TDisplayConfiguration& aRhs) const;
1.336 + };
1.337 +
1.338 +#include <graphics/displayconfiguration.inl>
1.339 +#endif // _DISPLAYCONFIGURATION__INCLUDED_