TextStyleDefinition

Since: BlackBerry 10.0.0

#include <bb/cascades/TextStyleDefinition>

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

The TextStyleDefinition class is used to modify the look and feel of the text displayed in your app. Instead of specifying each style characteristic for each individual control, you can create a TextStyleDefinition and apply it to all of the text controls in your app.

The TextStyleDefinition class 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 are used to override the base text style. The resulting text style can be queried using the style property.

When you create a TextStyleDefinition, you can base the style on one of the existing system defaults specified in SystemDefaults::TextStyle. For example, if you create a custom title, you can base the TextStyleDefinition on the SystemDefaults::TextStyles::titleText() text style. You can then override the individual style properties with style properties of your own. The resulting text style can be queried using the style property.

The following C++ example shows you 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->setFontWeight(FontWeight::Bold);
pTSD->setFontSize(FontSize::Small);
TextStyle boldBodyText = pTSD->style();
Here's how to do the same thing 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
    }
  }

}


Overview

Inheritance

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

QML properties

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

Public Functions Index

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

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

Properties

QVariant base

The base text style.

Since:

BlackBerry 10.0.0

QVariant color

The color of the text.

The default value is an invalid color. If the color property is not specified, the value from the base text style is used.

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

Since:

BlackBerry 10.0.0

QString fontFamily

The font family name.

Example: Helvectica

The default value is QString::null. If the fontFamily property is not specified, the value from the base text style is used.

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

The default value is FontSize::Default. If the fontSize property is not specified, the value from the base text style is used.

Since:

BlackBerry 10.0.0

float fontSizeValue

The font size value.

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

The default value is 0.0. If the fontSizeValue is not specified, the value from the base text style is used.

If FontSize is set to PercentageValue, the size value 100.0 corresponds to the size of the parent style element. If there is no parent element, the size is in relation to the system default size, which typically matches the Medium logical size. 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::FontStyle::Type fontStyle

The font style.

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

The default value is FontStyle::Default. If the fontStyle property is not specified, the value from the base text style is used.

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.

The default value is FontWeight::Default. If the fontWeight property is not specified, the value from the base text style is used.

Since:

BlackBerry 10.0.0

float lineHeight

The line height.

This property indicates the distance between rows of text, with 1.0 being equal to 1 standard row height. A lineHeight of 1.5 sets the distance between rows to the height of 1.5 standard rows.

The default value is -1.0. If the lineHeight property is not specified, the value from the base text style is used.

Since:

BlackBerry 10.0.0

QDeclarativeListProperty< bb::cascades::AbstractTextStyleRule > rules[read-only]

A list of text style rules that define the properties for custom fonts.

Since:

BlackBerry 10.2.0

QVariant style[read-only]

The style constructed by the text style definition.

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

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. If the textAlign property is not specified, the value from the base text style is used.

Since:

BlackBerry 10.0.0

QString objectNameInherited

This property is overridden from QObject.

See also:

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

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 is returned.

Since:

BlackBerry 10.0.0

QString fontFamily ()

Returns the font family.

Return:

The font family if set, otherwise a null QString is returned.

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

float fontSizeValue ()

Returns the font size value.

The default value is 0.0.

Return:

Font size value if set, otherwise the default value is returned.

Since:

BlackBerry 10.0.0

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

Returns the font style.

Return:

The fontstyle if set, otherwise FontStyle::Default is returned.

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.

Since:

BlackBerry 10.0.0

float lineHeight ()

Returns the line height.

The default value is 0.0.

Return:

The line height if set, otherwise the default value is returned.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetBase ()

Resets the base TextStyle to its default value of null.

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_INVOKABLE void resetFontFamily ()

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

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontSize ()

Resets the logical size to its default value.

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_INVOKABLE void resetFontStyle ()

Resets the fontStyle to its default value.

Since:

BlackBerry 10.0.0

Q_INVOKABLE void resetFontWeight ()

Resets the fontWeight to its default value.

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_INVOKABLE void resetTextAlign ()

Resets textAlign to its default value.

Since:

BlackBerry 10.0.0

void setBase (

Sets the base TextStyle.

The base text style is combined with any specified style parameters that are used to override the values of the base text style.

The resulting TextStyle can be queried via the style property.

Parameters
base

The base text style.

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 the base text style.

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 the base text style.

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

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 the base text style.

Parameters
fontFamily

The font family name.

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

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 the base text style.

If FontSize is set to PercentageValue, size value 100.0 corresponds to the logical size of the parent style element. If there is no parent element, the size is in relation to the system default size, which typically matches the logical size of 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

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 the base text style.

Parameters
fontStyle

The font style.

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 the base text style.

Parameters
fontWeight

The font weight.

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 the base text style.

Parameters
lineHeight

The line height.

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 the base text style.

Parameters
alignment

The horizontal text alignment.

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 values of the base text style.

Return:

The constructed TextStyle.

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 is returned.

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 baseChanged (

Emitted when the base TextStyle has changed.

Parameters
textStyle

The new base TextStyle.

Since:

BlackBerry 10.0.0

void colorChanged (

Emitted when color has been changed.

Parameters
color

The new color.

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 fontSizeChanged (

Emitted when logical size has been changed.

Parameters
newFontSize

The new logical font size.

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 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 lineHeightChanged (
  • floatlineHeight)

Emitted when lineHeight has been changed.

Parameters
lineHeight

The new line height.

Since:

BlackBerry 10.0.0

void styleChanged ()

Emitted when the style has changed.

This is emitted when any of the parameters of the TextStyleDefinition has changed.

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

Emitted 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 indicates 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 also:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (Inherited

This signal is emitted when the objectName property is changed.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



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

comments powered by Disqus