TextStyleDefinition

#include <bb/cascades/TextStyleDefinition>

Used to define style sets for sets of text nodes in an application.

This class is useful if you need to modify the look and feel of the text displayed in your application. Instead of specifying each style characteristic for each individual control, you can create a TextStyleDefinition and apply it to each of the controls.

The TextStyleDefinition constructs a text style based on a base text style in combination with its own parameters. All parameters that are set to non default values will be used to override the base style. The resulting text style can be queried using the style property.

When creating a TextStyleDefinition you can base the style off of one of the existing system defaults specified in SystemDefaults::TextStyle. For example, if you're creating a custom title, you might want to base the TextStyleDefinition off of SystemDefaults::TextStyles::titleText(). Then you would override the individual properties that you want to change with style properties of your own. The resulting text style can be queried using the style property.

This example demonstrates how to create a text style based on SystemDefaults::TextStyle::bodyText(), with the fontWeight property being overridden to bold and fontSize being overridden to "small".

TextStyleDefinition *pTSD = new TextStyleDefinition();
pTSD->setBase(SystemDefaults::TextStyles::bodyText());
pTSD->setWeight(FontWeight::Bold);
pTSD->setFontSize(FontSize::Small);
TextStyle boldBodyText = pTSD->style();
In QML: 
import bb.cascades 1.0

Container {

  attachedObjects: [
    TextStyleDefinition
    {
      id: tsd
      base: SystemDefaults.TextStyles.BodyText
      fontWeight: FontWeight.Bold
      fontSize: FontSize.Small
    }
  ]

  Label{
    id: label
    text: "Hello, world!"
    textStyle
    {
      base: tsd.style
    }
  }

}

Since:

BlackBerry 10.0.0

Inheritance

bb::cascades::BaseObject
bb::cascades::TextStyleDefinition

QML properties

base: bb::cascades::TextStyle
style: bb::cascades::TextStyle [read-only]
fontFamily: QString
fontStyle: bb::cascades::FontStyle::Type
fontWeight: bb::cascades::FontWeight::Type
color: bb::cascades::Color | bb::cascades::ColorPaint
lineHeight: float
fontSizeValue: float
fontSize: bb::cascades::FontSize::Type
textAlign: bb::cascades::TextAlign::Type
objectName: QStringInherited
parent: QObject [read-only]Inherited

Public Functions Index

TextStyleDefinition ()
virtual ~TextStyleDefinition ()
bb::cascades::TextStylebase ()
bb::cascades::TextStylestyle ()
voidsetBase (const bb::cascades::TextStyle &base)
Q_INVOKABLE voidresetBase ()
Q_SLOT voidsetFontFamily (const QString &fontFamily)
QStringfontFamily () const
Q_INVOKABLE voidresetFontFamily ()
Q_SLOT voidsetFontStyle (bb::cascades::FontStyle::Type fontStyle)
bb::cascades::FontStyle::TypefontStyle () const
Q_INVOKABLE voidresetFontStyle ()
Q_SLOT voidsetFontWeight (bb::cascades::FontWeight::Type fontWeight)
bb::cascades::FontWeight::TypefontWeight () const
Q_INVOKABLE voidresetFontWeight ()
Q_SLOT voidsetColor (const bb::cascades::ColorPaint &color)
Q_SLOT voidsetColor (const QVariant &color)
QVariantcolor ()
Q_INVOKABLE voidresetColor ()
Q_SLOT voidsetLineHeight (float lineHeight)
floatlineHeight () const
Q_INVOKABLE voidresetLineHeight ()
Q_SLOT voidsetFontSizeValue (float size)
floatfontSizeValue () const
Q_INVOKABLE voidresetFontSizeValue ()
Q_SLOT voidsetFontSize (bb::cascades::FontSize::Type size)
bb::cascades::FontSize::TypefontSize () const
Q_INVOKABLE voidresetFontSize ()
Q_SLOT voidsetTextAlign (bb::cascades::TextAlign::Type alignment)
bb::cascades::TextAlign::TypetextAlign ()
Q_INVOKABLE voidresetTextAlign ()
voidsetObjectName (const QString &name)Inherited
virtual Q_INVOKABLE QStringtoDebugString () const Inherited

