Gets the current display configuration.

Note that some entries in the configuration may be undefined if they are unknown, so their validity should either be checked using the accessor return code, or using the IsDefined() function before reading them.

If the display is not connected, the resolution shall be set as undefined. If the display is connected, but disabled, the resolution shall be (0,0). Other attributes may or may not be defined in these states.

TDisplayConfiguration::IsDefined SetConfiguration

Retrieves the set of available display resolutions and supported rotations per resolution.

If a display can be disabled, the list shall include a resolution with the size (0,0). If the display is connected but disabled, the list may also include other supported resolutions. If a display cannot be disabled, the list shall not include (0,0).

The flags field in each entry shall contain the set of rotations supported for the given resolution. The size fields shall always give the resolution with no rotation applied (ERotationNormal), whether or not that rotation is supported.

If the EIsVirtual flags is set, the resolution will be simulated by scaling the output. Scaling quality varies between platfoms, and in general the best quality will be achieved using a physical resolution, where the EIsVirtual flag is not set.

The size in twips may be an estimate for some displays, but can be used to determine the pixel aspect ratio in combination with the size in pixels.

The array shall be reset and the contents replaced by the available resolutions. If an error is returned, the contents of the array shall be undefined.

If no display is connected, the return value shall be KErrDisconnected. When initially connected, the set of resolutions available may be limited, possibly zero, increasing when the display has reported which resolutions it supports.

If the array is not large enough to retrieve the set of resolutions initially, it will be expanded once, or fail with KErrNoMemory. If the number of resolutions increases again after this expansion, the function will fail with KErrOverflow. The caller may re-try the operation.

TResolutionFlags

Returns the number of discrete resolutions that can be retrieved using GetResolutions().

If the display is disconnected, the return value shall be KErrDisconnected. Implicitly, there are no resolutions available. When initially connected, the number of resolutions may be limited, possibly zero, only increasing when the display has reported which resolutions it supports.

Returns the preferred version of the TDisplayConfiguration object.

GetConfiguration() and SetConfiguration() may be passed any version of the TDisplayConfiguration class, as returned by TDisplayConfiguration::Version(). If an earlier version is presented, the implementation will treat later attributes as undefined. If a later structure is presented, then the additional attributes will be ignored.

This method may be used to fine-tune use of the interface, by avoiding the generation of attribute data that will not be used, or by reducing the options presented to users.

Sets the new display configuration.

It is valid to leave settings undefined to let the implementer determine the optimal combination. If a defined setting cannot be achieved, the function shall fail with KErrArgument.

Note that the new configuration will be in use when the function returns, but the change may not appear on screen immediately. It may be deferred due to rendering, composition and display synchronization taking place, but will generally become apparent in the next frame update.

Whether a given configuration is valid or not shall be platform dependent, and may depend on the current screen size mode. Some platforms may restrict resolutions to those listed in the resolution list, while others may be more flexible. Where the resolution does not match a physical resolution from the list, display quality may be reduced.

Setting a resolution of (0,0), if allowed, shall disable display output. Otherwise the pixel resolution shall define the maximum number of pixels that can be rendered using CWindowGc, and this area shall fill the display. Alternative means of rendering may be displayed at the physical resolution, irrespective of the current configuration.