[Qt-components] QML component APIs and techniques

Alan Alpert 416365416c at gmail.com
Fri Jan 11 18:34:41 CET 2013

On Fri, Jan 11, 2013 at 12:55 AM, Bache-Wiig Jens
<Jens.Bache-Wiig at digia.com> wrote:
> 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

Not necessarily. ToolBar (+ToolButton) and ContextMenu aren't in
Cascades. This is because in Cascades the system has tighter control
of the UI, and for standard application chrome that's managed by the
scene backend. You don't create your own tool bar for your application
- it creates the system tool bar for your application when you specify
actions for it. Same for context menus, like in this example:

Then there are some divergent designs: like with RadioButton. Cascades
has a RadioGroup with Option elements per button. This is a better
abstraction in that it handles the grouped case more easily for you,
but you lose more free-form control of the location of the buttons.

Finally, of course there are a few arbitrary name differences. Like
ActivityIndicator, ProgressIndicator and ToggleButton. Name
differences are the easy win for compatibility anyways, so I'd say we
should tackle this category first.

ToggleButton is particularly hard to defend when they describe it as a
switch in the documentation, Switch is probably better there. I
actually like ActivityIndicator and ProgressIndicator over Spinner and
ProgressBar. Not only is it a little more generic, allowing more
flexibility, but it's matching (both "Indicators"). I like Activity
over Busy in the indicator because that's more accurate (you're not
necessarily busy, you just want to show activity to the user so they
feel more comfortable waiting).

> 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.

Page is a good idea, because it allows extension (even if those
extensions are platform specific or just future ideas). Cascades has a
Page, and a PageStack named "NavigationPane". Which behaves like a
stack. Associating actions with the Cascades Page seems to be how you
get a toolbar like interface. This again makes me think that we should
add Action as one of the types that we look at for compatibility
(especially if a QGuiAction is added that most people can use - note
that Cascades does not rely on QtGui).

> 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?

Cascades doesn't have one either. But I was going to strongly suggest
one to them for the next version - it will be a lot easier once
Cascades doesn't require it's own Application subclass (something I
think everyone agrees is bad, no need to yell about it).

In general I would advocate an ApplicationWindow for all component
sets because that gives you a place in QML to do all of your custom
setup. That gives you the option of using that component set with a
generic runtime like the proposed qml tool (not that you have to - you
can also use ApplicationWindow to block that behavior if you so

> - 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.

Neither exists in Cascades.

> - 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.

Exists in Cascades with that name.

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

Called ScrollView in Cascades.

> - 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.

Agreed. Text needs to remain platform agnostic as a rendering
primitive for text. You need to be able to use it in your
platform-specific app alongside Labels, for the rare case where you
want to custom-render a bit of text instead of making it fit in

Cascades has a Label, with that name to boot!

> - 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.

Cascades has a TabbedPane (built-in TabBar) and a Tab element for
populating it. To me this seems to be the correct abstraction - it's
conceptually the same as Page/PageStack except that the navigation
flow is different. The names in Cascades even match a little, Tab/Page
and TabbedPane/NavigationPane.

Alan Alpert

More information about the Qt-components mailing list