DelegateStyle QML Type | Qt Labs StyleKit | Qt 6.11.2
Description: Defines the visual appearance of an element within a control.

- Qt 6.11
- Qt Labs StyleKit
- QML Types
- DelegateStyle
- Qt 6.11.2 Reference Documentation

# DelegateStyle QML Type

Defines the visual appearance of an element within a control. More...

Import Statement: | `import Qt.labs.StyleKit`
Inherited By: | HandleStyle, IndicatorStyle, and SubIndicatorStyle

- List of all members, including inherited members

## Properties

- alignment : Qt::Alignment
- border : BorderStyle
- bottomLeftRadius : real
- bottomMargin : real
- bottomRightRadius : real
- clip : bool
- color : color
- data : QObject
- delegate : Component
- gradient : Gradient
- image : ImageStyle
- implicitHeight : real
- implicitWidth : real
- leftMargin : real
- margins : real
- minimumWidth : real
- opacity : real
- radius : real
- rightMargin : real
- rotation : real
- scale : real
- shadow : ShadowStyle
- topLeftRadius : real
- topMargin : real
- topRightRadius : real
- visible : bool

## Detailed Description

DelegateStyle describes the visual appearance of a visual element within a ControlStyle, such as its background, indicator, or a sub-element like indicator.foreground. It provides properties for controlling size, color, border, radius, shadow, image, opacity, and more.

Note: Types in Qt.labs modules are not guaranteed to remain compatible in future versions.

See also ControlStyle, ControlStateStyle, and FallbackStyle Reference.

## Property Documentation

### alignment : Qt::Alignment

The alignment of the delegate within its parent. The default value is `Qt.AlignLeft | Qt.AlignVCenter`.

### border : BorderStyle

Grouped property for styling the border of this delegate.

### bottomLeftRadius : real

The bottom-left corner radius. If not set, falls back to radius.

See also radius, topLeftRadius, topRightRadius, and bottomRightRadius.

### bottomMargin : real

The bottom margin of this delegate. If not set, falls back to margins.

See also margins, topMargin, leftMargin, and rightMargin.

### bottomRightRadius : real

The bottom-right corner radius. If not set, falls back to radius.

See also radius, topLeftRadius, topRightRadius, and bottomLeftRadius.

### clip : bool

Whether the delegate clips its contents. The default value is `false`.

### color : color

The fill color of this delegate. The default value is `transparent`.

Unlike a Quick Rectangle, where a gradient replaces the color, StyleKit draws the gradient on top of the color. This means you can use a semi-transparent gradient as an overlay (for example, a subtle shading effect) while the color shows through underneath.

     button {
         background.gradient: Gradient {
             GradientStop { position: 0.0; color: Qt.alpha("black", 0.0)}
             GradientStop { position: 1.0; color: Qt.alpha("black", 0.2)}
         }
         background.color: "lightsteelblue"
         hovered.background.color: Qt.darker("lightsteelblue", 1.1)
         pressed.background.color: Qt.darker("lightsteelblue", 1.2)
     }

See also gradient and opacity.

### data : QObject

An arbitrary object that can be used for passing custom data from the style to a custom delegate component.

This allows you to define custom style properties beyond what the StyleKit API provides. The data object can vary between states and themes, making it possible to style elements in a custom delegate that are not covered by the built-in properties.

The following snippet uses a custom delegate that draws an overlay Text whose color varies depending on the control's state. The delegate inherits StyledItem, which is optional but ensures the rest of the button background is rendered normally.

     component OverlayData : QtObject {
         property color overlayColor
     }

     toolButton {
         background.delegate: StyledItem {
             id: custom
             Text {
                 color: custom.delegateStyle.data.overlayColor
                 font.pixelSize: 30
                 text: "シ"
             }
         }
         background.data: OverlayData {
             overlayColor: "sandybrown"
         }
         hovered.background.data: OverlayData {
             overlayColor: "magenta"
         }
     }

Note: The `data` object is propagated as a whole. Unlike regular style properties, individual properties inside the data object do not propagate separately.

See also delegate.

### delegate : Component

The delegate used to render the DelegateStyle in a Qt Quick Control.

The default value is `null`, in which case StyledItem is used for rendering instead. If you want to hide the delegate altogether (and prevent if from being created), set visible to `false`.

