Customizing a Control

Sometimes you'll want to create a "one-off" look for a specific part of your UI, and use a complete style everywhere else. Perhaps you're happy with the style you're using, but there's a certain button that has some special significance.

The first way to create this button is to simply define it in-place, wherever it is needed. For example, perhaps you're not satisfied with the default style's Button having square corners. To make them rounded, you can override the background item and set the radius property of Rectangle:

import QtQuick 2.15
import QtQuick.Controls 2.15
Rectangle {
    id: root
    color: "#d7d1df"
    readonly property int leftMargin: 10
    readonly property int rowSpacing: 14
    Button {
        id: button
        text: qsTr("A Special Button")
        background: Rectangle {
            implicitWidth: 100
            implicitHeight: 40
            color: button.down ? "#d6d6d6" : "#f6f6f6"
            radius: 4
        }
    }
}

The second way to create the button is good if you plan to use the above button in several places.

For this approach, you have to create a MyButton.qml file with the content

import QtQuick 2.15
import QtQuick.Controls 2.15
Button {
    id: btn
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        color: btn.down ? "#d6d6d6" : "#f6f6f6"
        radius: 4
    }
}

To use the control in your application, refer to it by its filename:

Item{
    Rectangle {
        id: root
        color: "#d7d1df"
        readonly property int leftMargin: 10
        readonly property int rowSpacing: 14
        MyButton {
            id: button
            text: qsTr("A Special Button")
        }
    }
}

The third way to create the button is a bit more structured, both in terms of where the file sits in the file system and how it is used in QML. Create the file as above, but this time name it Button.qml and put it into a subfolder in your project named (for example) controls. To use the control, first import the folder into a namespace:

import QtQuick 2.15
import QtQuick.Controls 2.15
import "controls" as MyControls
Rectangle {
    id: root
    color: "#d7d1df"
    readonly property int leftMargin: 10
    readonly property int rowSpacing: 14
    MyControls.Button {
        id: button
        text: qsTr("A Special Button")
    }
}

As you now have the MyControls namespace, you can name the controls after their actual counterparts in the Qt Quick Controls module. You can repeat this process for any control that you wish to add.

Creating a Custom Style

Qt Quick Ultralite in general follows the Qt Quick approach to defining custom style.

Differences in styling between Qt6 and Qt Quick Ultralite

• Qt Quick Ultralite currently provides only default style.
• Qt Quick Ultralite supports only compile-time styling.
• Default controls without style used to define a styled controls are located in QtQuick.Templates.
• QUL_CONTROLS_STYLE CMake target property must be set to your custom style module's uri
• The style module must be linked to the application CMake target

Default style for controls

To use the default style for the controls, follow these steps:

• Link `Qul::Controls` library to your CMake project (see: target_link_libraries).
• Import QtQuick.Controls in the .qml file.

Custom style for controls

To create a custom style for controls, follow these steps:

• Implement custom components for the style based on QtQuick.Templates.

  The components in the Templates module have useful baseline functionality and make it easier to create components that end up interchangable with the default style controls.

• Create a QML module for the custom style.

  The module consists of .qml/.h source and generated files, a qmldir file and a library. Example:

  MyControlsStyle.a
  MyControlsStyle/
  MyControlsStyle/qmldir
  MyControlsStyle/Button.qml (source file)
  MyControlsStyle/Button.h (generated file from qmltocpp)
  MyControlsStyle/Helper.h (source file)
  MyControlsStyle/Helper.qml (generated file from qmlinterfacegenerator)
  ...

To use a custom style for controls:

• Link your custom style library to the CMake project (see: target_link_libraries).
• Ensure the custom style QML module is found in the include path (see: target_include_directories).

  Note that it should be set to the path containing the module's directories, not to the path containing the qmldir file. If you have <path>/My/Style/qmldir and want the module uri to be My.Style then set the include path to <path>.

• Set the MCU.Config.controlsStyle QmlProject property to your custom style module's uri to make it provide QtQuick.Controls.

  In the above example one would use QUL_CONTROLS_STYLE=My.Style.

• Import QtQuick.Controls in the .qml file.

See `styling` example for reference.