[Qt-components] QML component APIs and techniques

Zsombor Egri zsombor.egri at canonical.com
Mon Jan 14 09:27:02 CET 2013

On 01/11/2013 10:55 AM, Bache-Wiig Jens 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. :)
One question about the practicalities, how do you guys see we should
discuss about the APIs? Here in the list in separate threads for each
component, or we open again an entry in bugreports and have the debate
(or summary) there?
> 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? 
Here I have to agree with Alan that ToolButton is not necessarily
obvious. Due to styling, our (Ubuntu) ToolButtons are simple Buttons
with different style.

RadioButton decision was postponed as we have ValueSelector in between
ListItems, and for our current needs that was more suitable than the
RadioButton. However, here I agree with Alen that a RadioGroup with
options would suit much better than a separate group to which radio
elements will be added.

We had some discussions about the Menu/ContextMenu, but we haven't
decided yet whether to have it or not.

Then yes, the BusyIndicator we call it as ActivityIndicator as that
feels more generic about indicating any activity, where busy is one
activity. And yes, we could argue that busy is the usual activity or not :)
> - 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.
We have both, and yes, the dubious tools property was left out.
> 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?
Ubuntu doesn't have it because we haven't yet agreed on its need. The
features you describe here are more layout specific therefore I'd handle
them separately.
> - 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.
ToolBar is not yet there in Ubuntu, and StatusBar is a system component
and applications don't have too much interaction with it.
> - 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?
No such component in Ubuntu.
> - TextArea
> A cosmetically decorated and resizable TextEdit item with built-in flickable/scrollarea.
Exists in Ubuntu, the API is the TextExit + few properties for automatic
expansion control.
> - ScrollArea
> A flickable/viewport with built-in decoration and scroll bar controls. 
Does not exist in Ubuntu - yet.
> - 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.
Yes, because for us it is not just a decorator. Depending on its
delegate implementation, it can be a simple decorator or an interactive
one, or it can be both. The current delegate implementation supports
both interactive and decorator functionality.
> - 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.
Agree. Ubuntu has the Tabs and again, with different delegate
implementations it can have the old style behaviour (group of buttons on
the top/bottom of the pages) or the new style - see ComponentShowcase in
Ubuntu toolkit.
>>> 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).
> Jens
> _______________________________________________
> Qt-components mailing list
> Qt-components at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/qt-components


More information about the Qt-components mailing list