The delegate needs to define the following required properties:

     required property DelegateStyle delegateStyle
     required property QtObject control

`delegateStyle` points to the DelegateStyle that describes how the delegate should be styled. `control` points to the Qt Quick Control that owns the delegate. The latter can be used to resolve additional information about the control not available from the style.

If you know the specific type of the owning control, you can use it instead of QtObject for the `control` property. For example, since a handle delegate in the snippet below is always used inside a Slider, the type can be set to T.Slider:

     // import QtQuick.Templates as T

     slider {
         handle.delegate: Rectangle {
             id: handle
             required property DelegateStyle delegateStyle
             required property T.Slider control
             implicitWidth: delegateStyle.implicitWidth
             implicitHeight: delegateStyle.implicitHeight
             radius: delegateStyle.radius
             color: delegateStyle.color
             Text {
                 anchors.centerIn: parent
                 text: handle.control.value.toFixed(0)
             }
         }
     }

Note: If a DelegateStyle has a drop shadow defined, it will be drawn separately by a shadow delegate.

See also data, visible, and StyledItem.

### gradient : Gradient

The gradient of this delegate. The default value is `null` (no gradient).

Unlike a Quick Rectangle, where a gradient replaces the color, StyleKit draws the gradient on top of the color. This means you can use a semi-transparent gradient as an overlay (for example, a subtle shading effect) while the color shows through underneath.

     button {
         background.gradient: Gradient {
             GradientStop { position: 0.0; color: Qt.alpha("black", 0.0)}
             GradientStop { position: 1.0; color: Qt.alpha("black", 0.2)}
         }
         background.color: "lightsteelblue"
         hovered.background.color: Qt.darker("lightsteelblue", 1.1)
         pressed.background.color: Qt.darker("lightsteelblue", 1.2)
     }

See also color.

### image : ImageStyle

Grouped property for placing an image inside this delegate.

See also ImageStyle.

### implicitHeight : real

The implicit height of this delegate.

### implicitWidth : real

The implicit width of this delegate. Set this to Style.Stretch to make the delegate fill the available width of the control.

### leftMargin : real

The left margin of this delegate. If not set, falls back to margins.

See also margins, rightMargin, topMargin, and bottomMargin.

### margins : real

The uniform margin around this delegate. Setting this provides a default value for leftMargin, rightMargin, topMargin, and bottomMargin. Each side can be overridden individually.

See also leftMargin, rightMargin, topMargin, and bottomMargin.

### minimumWidth : real

The minimum width of this delegate. The delegate will not be sized smaller than this value.

### opacity : real

The opacity of this delegate, from `0.0` (fully transparent) to `1.0` (fully opaque). The default value is `1.0`.

See also visible and color.

### radius : real

The corner radius applied to all four corners of this delegate. Individual corners can be overridden with topLeftRadius, topRightRadius, bottomLeftRadius, and bottomRightRadius.

See also topLeftRadius, topRightRadius, bottomLeftRadius, and bottomRightRadius.

### rightMargin : real

The right margin of this delegate. If not set, falls back to margins.

See also margins, leftMargin, topMargin, and bottomMargin.

### rotation : real

The rotation of this delegate, in degrees.

### scale : real

The scale factor of this delegate. The default value is `1.0`.

### shadow : ShadowStyle

Grouped property for styling a drop shadow behind this delegate.

See also ShadowStyle.

### topLeftRadius : real

The top-left corner radius. If not set, falls back to radius.

See also radius, topRightRadius, bottomLeftRadius, and bottomRightRadius.

### topMargin : real

The top margin of this delegate. If not set, falls back to margins.

See also margins, bottomMargin, leftMargin, and rightMargin.

### topRightRadius : real

The top-right corner radius. If not set, falls back to radius.

See also radius, topLeftRadius, bottomLeftRadius, and bottomRightRadius.

### visible : bool

Whether this delegate is visible. The default value is `true`.

Note: Although the default value is `true`, the fallback style (which overrides many of the default values) sets `background.visible` to `false` for controls that typically should not draw a background, such as CheckBox, RadioButton, and Slider.

When `visible` is `false`, the delegate will not be created. If you need a hidden delegate to be created, consider setting opacity to `0` instead.

See also opacity.