Ubuntu.Components.UbuntuShape

Rounded rectangle containing a source image blended over a background color. More...

Import Statement: import Ubuntu.Components 1.3
  • Obsolete members

Properties

Detailed Description

The UbuntuShape is a rounded rectangle (based on a href="https://en.wikipedia.org/wiki/Squircle">squircle) containing an optional source image blended over a background color (solid or linear gradient). Different properties allow to change the look of the shape.

Examples:

import Ubuntu.Components 1.2
UbuntuShape {
backgroundColor: "green"
}
import Ubuntu.Components 1.2
UbuntuShape {
source: Image {
source: "ubuntu.png"
}
}

Property Documentation

aspect : enumeration

This property defines the graphical style of the UbuntuShape. The default value is UbuntuShape.Inset.

Note: Setting this disables support for the deprecated borderSource property. Use the UbuntuShapeOverlay item in order to provide the inset "pressed" aspect previously supported by that property.

  • UbuntuShape.Flat - no effects applied
  • UbuntuShape.Inset - inner shadow slightly moved downwards and bevelled bottom

backgroundColor : color

This property defines the background color. The default value is transparent black.

Note: Setting this disables support for the deprecated color and gradientColor properties.

This QML property was introduced in Ubuntu.Components 1.2.


backgroundMode : enumeration

This property defines the background rendering mode. The default value is UbuntuShape.SolidColor.

Note: Setting this disables support for the deprecated color and gradientColor properties.

This QML property was introduced in Ubuntu.Components 1.2.


radius : string

This property defines the corner radius. Three fixed values are supported: "small", "medium" and "large". The default value is "small".

Note: Setting a non-zero relativeRadius value disables this property temporarily.


relativeRadius : real

This property defines a radius relative to the size of the UbuntuShape. It is specified as a number between 0.0 (0%) and 0.75 (75%) corresponding to the proportion of the radius with regards to the smallest side (divided by 2 since a side has 2 angles). The default value is 0.0.

Note: Setting a non-zero value takes over the radius property.

This QML property was introduced in Ubuntu.Components 1.3.


secondaryBackgroundColor : color

This property defines the secondary background color. It is used when backgroundMode is set to UbuntuShape.VerticalGradient. The default value is transparent black.

Note: Setting this disables support for the deprecated color and gradientColor properties.

This QML property was introduced in Ubuntu.Components 1.2.


source : http://doc.qt.io/qt-5/qml-variant.html">variant

This property sets the source provider of a texture rendered in the UbuntuShape. Supported types are Image, AnimatedImage (to render a GIF image for instance) and ShaderEffectSource (to embed a UI previously rendered with QML). It is blended over the background color. The default value is null.

It can be set either with an inlined Image:

Item {
UbuntuShape {
source: Image { source: "ubuntu.png" }
}
}

or with an Image id:

Item {
Image {
id: img
visible: false
source: "ubuntu.png"
}
UbuntuShape {
source: img
}
}

Note that in this case, the Image is stored in the scene tree as any other items. So setting it as not visible might be needed.

The href="https://en.wikipedia.org/wiki/Texture_filtering">sampling filter is set through the given Item's smooth property. Set it to false for nearest-neighbor filtering or to true for bilinear filtering.

The fill modes and alignments set on the Image and AnimatedImage are not monitored, use the appropriate UbuntuShape properties instead (sourceFillMode, sourceHorizontalAlignment and sourceVerticalAlignment).

Note: Setting this disables support for the deprecated image property.

This QML property was introduced in Ubuntu.Components 1.2.


sourceFillMode : enumeration

This properties defines how the source texture fills the UbuntuShape. The modes are the same as the ones used by Image, minus the tiling which is exposed through wrapping properties (sourceHorizontalWrapMode and sourceVerticalWrapMode). The default value is UbuntuShape.Stretch.

Note: Setting this disables support for the deprecated image property.

  • UbuntuShape.Stretch - the source is scaled non-uniformly to fit
  • UbuntuShape.PreserveAspectFit - the source is scaled uniformly to fit without cropping
  • UbuntuShape.PreserveAspectCrop - the source is scaled uniformly to fit with cropping
  • UbuntuShape.Pad - the source is not scaled

This QML property was introduced in Ubuntu.Components 1.2.


sourceHorizontalAlignment : enumeration

This property defines how the source texture is horizontally aligned inside the UbuntuShape area. The default value is UbuntuShape.AlignLeft.

