QScreenInformation Class Reference
[QtBaseModule]

Detailed Description

The QScreenInformation class provides additional information about screens beyond that from QDesktopWidget.

Some devices have multiple output screens. For example, a device might have a primary LCD screen plus a TV composite video output socket. The TV output can display what is on the LCD screen (known as "cloning"), or it can provide a separate framebuffer for displaying a second image that is different from that on the LCD.

The following code finds the first screen of type Television and then directs that it be a clone of the primary screen:

    QScreenInformation tv(QScreenInformation::Television);
    tv.setClonedScreen(QApplication::desktop()->primaryScreen());

The television screen can be separated from the LCD for separate display as follows:

    tv.setClonedScreen(-1);

When the tv object is deleted, or the application exits, the clone state will revert to its default setting.

Some devices have multiple screens that can be visible at the same time, overlaid on each other. Transparency colors are used to "poke holes" in one layer to allow lower layers to be partially or completely revealed.

Overlay screens are marked with the type QScreenInformation::Overlay. Such screens will typically return a list of layers from supportedLayers() that indicates the layer numbers that can be set for the overlay.

Layer numbers are always relative to zero, which indicates the main GUI layer. Layer numbers less than zero indicate a layer that is below the main GUI layer and numbers greater than zero indicate a layer that is above the main GUI layer.

When a client application calls setLayer(), a request is sent to the screen's QScreenInformationProvider object to change the layer number and make the screen visible. When the QScreenInformation object is deleted, or the application exits, the overlay is made invisible and reverted to its default layer ordering.

See also QScreenInformationProvider.

Member Type Documentation

enum QScreenInformation::Type

This enum defines the type of a screen.

Member Function Documentation

QScreenInformation::QScreenInformation ( int screenNumber = -1, QObject * parent = 0 )

Constructs a screen information object for screenNumber and attaches it to parent. If screenNumber is -1, then the primary screen number will be used. Otherwise, if the screenNumber is invalid, then screenNumber() on the constructed object will be -1.

See also screenNumber().

QScreenInformation::QScreenInformation ( QScreenInformation::Type type, QObject * parent = 0 )

Constructs a screen information object for the first screen with the specified type and attaches it to parent. If there is no such screen, then screenNumber() on the constructed object will return -1.

See also screenNumber().

QScreenInformation::~QScreenInformation ()

Destroys this screen information object. If the clone state was changed with setClonedScreen(), then the system will revert the screen to its previous clone mode.

See also setClonedScreen().

void QScreenInformation::changed ()   [signal]

Signal that is emitted when one of isVisible(), type(), clonedScreen(), layer(), supportedLayers(), or transparencyColor() changes.

See also isVisible(), type(), clonedScreen(), layer(), supportedLayers(), and transparencyColor().

int QScreenInformation::clonedScreen () const

Returns the number of the screen that this screen is cloning. The output on the other screen will also be sent to this screen. If the value is -1, then this screen is separated from all the others.

See also setClonedScreen() and changed().

bool QScreenInformation::isVisible () const

Returns true if the screen is expected to be visible to the user at the present time. In the case of Television screens, this may be false if the video cable is not connected.

See also changed().

int QScreenInformation::layer () const

Returns the overlay layer that this screen currently occupies. A value of zero indicates the normal GUI layer. A value less than zero indicates that the overlay is currently below the normal GUI layer. A value greater than zero indicates that the overlay is currently above the normal GUI layer. The default value is zero.

See also setLayer(), supportedLayers(), and transparencyColor().

int QScreenInformation::screenNumber () const

Returns the screen number that this object pertains to. Returns -1 if this object was constructed using an invalid screen number, or it was constructed using a QScreenInformation::Type and there was no screen with that type.

void QScreenInformation::setClonedScreen ( int value )

Sets the number of the screen that this screen is cloning to value. The output on screen value will also be sent to this screen. If value is -1, then this screen should be separated from all others.

When this QScreenInformation object is deleted, the requested clone operation will be reverted. This permits the system to revert the clone state to the default when an application crashes.

The value of clonedScreen() will remain at its previous value until the changed() signal is emitted. The system is free to ignore the request if the requested clone operation is not supported.

See also clonedScreen() and changed().

void QScreenInformation::setLayer ( int value )

Sets the overlay layer for this screen to value. A value of zero indicates the normal GUI layer. A value less than zero indicates that the overlay is currently below the normal GUI layer. A value greater than zero indicates that the overlay is currently above the normal GUI layer.

The layer can only be set to one of the values in the list returned by supportedLayers(). Requests to change the layer to something else will be ignored.

Setting the layer value for an overlay screen will also make it visible. The layer will be made invisible again once the QScreenInformation object is deleted, or the application exits. The isVisible() function can be used to determine if the layer is currently visible.

See also layer(), supportedLayers(), and isVisible().

QList<int> QScreenInformation::supportedLayers () const

Returns the list of overlay layer numbers that are supported for this screen. This can be used by the client application to locate an overlay layer that can be placed above or below the normal GUI layer.

As an example, if the list contains -1, 1, and 2, then the layer can be placed one step below the main GUI layer, or either one or two steps above the main GUI layer.

If the returned list is empty, then the overlay position is fixed at the value returned by layer().

See also layer() and setLayer().

QColor QScreenInformation::transparencyColor () const

Returns the color to fill an area of this screen with to cause layers below this one to be visible through the transparency gaps.

See also layer().

QScreenInformation::Type QScreenInformation::type () const

Returns the type of screen.