[Qt-components] QML component APIs and techniques

Bache-Wiig Jens Jens.Bache-Wiig at digia.com
Fri Jan 11 09:55:10 CET 2013

On Jan 11, 2013, at 1:12 AM, Aaron J. Seigo <aseigo at kde.org> wrote:

> On Friday, January 11, 2013 09:22:00 you wrote:
>>  The Meego and Symbian components have a large API, so I think they should
>> be used as a reference for naming the properties, rather than a starting
>> point for an API.
> while i agree that they have a lot to offer in terms of experience based 
> results that we can use as reference, they are also dead platform with limited 
> software available for them. if there is reason to diverge, the pre-existence 
> of these implementations should not hold us back imho.

Yes I don't think there is a danger of them holding anyone back. But if there are good reasons why specific parts of these APIs do not work any more or did not work, it would be good if we brought that up here so we can agree to make the same changes to them.

As a matter of fact, this task: https://bugreports.qt-project.org/browse/QTCOMPONENTS-200 was historically the properties that were agreed to be common ground and general purpose enough to be included in both API's. It also includes a lot of the ongoing discussion on property naming that I suspect will eventually end up being repeated in this thread. :)

So to get started with some initial notes:

-  Button, ToolButton, CheckBox, Slider, ProgressBar, TextField, TextArea, RadioButton, ButtonRow, Menu, ContextMenu, ToolBar, Switch, BusyIndicator. 

All these are pretty obvious but it seems we don't agree on "BusyIndicator". Both ActivityIndicator and Spinner seems viable candidates but if BusyIndicator is good enough, is there a good reason to change? 

- Page and PageStack. Are you generally agreeing on these? Page is almost unnecessary as items can be pushed but feels natural in a "pagestack" and will allow some custom margins/styling as well as a status property. But the "tools" property and orientation properties seem dubious and Meego specific.

As for ApplicationWindow the basic API might end up like this:
- ApplicationWindow {  // A QtQuick.Window obviously so has "title" etc
    toolBar: ToolBar { … }
    statusBar: StatusBar { …} 
    initialPage: MyPage{ } 
For desktop it is essentially a replacement for QMainWindow but the way it is defined makes it suitable for hybrid mobile/touch development as well. I see that Ubuntu doesn't have it. Does SailFish define something similar?

- Menu and ContextMenu. Both roughly make sense on desktop but the MenuLayout has to go.

- ToolBar and StatusBar - Probably means something different on various platforms. On desktop both are just special decorated items with their own platform dependant surface area.  As with Menu, no ToolBarLayout is required. As I pointed out on irc, Ubuntu use Toolbar or toolbar without camel casing "Bar". While technically correct, it looks somewhat odd in Qt and should be aligned.

- SectionScroller
base api is far too incomplete to be useful. But perhaps the base name should be used for similar concepts. (i.e list lookup / alphabet scroller API. Does anyone already use a different name for this concept?

- TextArea
A cosmetically decorated and resizable TextEdit item with built-in flickable/scrollarea.

- ScrollArea
A flickable/viewport with built-in decoration and scroll bar controls. 

- ScrollDecorator
somewhat conflicting with ScrollArea. But more convenient when using built-in QtQuick Views.
Canonical seems to call this "Scrollbar" so alignment might be useful but possibly difficult.

- Label
I remember this as the most disputed but ultimately necessary component. It really is just a raw Text element with system-specific font and colours. It would be nice if we could have re-used Text for this but having Text automatically adapt to the system palette/font will break pretty much every existing QML app and breaks with some fundamental QtQuick principles.

- Tabs/TabBar/TabFrame/TabGroup
This one is difficult. Partially because desktop/touch and various platforms have different conventions and needs. I am not sure if we can standardise on this. You can use ButtonRow with the exclusive property to create a raw tabbar but it has no convenience. I introduced TabFrame (which has a TabBar) to have a good "QTabWidget" replacement but that is not the right solution on touch where TabGroup serves the same purpose. Canonical seems to use a "Tabs" item for this.

>> The trick is to define a minimal API, e.g. a Button has "text" property and
>> "clicked" signal.  Much more than that and it won't suit some platforms,
>> especially those that are performance conscience and don't want features
>> unnecessary for their design.
> yes, we can define a minimal API. but most platforms will want more than that. 
> we know that because, well, they provide more than that. and that "more" needs 
> to be consistent.
> i'd support the idea of marking API as "minimally required for conformance" 
> (whatever that might actually mean :), but we need to remain realistic and 
> recognize that the APIs will be richer on most platforms, and that richness is 
> precisely what we need to harmonize.
>>> Did anyone look into standard icon naming? (which was oddly one of the
>>> bigger problems when co-ordinating meego vs symbian API).
> freedesktop.org has a standard for this. we can extend it as needed. i would 
> not suggest creating our own new standard for this, but to follow the 
> freedesktop.org one. this makes it far easier for applications which already 
> follow this (1000s) to be ported.

Agreed. On the Desktop components we are currently considering to add both "iconSource" and "iconName" in the work-in-progress QML Action API, where iconName is based on the free desktop standard. Obviously it is just a convenience to avoid specifying a "themeicon://" image provider on the source property but I find that a bit too cumbersome. We also need to be able to set both conveniently since many platforms don't have standard implementations for the free desktop standard.

I see that Plasma uses QIcon("icon") though. Not sure if that would be a good fit for this.

Alas, the existing naming standard is fairly desktop centric so there are likely going to be problems with standardising mobile icon sets on it. (Meego/N9 was in principle using it).


More information about the Qt-components mailing list