DisplayInfo

Since: BlackBerry 10.0.0

#include <bb/device/DisplayInfo>

To link against this class, add the following line to your .pro file: LIBS += -lbbdevice

The DisplayInfo API enables applications to determine properties of the built-in physical displays, and any externally connected physical displays.

These properties include the display size and resolution, the ID and name, and the aspect and attached state.

Two physical displays are explicitly recognized: A primary, built-in display and a secondary, externally connected display. Other internal or external displays that may exist are also supported by this API but only if their screen display IDs are known. An external display can be thought of as a display port on the device. The port may or may not have a physical display attached to it at any given time. The DisplayInfo class not only facilitates accessing display parameters but also enables monitoring the display state, such as when a physical display is attached or disconnected (attachedChanged()).

Note:

A DisplayInfo instance should not be moved to another thread, and must be deleted on the thread in which it was created.

If only the primary display is of interest, instantiate a DisplayInfo object and query it for parameters:
    bb::device::DisplayInfo display;
    qDebug() << "display id is " << display.displayId();
    qDebug() << "display name is " << display.displayName();
    qDebug() << "display size is " << display.pixelSize().width() << ", "
             << display.pixelSize().height();

Example of how to use DisplayInfo in QML (since BlackBerry 10.3.0):

  import bb.cascades 1.3
  import bb.device 1.3
  ...
  Container {
     preferredHeight: displayInfo.pixelSize.height
     preferredWidth: displayInfo.pixelSize.width
  }
  ...
  attachedObjects: [
      DisplayInfo {
          id: displayInfo
      }
  ]
Note:

If you are using QML, you can create a DisplayInfo instance only for the primary display.

The following example shows how to monitor the secondary display:
    int secondaryDisplayId = bb::device::DisplayInfo::secondaryDisplayId();
    qDebug() << "secondary display Id is " << secondaryDisplayId;

    // Construct the DisplayInfo object for the secondary display, and set its parent
    // to some "mainApp" so it will take care of the destruction.
    bb::device::DisplayInfo* secondaryDisplayInfo = new bb::device::DisplayInfo(secondaryDisplayId, &mainApp);

    // The display parameters are interesting if a physical display is attached.
    if ( secondaryDisplayInfo->isAttached() ) {
        qDebug() << "secondary display name is "
                 << secondaryDisplayInfo->displayName();
        qDebug() << "secondary display size is "
                 << secondaryDisplayInfo->pixelSize().width()
                 << ", " << secondaryDisplayInfo->pixelSize().height();
    }

    // Connect the "mainApp's" slot to the secondary display's attachedChanged()
    // signal in order to be notified when the attached state changes.
    QObject::connect(secondaryDisplayInfo, SIGNAL(attachedChanged(bool)),
                     &mainApp, SLOT(secondaryDisplayAttachedChanged(bool)));
Note:

There is a slight performance impact when a DisplayInfo instance is created, thus creating multiple instances of the class is not recommended.


Overview

Properties Index

bb::device::DisplayAspectType::TypeaspectType [read-only]
boolattached [read-only]
booldetachable [read-only]
intdisplayId [read-only]
QStringdisplayName [read-only]
bb::device::DisplayTechnology::TypedisplayTechnology [read-only]
QSizeFphysicalSize [read-only]
QSizepixelSize [read-only]
QSizeFresolution [read-only]
boolwireless [read-only]

Public Functions Index

DisplayInfo (QObject *parent=0)
DisplayInfo (int displayId, QObject *parent=0)
virtual ~DisplayInfo ()
bb::device::DisplayAspectType::TypeaspectType () const
intdisplayId () const
QStringdisplayName () const
bb::device::DisplayTechnology::TypedisplayTechnology () const
boolisAttached () const
boolisDetachable () const
boolisValid () const
boolisWireless () const
QSizeFphysicalSize () const
QSizepixelSize () const
QSizeFresolution () const

Static Public Functions Index

Signals Index

voidattachedChanged (bool attached)
voidpixelSizeChanged (QSize pixelSize)

Properties

bb::device::DisplayAspectType::Type aspectType[read-only]

The aspect of the display describes the shape of the rectangular region that defines the display area.

Since:

BlackBerry 10.0.0