Protected Functions Index

Only has inherited protected functions

BaseObject (QObject *parent=0)Inherited

Signals Index

voidstyleChanged ()
voidbaseChanged (const bb::cascades::TextStyle &textStyle)
voidfontFamilyChanged (const QString &fontFamily)
voidfontStyleChanged (bb::cascades::FontStyle::Type newFontStyle)
voidfontWeightChanged (bb::cascades::FontWeight::Type newFontWeight)
voidcolorChanged (const bb::cascades::ColorPaint &color)
voidlineHeightChanged (float lineHeight)
voidfontSizeValueChanged (float fontSizeValue)
voidfontSizeChanged (bb::cascades::FontSize::Type newFontSize)
voidtextAlignChanged (bb::cascades::TextAlign::Type newAlignment)
voidcreationCompleted ()Inherited
voidobjectNameChanged (const QString &objectName)Inherited

Properties

QVariant base

The base text style.

The parameters of this text style will be used if not explicitly overidden.

The default value is a null TextStyle.

Since:

BlackBerry 10.0.0

QVariant style[read-only]

The style constructed by the text style definiton.

The style is constructed from the base text style. All parameters that are set to non default values on the text style definition will override the corresponding parameter from base.

Since:

BlackBerry 10.0.0

QString fontFamily

The font family name.

Example: Helvectica

Default value is QString::null which means that the fontFamily will not be overridden and the value from the base text style will be used instead.

Since:

BlackBerry 10.0.0

bb::cascades::FontStyle::Type fontStyle

The font style.

Font styles are defined in FontStyle, which includes options such as normal and italic.

Default value is FontStyle::Default which means that the fontStyle will not be overridden and the value from the base text style will be used instead.

Since:

BlackBerry 10.0.0

bb::cascades::FontWeight::Type fontWeight

The font weight.

Font weights are defined in FontWeight, which includes options such as W100, W200, ..., W800, W900, normal and bold.

Default value is FontWeight::Default which means that the fontWeight will not be overridden and the value from the base text style will be used instead.

Since:

BlackBerry 10.0.0

QVariant color

The color of the text.

The default value is an invalid color which means that the color will not be overridden and the value from the base text style will be used instead.

Valid value types for this propety are Color and ColorPaint, and an invalid QVariant.

Since:

BlackBerry 10.0.0

float lineHeight

The line height.

This indicates the distance between rows of text. 1.0 is equal to 1 ordinary row height. 1.5 would make the distance between rows 1.5 ordinary row heights.

The default value is -1.0 which means that the lineHeight will not be overridden and the value from the base text style will be used instead.

Since:

BlackBerry 10.0.0

float fontSizeValue

The font size value.

This indicates the font size in post script units or percentage depending on the setting of fontSize. Valid ranges are >= 0.Sizes < 0 will be clamped to 0.

The default value is 0.0 which means that the size will not be overridden and the value from the base text style will be used instead.

If FontSize is set to PercentageValue, size value 100.0 corresponds to the size of the parent style element. If there is no parent element, the size will be in relation to the system default size, which typically matches the logical size Medium. Note, this value will take effect only when font size is set to FontSize::PointValue or FontSize::PercentageValue

Since:

BlackBerry 10.0.0

bb::cascades::FontSize::Type fontSize

The logical font size.

Logical font sizes are defined in FontSize. Logical size will be translated to the actual size according to system font settings.

E.g. the large size can vary from 12pt to 20pt depending on the font size set in accesibility settings

Default value is FontSize::Default which means that the logical font size will not be overridden, and the value from the base text style will be used instead.

Since:

BlackBerry 10.0.0

bb::cascades::TextAlign::Type textAlign

The horizontal alignment.

Horizontal alignment is defined in TextAlign, which includes options such as center, left, right and justify.

The default value is TextAlign::Default which will result in that the alignment will not be overridden and the value from the base text style will be used instead.

Since:

BlackBerry 10.0.0

