HIG and components API

[Thomas Pfeiffer]

Hi Marco,
first of all: Thank you for starting this discussion. I know we should have 
done that already, and I promise we'll make more use of the mailing list from 
now on.

I will not go into too much detail about the reasoning/basic assumptions 
behind our decisions, as that will be covered in a blog post I've been writing 
on since last Friday, and I promise I'll finish this week.

On Monday 05 October 2015 16:50:40 Marco Martin wrote:
> Hi all,
> 
> Wall of text ahead, but please, don't just "mark as read" :p
> I want to have a proper discussion on components for the API of mobile
> components since via email looks a bit messy, maybe an etherpad document may
> be created that may make things a bit easier with some formatting goodness

Etherpad is fine with me, or whatever floats you guys' boats.
 
> some preliminar version of the HIG for Plasma Mobile is out at
> https://techbase.kde.org/Projects/Usability/HIG/Patterns/CommandPatterns
> https://techbase.kde.org/Projects/Usability/HIG/Patterns/NavigationPatterns
> 
> I want to provide some components in order to make easy to write
> applications that behave like this, especially since doing something in QML
> that behaves exactly like described, and that looks coherent enough with
> all the other apps is not trivial.

Yes, components are crucial both for consistency and for the adoption of the 
HIG. A HIG is supposed to make people's lives easier, not harder, and 
components that "automatically" comply with the HIG are an integral part of 
that.

> Moreover, I'm feeling that the api and the usage of the components will be
> quite intertwined with what will be the hig in the end.

What exactly do you mean by that?

> The main points that I'm tackling now are some aspects of the application:
> * applications should have two panels that slide from the edges that overlay
> the app content (shown in https://www.youtube.com/watch?v=4eYPTlUgdZo) *
> the right panel contains a list of actions that are context specific to the
> current application "page"

Ah damn, I made a mistake here: That HIG still reflects the original intention 
of using the Context Drawer only for what on desktop goes into a context menu. 
This is likely to still be true in most of the cases, but while thinking about 
concrete applications, we realised that this may be too limited. In Okular, 
for example, navigating through the currently opened document via TOC or 
bookmarks is specific to the context, but canot be done in a list of actions.

For the Okular case we'd even need tabs in that drawer (as we had in Okular 
Active).

Therefore I fear I have to change that HIG. I assume a list of actions will 
still be the default (and therefore it makes sense to make this as easy as 
possible), but we will have to allow developers to alternatively also put 
other controls there, including tabs.

> * the left panel is some "global" actions it may include tool to invoke
> settings or something comparable to the menubar
> * the toolbar is at the bottom and contains at most 4 buttons

> ----------------------
> UI wise, things that i'm still not sure/not completely agree are:
> * side panels: i have as well one slightly semantically different kind of
> panel in which you slide out the app content to uncover the panel content
> instead (like the web browser on the blackberry where the menu is an
> overlay drawer that enters from the right, the tabs are on the left, and
> the webpage slides away to show them). I like it (and is already there) but
> not so important, overlay panels on both sides are fine as well

I do like the "split drawers" as I called them in Plasma Active in general. 
The only downside I see is that they may be in conflict - from a mental model 
perspective - with column-based navigation (people may be confused whether 
sliding to the side will bring the next column or the drawer).
 
> * toolbar: I'm not sure having the side slide panels only to appear with
> edge slide, may be a good idea having two buttons at the screen edges of
> the toolbar, this leaves room for:
> two buttons for the sidebars, aligned at the edges
> 3 buttons of generic actions, aligned in the middle

Okay, here's the thing: Mostly the reason why Android still has that button 
for the drawer is that it's not even present in all applications that ship 
with Android, let alone third-party apps. Therefore, users may indeed not 
expect them to be there if there is no indication.

In Plasma Mobile, we have the chance to give more space to the content by 
removing UI "Chrome" without sacrificing usability, because we can make sure 
things like the drawers are used consistently across KDE applications. That 
way, we can give users a quick tutorial at the first start (Sailfish OS is an 
excellent example of how a tutorial can give interaction designers more 
freedom for innovation without sacrificing usability) and then allow them to 
transfer that knowledge to all applications.

I also know that we want our apps to be able to run on Android, though. What I 
don't want to do, however, is make them look and feel exactly like any other 
Android app even in Plasma Mobile. Much of the benefit Plasma Mobile can bring 
to users will come in the form of great KDE applications which integrate well 
with it. If we just make them look and feel like Android, there won't be much 
room for innovation.
This is actually one of the cases where I'd hope we could make the components 
automatically adapt to the environment they run in. In Android, applicaitons 
by default have a header bar, which contains both the menu button for the 
navigation drawer and the overflow button for contextual controls.
What I'd like to see is that when our apps run in Android, they draw such a 
header bar with the two buttons.

Within Plasma Mobile, however, I'd like to give that space back to the 
content, since a Plasma Mobile user will learn pretty quickly to epxect both 
drawers to be there.

Would that be possible?

> ------------------------
> API
> For the side panels I have a component called OverlayPanel
> it has a property called drawer that can be any Item, that will contain
> whatever is in the sliding panel. another property is "inverted" that
> decides wether it comes out from the left or from the right.
> 
> I think it makes sense to provide a skeleton "Application" type, extending
> the QQC Application to automagically have the side panels and the bottom
> toolbar in place, a rough sketch of the API I had in mind is:
> 
> PlasmaApplication {
>   property Item globalDrawer   // the contents of the drawer, not sure
> wether to have a default implementation for the contents or not
>   property Item contextualDrawer // the contents: by default a series of
>                                           actions with a title
> 
>   property string contextualDrawerTitle //title that will be shown in the
>                                       default implementation of the
> contextual drawer contents.. maybe provide globalDrawerTitle too, if
> globalDrawer will have default contents as well
> 
>   property bool globalDrawerOpen  //true when the drawer is open, assign it
> to programmatically open/close property bool contextualDrawerOpen
> 
>   property var contextualActions  //actions show in the contextual menu, it
> may be a list of Action {} an array of the same thing or an array of
> QActions }

Would this API still allow for a context drawer with additional controls? (see 
my comment further up)

> Still not sure about the toolbar, wether using the same contextualActionList
> or a separate list of actions.
> I think it should figure out automatically how many buttons to show to not
> clutter it too much (having specified in the hig that each action should be
> available elsewhere too in case it gets cutted away)

Shouldn't we be fine if we set a hard limit on the number of toolbar buttons 
in the HIG (four should fit on any screen, right?), telling people that they 
should put additional buttons elsewhere? I don't like having things duplicated 
in the little space available on mobile.

> in a tablet or in horizontal mode more actions could be shown
> *but* it should also have api to alternatively put in there some arbitrary
> widget instead

Landscape mode could show more buttons, yes, but I don't think it would be 
beneficial to have the toolbar change dynamically with the orientation, this 
would likely confuse more than it helps.

For tablets, an optimized UI should be created anyway.

[...]

> * could some content for the global drawer be there by default? do we leave
> a blank slate? even the hig examples are very heterogeneous
> https://techbase.kde.org/Projects/Usability/HIG/GlobalDrawer

We could put an "About" button there...