bool attached[read-only]

Indicates if there is a display physically attached to the device for this DisplayInfo instance.

Since:

BlackBerry 10.0.0

bool detachable[read-only]

Indicates if this DisplayInfo supports a physical display that can be attached and disconnected.

Since:

BlackBerry 10.0.0

int displayId[read-only]

The id associated with this DisplayInfo instance, usually either primaryDisplayId(), or secondaryDisplayId().

Since:

BlackBerry 10.0.0

QString displayName[read-only]

The name of the display, as defined by the QNX Screen and Windowing API.

If this DisplayInfo instance represents an external display that has been disconnected, the name is blank.

Since:

BlackBerry 10.0.0

bb::device::DisplayTechnology::Type displayTechnology[read-only]

The type of technology this display is using.

Since:

BlackBerry 10.1.0

QSizeF physicalSize[read-only]

The horizontal and vertical resolution of the display measured in mm.

Since:

BlackBerry 10.0.0

QSize pixelSize[read-only]

The size (width and height) of the display measured in pixels.

Since:

BlackBerry 10.0.0

QSizeF resolution[read-only]

The horizontal and vertical resolution of the display measured in pixels per meter.

Since:

BlackBerry 10.0.0

bool wireless[read-only]

Indicates if this display is connected via a wireless protocol or not.

Since:

BlackBerry 10.2.0

Public Functions

