Custom QML components

A custom component is essentially a QML document that defines a single QML component that you can use in an application. During runtime, QML components are interpreted to create objects according to the behaviors defined by the document.

To create a QML component, you create a file called <Name>.qml, where <Name> is the new component name, that begins with an uppercase letter.

import bb.cascades 1.0
 
Container {
    layout: StackLayout {
        orientation: LayoutOrientation.LeftToRight
    }
    CheckBox {
        id: checkBox
        checked: false
    }
    Label {
        id: label
        leftMargin: 10
        text: "Check Box"
    }
}

To use a custom component in an application, you use the component name the way you would with any core component.

Below is an example of how you could use the CustomCheckBox component in another QML document. The component is assigned an id and has layout properties set on it. The CustomCheckBox.qml file must be located in the same directory as this file.

import bb.cascades 1.0
 
Page {
    Container {
        layout: DockLayout {}
        CustomCheckBox {
            id: customCheckBox
            verticalAlignment: VerticalAlignment.Center
            horizontalAlignment: HorizontalAlignment.Center
        }
    }
}

When you create a custom component, you'll often want to be able to expose the properties of its subcomponents. In the example above, CustomCheckBox contains a  CheckBox and a  Label, and each control has its own set of properties. However, in the custom component's current state, these inner properties cannot be accessed from outside the component. And what good is this CustomCheckBox if you can't change its text?

To expose these properties, you must define new properties at the root of your custom component and bind them to the inner properties that you want to expose.

In the example below, the text property for the Label and the checked property for the CheckBox are exposed for CustomCheckBox.

import bb.cascades 1.0
 
Container {
    property string text: label.text
    property bool checked: checkBox.checked   
     
    CheckBox {
        id: checkBox
        checked: false
    }
    Label {
        id: label
        text: "Hello"
    }
}

When you define a new property to expose an inner property, new memory is allocated for the property value. To avoid the allocation of new memory, you can use an alias to point to the inner property instead. Since the new property is of the same type as the aliased property, it's not necessary to specify an explicit type for the new property.

import bb.cascades 1.0
 
Container {
    property alias text: label.text
    property alias checked: checkBox.checked
     
    CheckBox {
        id: checkBox
        checked: false
    }
    Label {
        id: label
        text: "Hello"
    }
}

When you declare a custom property in QML, there's a corresponding value-change signal that's emitted when the property changes. To receive these signals, create a signal handler named using on<PropertyName>Changed syntax. In the example described above, the corresponding signal handlers are called onTextChanged and onCheckedChanged.

Here's how you can capture changes to the properties and log the new values.

import bb.cascades 1.0
 
Container {
    property alias text: label.text
    property alias checked: checkBox.checked
    
    ...

    onTextChanged: {
        console.log("Text has changed to:", text)
    }
    onCheckedChanged: {
        console.log("Checked has changed to:", checked)
    }
}