UIConfig

Since: BlackBerry 10.3.0

#include <bb/cascades/UIConfig>

Provides UI configuration properties for a UiObject.

This class provides functions for converting design units into pixels and for exposing the ui palette used within the current context.

Design units are device-independent values that are converted into explicit pixel values optimized for the screen density and resolution of a particular device. Both the du() and sdu() methods convert a design unit into pixels, with the difference being that sdu() rounds the value off to the nearest whole number.


Overview

QML properties

compact: bool [read-only]
dduFactor: float [read-only]
palette: bb::cascades::UIPalette [read-only]

Properties Index

boolcompact [read-only]
floatdduFactor [read-only]
bb::cascades::UIPalettepalette [read-only]

Public Functions Index

Q_INVOKABLE floatddu (float dduValue) const
floatdduFactor () const
Q_INVOKABLE floatdu (float duValue) const
boolisCompact () const
bb::cascades::UIPalette *palette () const
Q_INVOKABLE floatpx (float pxValue) const
Q_INVOKABLE floatsddu (float sdduValue) const
Q_INVOKABLE floatsdu (float sduValue) const

Signals Index

voidcompactChanged (bool isCompact)
voiddduFactorChanged (float dduFactor)
voidpaletteChanged (const bb::cascades::UIPalette *palette)

Properties

bool compact[read-only]

Specifies whether the UI should use the compact mode concept to define the appearance of visual components.

Since:

BlackBerry 10.3.0

float dduFactor[read-only]

A scale factor that depends on the information density context.

The dynamic design factor is a modifier with the base of 1.0 that can be used to adapt UI dimensions when the information density changes. One way that information density changes is through the system font (as the system font becomes smaller, information density rises).

If your app contains a lot of text, you might want other dimensions (margins, padding, and so on) to change as the size of text changes. By updating other dimensions along with the text, your app is always making the best use of the space that's available.

Some controls, such as the StandardListItem, are automatically updated when the information density changes. Other controls require that you update them yourself. To allow your app to update these controls as the information density changes, you can add the information density factor to your existing du() and sdu() methods by multiplying the design unit value with the dduFactor.

Before:
 topPadding: ui.du(11.5)
After:
 topPadding: ui.du(11.5 * ui.dduFactor)

You can also replace your existing du() and sdu() methods with ddu() and sddu() respectively, but this approach requires that you connect to the dduFactorChanged() signal to monitor changes and update the required values.

Since:

BlackBerry 10.3.1

bb::cascades::UIPalette palette[read-only]

Provides access to the palette used in a UIObject.

Since:

BlackBerry 10.3.0

Public Functions

Q_INVOKABLE float ddu (
  • floatdduValue)

Converts a design unit value into a pixel value while taking the dduFactor into account.

The dynamic design unit conversion can be used instead of the du() equivalent. The only difference is that this function also takes the current dduFactor into account.

Parameters
dduValue

The value to convert in design units.

Return:

The converted pixel value.

Since:

BlackBerry 10.3.1

float dduFactor ()

Returns the dduFactor property of the UI context.

Return:

A float stating the information density factor.

Since:

BlackBerry 10.3.1

Q_INVOKABLE float du (
  • floatduValue)

Converts a design unit value into a pixel value.

Parameters
duValue

The value to convert in design units.

Return:

The converted pixel value.

Since:

BlackBerry 10.3.0

bool isCompact ()

Returns the isCompact property of the UI context.

Return:

A bool indicating whether the UI should be shown in compact mode.

Since:

BlackBerry 10.3.0

bb::cascades::UIPalette * palette ()

Retrieves the ui palette.

Return:

The UIPalette used by the UIObject.

Since:

BlackBerry 10.3.0

Q_INVOKABLE float px (
  • floatpxValue)

Converts a pixel value to a pixel value.

This method doesn't change the value of the measurement. It's simply used as a way to explicitly show that the value is a pixel value.

Note:

In future versions of Cascades, API changes may require that pixel values are specified explicitly by using this method. Using this API reduces the effort to adapt to those changes, and your code may be source compatible with future versions.

Parameters
pxValue

The value to convert in pixels.

Return:

The pixel value.

Since:

BlackBerry 10.3.0

Q_INVOKABLE float sddu (
  • floatsdduValue)

Converts a design unit value into a pixel value while taking the dduFactor into account and rounding the result to the nearest whole pixel.

The dynamic design unit conversion can be used instead of the sdu() equivalent. The only difference is that this function also takes the current dduFactor into account.

Parameters
sdduValue

The value to convert in design units.

Return:

The converted pixel value, rounded to the nearest whole pixel.

Since:

BlackBerry 10.3.1

Q_INVOKABLE float sdu (
  • floatsduValue)

Converts a design unit value into a pixel value, while rounding to the nearest whole pixel.

Parameters
sduValue

The value to convert in design units.

Return:

The converted pixel value, rounded to the nearest whole pixel.

Since:

BlackBerry 10.3.0

Signals

void compactChanged (
  • boolisCompact)

Emitted after the isCompact of the UI has changed.

Parameters
isCompact

The new compact mode for the UI.

Since:

BlackBerry 10.3.0

void dduFactorChanged (
  • floatdduFactor)

Emitted after the dduFactor of the UI has changed.

Parameters
dduFactor

The new information density factor for the UI.

Since:

BlackBerry 10.3.1

void paletteChanged (

Emitted when the UIPalette for this UIObject has changed.

Here's how to connect a slot to a button and listen for changes to its ui palette:

Button *button7 = new Button();
Color baseColor = button7->ui()->palette()->primaryBase();
// set primary base color as button color
button7->setColor(baseColor);

// listen to palette changed signal
QObject::connect(button7->ui(),
                 SIGNAL(paletteChanged(const bb::cascades::UIPalette*)),
                 this,
                SLOT(onPaletteChanged(const bb::cascades::UIPalette*)));
// update button color in onPrimaryPaletteChanged() slot ...
Parameters
palette

The new ui palette.

Since:

BlackBerry 10.3.0

Last modified: 2014-09-30



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

comments powered by Disqus