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]

QML signals

onCompactChanged	: {}
onDduFactorChanged	: {}
onPaletteChanged	: {}

Properties Index

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

Public Functions Index

Q_INVOKABLE float	ddu (float dduValue) const
float	dduFactor () const
Q_INVOKABLE float	du (float duValue) const
bool	isCompact () const
bb::cascades::UIPalette *	palette () const
Q_INVOKABLE float	px (float pxValue) const
Q_INVOKABLE float	sddu (float sdduValue) const
Q_INVOKABLE float	sdu (float sduValue) const

Signals Index

void	compactChanged (bool isCompact)
void	dduFactorChanged (float dduFactor)
void	paletteChanged (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 (
const bb::cascades::UIPalette *palette)

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

UIConfig

Overview

QML properties

QML signals

Properties Index

Public Functions Index

Signals Index

Properties

bool compact[read-only]

float dduFactor[read-only]

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

Public Functions

Q_INVOKABLE float ddu (
floatdduValue)

float dduFactor ()

Q_INVOKABLE float du (
floatduValue)

bool isCompact ()

bb::cascades::UIPalette * palette ()

Q_INVOKABLE float px (
floatpxValue)

Q_INVOKABLE float sddu (
floatsdduValue)

Q_INVOKABLE float sdu (
floatsduValue)

Signals

void compactChanged (
boolisCompact)

void dduFactorChanged (
floatdduFactor)

void paletteChanged (
const bb::cascades::UIPalette *palette)

1. Download the tools

2. Try the sample apps

3. Educate yourself

4. Start developing

UIConfig

Overview

QML properties

QML signals

Properties Index

Public Functions Index

Signals Index

Properties

bool compact[read-only]

float dduFactor[read-only]

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

Public Functions

Q_INVOKABLE float ddu (floatdduValue)

float dduFactor ()

Q_INVOKABLE float du (floatduValue)

bool isCompact ()

bb::cascades::UIPalette * palette ()

Q_INVOKABLE float px (floatpxValue)

Q_INVOKABLE float sddu (floatsdduValue)

Q_INVOKABLE float sdu (floatsduValue)

Signals

void compactChanged (boolisCompact)

void dduFactorChanged (floatdduFactor)

void paletteChanged (const bb::cascades::UIPalette *palette)

1. Download the tools

2. Try the sample apps

3. Educate yourself

4. Start developing

Q_INVOKABLE float ddu (
floatdduValue)

Q_INVOKABLE float du (
floatduValue)

Q_INVOKABLE float px (
floatpxValue)

Q_INVOKABLE float sddu (
floatsdduValue)

Q_INVOKABLE float sdu (
floatsduValue)

void compactChanged (
boolisCompact)

void dduFactorChanged (
floatdduFactor)

void paletteChanged (
const bb::cascades::UIPalette *palette)