[Qt-components] QML component APIs and techniques

Martin Jones martin.jones at jollamobile.com
Mon Jan 14 05:45:13 CET 2013

On 12/01/13 03:34, Alan Alpert wrote:
> 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:
> https://developer.blackberry.com/cascades/reference/bb__cascades__actionset.html
> .

Sailfish doesn't have a ToolBar at all, which just means we don't care 
about the API, I suppose.  Currently an image-based button in Jolla is 
named IconButton rather than ToolButton.  We do have ContextMenu.

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

No radio buttons in Sailfish so far.

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

Sailfish uses "Switch".  Currently a read-only Slider is used as 

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

Sailfish has Page and PageStack with similar API to meego components API.

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

Sailfish has an ApplicationWindow.  Doesn't have a statusBar or toolBar, 

> 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
> choose).
>> - Menu and ContextMenu. Both roughly make sense on desktop but the MenuLayout has to go.

MenuItem is one that we should be able to agree on, even with differing 
menu styles.

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

ToolButton is named IconButton in Sailfish, since that is what it is.

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

and in Sailfish

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

We don't have this in Sailfish.  There are Sailfish-specific versions of 
Flickable, ListView and GridView, though.

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

In Sailfish we have VerticalScrollDecorator, HorizontalScrollDecorator 
and ScrollDecorator (providing both horz and vert decorators).

>> - 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
> nicely.
> Cascades has a Label, with that name to boot!

Sailfish too.

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

No tabs in Sailfish.

I'd also add Slider as a common control type.  In Sailfish, looks like:
real maximumValue
real minimumValue
real value
bool handleVisible - display a handle at the current value position
string valueText - text indicating the current value

Is anyone setting up a page somewhere to gather this data?


More information about the Qt-components mailing list