Note: Setting this disables support for the deprecated image property.

  • UbuntuShape.AlignLeft - the source is aligned to the left
  • UbuntuShape.AlignHCenter - the source is aligned to the horizontal center
  • UbuntuShape.AlignRight - the source is aligned to the right

This QML property was introduced in Ubuntu.Components 1.2.


sourceHorizontalWrapMode : enumeration

When the sourceFillMode is set to UbuntuShape.Pad or UbuntuShape.PreserveAspectFit or when the sourceScale and/or sourceTranslation properties are changed, the source texture might not cover the entire UbuntuShape area. This property defines how the source texture wraps outside of its content area. The default value is UbuntuShape.Transparent.

Ensure UbuntuShape.Repeat is used only when necessary (in case of an Image or AnimatedImage source) as it requires the underlying texture to be extracted from its atlas. That slows down the rendering speed since it prevents the http://doc.qt.io/qt-5/qtquick-qmlmodule.html">QtQuick renderer to batch the UbuntuShape with others.

Note: Some OpenGL ES 2 implementations do not support UbuntuShape.Repeat with non-power-of-two sized source textures.

Note: Setting this disables support for the deprecated image property.

  • UbuntuShape.Transparent - the source is clamped to transparent
  • UbuntuShape.Repeat - the source is repeated indefinitely

This QML property was introduced in Ubuntu.Components 1.2.


sourceOpacity : real

This property holds the opacity of the source texture. Opacity is specified as a number between 0.0 (fully transparent) and 1.0 (fully opaque). The default value is 1.0.

Note: Setting this disables support for the deprecated image property.

This QML property was introduced in Ubuntu.Components 1.2.


sourceScale : http://doc.qt.io/qt-5/qml-vector2d.html">vector2d

This property defines the two-component vector used to scale the source texture. The texture is scaled at the alignment point defined by sourceHorizontalAlignment and sourceVerticalAlignment. The default value is Qt.vector2d(1.0,1.0).

That can be used to change the size of the source texture, to flip it horizontally and/or vertically, to achieve pulsing animations, etc.

Here is a code sample showing how to apply an horizontal flip:

UbuntuShape {
source: Image { source: "ubuntu.png" }
sourceScale: Qt.vector2d(-1.0, 1.0)
}

Note: Setting this disables support for the deprecated image property.

This QML property was introduced in Ubuntu.Components 1.2.


sourceTranslation : http://doc.qt.io/qt-5/qml-vector2d.html">vector2d

This property defines the two-component vector in normalized item coordinates used to translate the source texture. The default value is Qt.vector2d(0.0,0.0).

That can be used to put the source texture at a precise position, to create infinite scrolling animations (using the UbuntuShape.Repeat wrap mode), etc.

Note: Setting this disables support for the deprecated image property.

This QML property was introduced in Ubuntu.Components 1.2.


sourceVerticalAlignment : enumeration

This property defines how the source texture is vertically aligned inside the UbuntuShape area. The default value is UbuntuShape.AlignTop.

Note: Setting this disables support for the deprecated image property.

  • UbuntuShape.AlignTop - the source is aligned to the top
  • UbuntuShape.AlignVCenter - the source is aligned to the vertical center
  • UbuntuShape.AlignBottom - the source is aligned to the bottom

This QML property was introduced in Ubuntu.Components 1.2.


sourceVerticalWrapMode : enumeration

When the sourceFillMode is set to UbuntuShape.Pad or UbuntuShape.PreserveAspectFit or when the sourceScale and/or sourceTranslation properties are changed, the source texture might not cover the entire UbuntuShape area. This property defines how the source texture wraps outside of its content area. The default value is UbuntuShape.Transparent.

Ensure UbuntuShape.Repeat is used only when necessary (in case of an Image or AnimatedImage source) as it requires the underlying texture to be extracted from its atlas. That slows down the rendering speed since it prevents the http://doc.qt.io/qt-5/qtquick-qmlmodule.html">QtQuick renderer to batch the UbuntuShape with others.

Note: Some OpenGL ES 2 implementations do not support UbuntuShape.Repeat with non-power-of-two sized source textures.

Note: Setting this disables support for the deprecated image property.

  • UbuntuShape.Transparent - the source is clamped to transparent
  • UbuntuShape.Repeat - the source is repeated indefinitely

This QML property was introduced in Ubuntu.Components 1.2.