DisplayInfo (

Creates a DisplayInfo object which represents the primary display.

Parameters
parent

If not 0, the supplied parent is responsible for deleting this instance.

Since:

BlackBerry 10.0.0

DisplayInfo (

Creates a DisplayInfo object which represents the display that was specified by its screen display ID.

This corresponds to the display ID described in the QNX Screen and Windowing API. The screen display IDs of the primary and secondary displays can be determined from the static methods primaryDisplayId() and secondaryDisplayId() respectively. Other displays that may exist are also supported if their screen display IDs are known.

Parameters
displayId

The screen display ID of the display.

parent

The QObject to be set as the parent of this instance. If parent is 0, then no parent is set.

Since:

BlackBerry 10.0.0

virtual~DisplayInfo ()

Destructor.

Since:

BlackBerry 10.0.0

bb::device::DisplayAspectType::Type aspectType ()

Provides the display's aspect with respect to the display's natural orientation.

For the device's internal display, this is typically the orientation for which physical the buttons/trackpads, etc., and branding appear to be upright. A display's aspect can be DisplayAspectType::Landscape (for width > height), DisplayAspectType::Portrait (for width < height), or DisplayAspectType::Square (for width = height). If an external display is not attached (see isAttached()), then the aspect is considered to be DisplayAspectType::Square.

Return:

Returns the display's aspect. If this object is invalid, then the return value is undefined.

Since:

BlackBerry 10.0.0

int displayId ()

Provides the ID of the display represented by the DisplayInfo instance.

This corresponds to the display ID described in the QNX Screen and Windowing API.

Return:

Returns the display ID if successful, and -1 otherwise.

Since:

BlackBerry 10.0.0

QString displayName ()

Provides the name of the display represented by the DisplayInfo instance.

This corresponds to the display name described in the QNX Screen and Windowing API. The display name may contain identifying information such as display model and make. If an external display is not attached ( see isAttached() ) then the name is returned is an empty string.

Return:

Returns the display name (truncated to 128 characters) if successful, but if the object is invalid, the return value is undefined.

Since:

BlackBerry 10.0.0

bb::device::DisplayTechnology::Type displayTechnology ()

The type of technology this display is using.

Since:

BlackBerry 10.1.0

bool isAttached ()

Indicates if there is a display physically attached to the device for this DisplayInfo instance.

An external display can be thought of as a display port. The port always exists but a physical display may or may not be attached. The secondary display is an external display. The signal attachedChanged() can be connected to monitor when a physical display is attached and disconnected.

Return:

Returns the true if a physical display is attached to the device, and false otherwise. If this object is invalid, then the return value is undefined.

Since:

BlackBerry 10.0.0

bool isDetachable ()

Indicates if this DisplayInfo supports a physical display that can be attached and disconnected.

This defines an external display.

Return:

Returns true if the DisplayInfo is detachable (hence external), and false otherwise. If this object is invalid, then the return value is undefined.

Since:

BlackBerry 10.0.0

bool isValid ()

Indicates if this DisplayInfo object is valid.

To be valid, the current DisplayInfo object must have been given a recognized display ID in its constructor. * A DisplayInfo object is invalid only if the display ID is not recognized. A DisplayInfo object that represents a detachable display that is not currently attached to the device is still considered to be valid but not attached.

Return:

Returns true if this DisplayInfo object is valid, and false otherwise.

Since:

BlackBerry 10.0.0

bool isWireless ()

Indicates if the current display is connected via a wireless protocol or not.

Return:

true if the connection is wireless, false otherwise.

Since:

BlackBerry 10.2.0

QSizeF physicalSize ()

Provides the size (width and height) of the display measured in millimeters.

The size of the display is always provided with respect to the its natural orientation. For the device's internal display this is typically the orientation for which the physical buttons/trackpads, etc. and branding appear upright. The physical size may not be discoverable for all displays, in which case the width and height are considered to be 0.0. If an external display is not attached (see isAttached()) then the width and height are also considered to be 0.0.

Return:

Returns a QSizeF variable containing the size of the display in millimeters. Returns QSizeF(0.0f,0.0f) if the physical size could not be determined. If this object is invalid, then the return value is undefined.

Since:

BlackBerry 10.0.0

QSize pixelSize ()

Provides the size (width and height) of the display measured in pixels.

The size is always provided with respect to the display's natural orientation. For the device's internal display this is typically the orientation for which the physical buttons/trackpads, etc. and branding appear to be upright. If an external display is not attached (see isAttached()) then the width and height are considered to have values of 0.

It is possible for a display to dynamically change its pixel size, a notification of this pixel size change can be detected by connecting to the pixelSizeChanged() signal.

Return:

Returns the QSize variable containing the size of the display in pixels. Returns QSize(0,0) if the display is not attached. If this object is invalid, then the return value is undefined.

Since:

BlackBerry 10.0.0

QSizeF resolution ()

Provides the horizontal and vertical resolution of the display measured in pixels per meter.

The resolution is always provided with respect to the display's natural orientation. For the device's internal display, this is typically the orientation for which the physical buttons/trackpads, etc., and branding appear to be upright. The resolution is calculated from the ratio of the pixel size to the physical size. Note that the accuracy is limited by the physical size, which is known to the nearest millimeter. Since the physical size may not be detectable for all displays, the resolution cannot always be determined. In such cases, the horizontal and vertical resolution are considered to be 0.0. If an external display is not attached (see isAttached()), then the horizontal and vertical resolution are also considered to be 0.0.

It is possible for a display to dynamically change its pixel size, a notification of this pixel size change can be detected by connecting to the pixelSizeChanged() signal.

Return:

Returns a QSizeF variable containing the resolution of the display in pixels per meter. Returns QSizeF(0.0f,0.0f) if the resolution could not be determined. If this object is invalid, then the return value is undefined.

Since:

BlackBerry 10.0.0

Static Public Functions

int primaryDisplayId ()

Provides the display ID for the primary display.

The primary display is the device's internal display. If there is more than one internal display, the primary display is arbitrarily, but consistently, determined.

Return:

Returns the ID of the primary display if successful, and -1 otherwise.

Since:

BlackBerry 10.0.0

int secondaryDisplayId ()

Provides the display ID for the secondary display.

The secondary display is a display that is external to the device, and connected by a fixed port that exists on the device. If there is more than one external display, then the secondary display is arbitrarily, but consistently, determined.

Return:

Returns the ID of the secondary display if successful, and -1 otherwise.

Since:

BlackBerry 10.0.0

Signals

void attachedChanged (
  • boolattached)

Indicates that the attached state of a physical display has changed.

Parameters
attached

true if a physical display was attached, false if a physical display was not attached.

Since:

BlackBerry 10.0.0

void pixelSizeChanged (

Indicates that the size in pixels of a display that is currently attached has changed.

Parameters
pixelSize

The new size in pixels of the display.

Note:

In QML, only the pixelSize.width and pixelSize.height values can be accessed.

Since:

BlackBerry 10.0.0

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus