HIG and components API

[Marco Martin]

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

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.

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.

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"
* 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

* 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

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

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


----------------------------------
An example of use may be:

PlasmaApplication {

 globalDrawer: Item {
                Heading {text: "Fabulous app"}
		TabBar {...}
                Menu {...}
 }

  contextualActions: [
	Action {
		text: "foo"
 		onTriggered: doStuff()
        },
	Action {
		text: "bar"
 		onTriggered: doStuff()
        }
 ]

 WhateverMainApplicationContents {

 }

}

---------------------------------
Possible problems:
* the two panels may be always instantiated, even if empty this may be not 
optimal memory and loading time wise
* toolbar api still no defined
* 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

-- 
Marco Martin