ubuntu-phone team mailing list archive

[Zsombor Egri <zsombor.egri@xxxxxxxxxxxxx>]

Hello All,

I just wanted to share a somewhat big change that landed in the SDK/UI
Toolkit, a change which affects theming components, deprecates a few
theming classes [1] and affects applications which use the theming ie.
define custom styles or delegates in a .qmltheme file. The change does
not break anything, however you should adapt your application to the new
theming and stop using the deprecated APIs listed below as we are
planning to remove these in 2-3 weeks from now.


Until now the theming of a component was done so that after specifying
the style class (ItemStyle.style), its properties had to be bound
explicitly using the ComponentUtils and StyleUtils helper functions.
With automatic theming this is no longer needed. With a few exceptions
[2] all the properties of the widget and its delegate are themed
automatically.

The bigger change comes to delegate theming. Until now the itemStyle
context property and StyleUtils utility functions were made to ease
accessing style properties. From now both of these are deprecated, and
all delegates must expose publically properties that should be themed.

To illustrate this, let's look at the Button. The .button style defines
the "color", "borderSource" and "borderPressed" properties:

In default.qmltheme:
.button {
    color: "#cccccc";
    borderSource: url("artwork/ubuntushape_small_radius_idle.sci");
    borderPressed: url("artwork/ubuntushape_small_radius_pressed.sci");
}

In Button.qml:
Item {
    ItemStyle.class: "button"
    property color color
}

In ButtonDelegate.qml:
Item {
    property url borderSource
    property url borderPressed
}

These values will be automatically assigned to the Button and
ButtonDelegate corresponding properties:

Button.color will be "#cccccc"
ButtonDelegate.borderSource: "artwork/ubuntushape_small_radius_idle.sci"
ButtonDelegate.borderPressed: "artwork/ubuntushape_small_radius_pressed.sci"



**What should you do?**
If you use SDK components as they are, without any application specific
theming, you don't have to do anything. If you define a theme (.qmltheme
file) for your application, especially if you have special delegates for
your components, then make sure you remove any reference to StyleUtils
and declare the properties which were used in
StyleUtils.itemStyleProperty() function in the root item of the delegate.

Example of SliderDelegate.qml
Before:
Item {
    id: sliderDelegate
    [...]
    UbuntuShape {
        [...]
        color: StyleUtils.itemStyleProperty("backgroundColor", "white")
    }
}

After:
Item {
    [...]
    property color backgroundColor: "white"
    UbuntuShape {
        [...]
        color: sliderDelegate.backgroundColor
    }
}

That's it. If you have any questions, don't be shy and speak up.

Cheers,
Zsombor


[1] Deprecated APIs (copied from the CHANGES file):
- ComponentUtils module is deprecated (affects componentUtils.js:
hasStyle(), style(), delegateProperty() functions)
- StyleUtils module is deprecated (affects styleUtils.js:
itemStyleProperty(), animateOrSetValue(), animate() functions)
- 'itemStyle' context property is no longer exposed to delegates
- use of style type, second parameter of @qml-mapping is deprecated
- Deprecated theme specific styles and delegates: ButtonStyle,
CheckBoxStyle, NewTabsStyle, SwitchStyle, TabButtonStyle, TextAreaStyle,
TextFieldStyle, TextFieldDelegate, UbuntuShapeStyle. These components
were deprecated and their properties are now in the respective delegates.

[2] The properties not themed automatically are: activeFocus, anchors,
antialiasing, baseline, baselineOffset, bottom, children, childrenRect,
clip, data, focus, horizontalCenter, implicitHeight, implicitWidth,
layer, left, objectName, parent, resources, right, rotation, scale,
smooth, state, states, top, transform, transformOrigin, transitions,
verticalCenter, visibleChildren, x, y and z.


p.s.: Though it is not on the deprecation list, bindings with- or
modifications of style properties which only refer to delegate should be
avoided. Delegate API belongs to the theme API, which does not have a
stable API yet. As example, Tabs' "swipeToSwitchTabs" style property is
altered in gallery-app to alter the delegate functionality:
    Component.onCompleted: ItemStyle.style.swipeToSwitchTabs = false