Qt Reference Documentation

QML Screen Element

Symbian: Provides access to the screen properties such as resolution, dot density, and orientation. More...

This element was introduced in Qt Quick Components 1.0.

Properties

Detailed Description

A screen is exposed as a context property named screen. It is not possible to instantiate a Screen object in QML, but the screen must be accessed through the context property.

Property Documentation

allowedOrientations : enumeration

The allowed orientations for the screen. The property accepts any combination of Screen::Orientations flags. The flags are as follows:

  • Screen.Default - the default set of allowed orientations; may depend on hardware
  • Screen.Portrait - the portrait mode is allowed
  • Screen.Landscape - the landscape mode is allowed
  • Screen.PortraitInverted - the inverted portrait mode is allowed
  • Screen.LandscapeInverted - the inverted landscape mode is allowed
  • Screen.All - the convenience enumeration for allowing all possible orientation modes

You can use the property to lock the screen to a certain orientation. The following code example locks the screen to the landscape orientation.

 function lockToLandscape() {
     screen.allowedOrientation = Screen.Landscape
 }

You can also use the property to let the orientation change freely according to the physical orientation of the device. The following code example illustrates how enable this kind of behavior.

 function setAutomaticOrientation() {
     screen.allowedOrientation = Screen.All
     // equals to:
     // screen.allowedOrientation = Screen.Portrait | Screen.Landscape |
     //                             Screen.PortraitInverted | Screen.LandscapeInverted
 }

Note: Normally orientation is controlled by the Page component. You should use the allowedOrientations property only if Page is not used at all, or if Page::orientationLock property is set to PageOrientation.Manual.

See also currentOrientation and Page::orientationLock.


currentOrientation : enumeration

The current orientation of the screen. The possible values are:

  • Screen.Portrait - the width of the screen is less than or equal to the height
  • Screen.Landscape - the width of the screen is greater than the height
  • Screen.PortraitInverted - the width of the screen is less than or equal to the height, and the screen is considered to be upside-down
  • Screen.LandscapeInverted - the width of the screen is greater than the height, and the screen is considered to be upside-down

The values may depend on hardware. For instance, some devices might support only one orientation, or some devices might not support inverted orientations.

Note: currentOrientation is a read-only property. Use allowedProperties or Page::orientationLock to set the orientation.

See also allowedOrientations and Page::orientationLock.


density : enumeration

The screen classification based on the screen's dot density in dpi's (dots per inch). The density categories are as follows:

  • Screen.Low - a low-dpi screen
  • Screen.Medium - a medium-dpi screen
  • Screen.High - a high-dpi screen
  • Screen.ExtraHigh - an extra-high-dpi screen

The diagram below illustrates the density categories with relation to the ranges of the screen's dot density in dpi's.

See also displayCategory.


displayCategory : enumeration

The screen classification based on the physical size of the screen. The physical size is the length of the screen's diagonal. The display categories are as follows:

  • Screen.Small - a small screen
  • Screen.Normal - a normal screen
  • Screen.Large - a large screen
  • Screen.ExtraLarge - an extra large screen

The diagram below illustrates the display categories with relation to the ranges of the screen's diagonal length.

The following example illustrates how you can use this property to select different top level layouts for different display categories:

 Page {
     Loader {
         source: (screen.displayCategory == Screen.Small) ? "SmallView.qml" : "NormalView.qml"
         ...
     }
 }

See also density.


displayHeight : int

The native height of the display, that is, the height of the screen when rotation returns zero.

See also height and rotation.


displayWidth : int

The native width of the display, that is, the width of the screen when rotation returns zero.

See also width and rotation.


dpi : qreal

The screen's dot density in dpi's (dots per inch). It is assumed that the pixels are square, so in theory the value is not necessarily fully accurate.


height : int

The screen height in pixels. The value changes when the orientation changes: in the portrait mode the height is bigger than width and in the landscape mode vice versa.

See also displayHeight.


rotation : int

The rotation angle of the screen's content. The angle is measured anti-clockwise in relation to the device's native orientation. The native orientation is the position where the rotation method's return value is zero.

The value is always non-negative.

See also displayWidth and displayHeight.


width : int

The screen width in pixels. The value changes when the orientation changes: in the portrait mode the width is smaller than the height and in the landscape mode vice versa.

See also displayWidth.