QString objectNameInherited

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parentInherited[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

Public Functions

TextStyleDefinition ()

virtual~TextStyleDefinition ()

Destructor.

bb::cascades::TextStyle base ()

Returns the base TextStyle.

Return:

The base TextStyle if set, otherwise a null TextStyle.

Since:

BlackBerry 10.0.0

bb::cascades::TextStyle style ()

Returns the constructed TextStyle.

The style is constructed from a base TextStyle, along with any specified style parameters that are used to override the base style's values.

Return:

The constructed TextStyle.

Since:

BlackBerry 10.0.0

void setBase (

Sets the base TextStyle.

The base text style will be combined with any specified style parameters that are used to override the base style's values.

The resulting TextStyle can be queried via the style property.

Parameters
base

The base text style.
Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetBase ()

Resets the base TextStyle to its default value as a null text style.

Since:

BlackBerry 10.0.0

Q_SLOT void setFontFamily (

Sets the font family name to use for font matching.

Setting this value to anything other than the default value of QString::null will make the TextStyleDefinition construct its style with this value instead of the one provided from base.

Parameters
fontFamily

The font family name.
Since:

BlackBerry 10.0.0

QString fontFamily ()

Returns the font family.

Return:

The font family if set, otherwise an null QString will be returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontFamily ()

Resets the fontFamily to its default value of QString::null.

Since:

BlackBerry 10.0.0

Q_SLOT void setFontStyle (

Sets the font style to use for font matching.

Setting this value to anything other than the default value of FontStyle::Default will make the TextStyleDefinition construct its style with this value instead of the one provided from base.

Parameters
fontStyle

The font style.
Since:

BlackBerry 10.0.0

bb::cascades::FontStyle::Type fontStyle ()

Returns the font style.

Return:

The fontstyle if set otherwise FontStyle::Default will be returned.

See:

bb::cascades::FontStyle

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontStyle ()

Resets the fontStyle to its default value.

Since:

BlackBerry 10.0.0

Q_SLOT void setFontWeight (

Sets the font weight.

Setting this value to anything other than the default value of FontWeight::Default will make the TextStyleDefinition construct its style with this value instead of the one provided from base.

Parameters
fontWeight

The font weight.
Since:

BlackBerry 10.0.0

bb::cascades::FontWeight::Type fontWeight ()

Returns the font weight.

Return:

The weight if set otherwise FontWeight::Default will be returned.

See:

bb::cascades::FontWeight

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontWeight ()

Resets the fontWeight to its default value.

Since:

BlackBerry 10.0.0

Q_SLOT void setColor (

Sets the text color.

Setting this value to anything other than the default value of an invalid color will make the TextStyleDefinition construct it's style with this value instead of the one provided from base.

Parameters
color

The text color.
Since:

BlackBerry 10.0.0

Q_SLOT void setColor (

Sets the text color.

Setting this value to anything other than the default value of an invalid color will make the TextStyleDefinition construct it's style with this value instead of the one provided from base.

The passed QVariant can either be invalid or contain values of type Color or PaintColor or it will be ignored.

Setting an invalid QVariant or a QVariant containing invalid color is equivalent to calling resetColor().

Example: 
styleDef2->setColor(styleDef1->color());
Parameters
color

A QVariant containing the color to use or an invalid QVariant.
Since:

BlackBerry 10.0.0

QVariant color ()

Returns the text color.

The returned QVariant will be either invalid or contain values of type Color or ColorPaint.

Use QVariant::canConvert<Type T>() to find actual type, and then QVariant::value<Type T>() to get the value.

For example: 
QVariant v = style->color();
if (v.canConvert<Color>()) {
  Color c = v.value<Color>();
  // use the color
} else if (v.canConvert<ColorPaint>()) {
  ColorPaint cp = v.value<ColorPaint>();
  // must be a system default paint
}
Return:

The text color if set, otherwise an invalid color will be returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetColor ()

Resets the color to its default value as an invalid Color.

Since:

BlackBerry 10.0.0

Q_SLOT void setLineHeight (
  • floatlineHeight)

Sets the line height.

Setting this value to anything other than the default value of 0.0 will make the TextStyleDefinition construct its style with this value instead of the one provided from base.

Parameters
lineHeight

The line height.
Since:

BlackBerry 10.0.0

float lineHeight ()

Returns the line height.

The default value is 0.0.

Return:

Line height if set. If not set the default value will be returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetLineHeight ()

Resets the lineHeight to its default value of -1.0.

Since:

BlackBerry 10.0.0

Q_SLOT void setFontSizeValue (
  • floatsize)

Sets the font size value.

Setting this value to anything other than the default value of 0.0 will make the TextStyleDefinition construct its style with this value instead of the one provided from base.

If FontSize is set to PercentageValue, size value 100.0 corresponds to the locial size of the parent style element. If there is no parent element, the size will be in relation to the system default size, which typically matches the logical size Medium.

Note, this value will take effect only when font size is set to FontSize::PointValue or FontSize::PercentageValue

Parameters
size

The font size value.
Since:

BlackBerry 10.0.0

float fontSizeValue ()

Returns the font size value.

The default value is 0.0.

Return:

Font size value if set. If not set the default value will be returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontSizeValue ()

Resets the fontSizeValue to its default value of 0.0.

Since:

BlackBerry 10.0.0

Q_SLOT void setFontSize (

Sets the logical font size.

Parameters
size

The logical font size.
Since:

BlackBerry 10.0.0

bb::cascades::FontSize::Type fontSize ()

Returns the logical font size.

Return:

The logical font size if set.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontSize ()

Resets the logical size to its default value.

Since:

BlackBerry 10.0.0

Q_SLOT void setTextAlign (

Sets the horizontal text alignment.

Setting this value to anything other than the default value of TextAlign::Default will make the TextStyleDefinition construct its style with this value instead of the one provided from base.

Parameters
alignment

The horizontal text alignment.
Since:

BlackBerry 10.0.0

bb::cascades::TextAlign::Type textAlign ()

Returns the horizontal text alignment.

Return:

The text alignment if set, otherwise bb::cascades::TextAlign::Default will be returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetTextAlign ()

Resets textAlign to its default value.

Since:

BlackBerry 10.0.0

void setObjectName (Inherited

Sets the objectName property.

Parameters
name

The new name for the object.
Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()Inherited

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (Inherited

Constructs an instance of BaseObject's subclass.

Parameters
parent

An optional parent, defaults to 0.
Since:

BlackBerry 10.0.0

Signals

void styleChanged ()

Emitted when the style has changed.

This will will happen when any of the parameters of the TextStyleDefinition has changed.

Since:

BlackBerry 10.0.0

void baseChanged (

Emitted when the base TextStyle has changed.

Parameters
textStyle

The new base TextStyle.
Since:

BlackBerry 10.0.0

void fontFamilyChanged (

Emitted when fontFamily has been changed.

Parameters
fontFamily

The new font family name.
Since:

BlackBerry 10.0.0

void fontStyleChanged (

Emitted when fontStyle has been changed.

Parameters
newFontStyle

The new font style.
Since:

BlackBerry 10.0.0

void fontWeightChanged (

Emitted when fontWeight has been changed.

Parameters
newFontWeight

The new font weight.
Since:

BlackBerry 10.0.0

void colorChanged (

Emitted when color has been changed.

Parameters
color

The new color.
Since:

BlackBerry 10.0.0

void lineHeightChanged (
  • floatlineHeight)

Emitted when lineHeight has been changed.

Parameters
lineHeight

The new line height.
Since:

BlackBerry 10.0.0

void fontSizeValueChanged (
  • floatfontSizeValue)

Emitted when font size value has been changed.

Parameters
fontSizeValue

The new font size value.
Since:

BlackBerry 10.0.0

void fontSizeChanged (

Emitted when logical size has been changed.

Parameters
newFontSize

The new logical font size.
Since:

BlackBerry 10.0.0

void textAlignChanged (

Emitted when alignment has been changed.

Parameters
newAlignment

The new alignment.
Since:

BlackBerry 10.0.0

void creationCompleted ()Inherited

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class. This signal is emitted to indicate that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0