The new header property
This is a tutorial on how to use the new PageHeader component. So far, we had one header per application, implemented in the MainView, and configurable for each page using the Page.head property (which is an instance of PageHeadConfiguration). We deprecated that approach, and added the Page.header property, which can be set to be any Item so that each page has its own header instance. When it is set, two things happen:
The (deprecated) application header is disabled and any configuration that may be set using the old Page.head property is ignored,
The Page.header item is parented to the page.
Because the header is parented to the page, inside the header you can refer to its parent, and other items inside the page can anchor to the header.
Use PageHeader for an Ubuntu header
In order to get a header that looks like an Ubuntu header, use the PageHeader component. This component provides properties to set the title and actions in the header and shows them the way you are used to in Ubuntu apps. Below I will show how to customize the header styling, but first an example that uses the default visuals:
The leadingActionBar and trailingActionBar are instances of ActionBar, and can thus be configured in the same way any action bar can be configured. The default settings for the leading action bar configures the number of slots as 1, sets the overflow icon to "navigation-menu", and the default value for actions is navigationActions, which is a property of the PageHeader set by the PageStack or AdaptivePageLayout to show a back button when needed. If leadingActionBar.actions is explicitly defined as in the example above, the back button added by a PageStack or AdaptivePageLayout is ignored. The trailing action bar automatically updates its number of slots depending on the space available for showing actions. On a phone it will show 3 actions by default, but on a tablet or desktop more. When actions.length > numberOfSlots for the leading or trailing action bar, an overflow button will automatically be shown that shows the other actions when tapped.
Automatic show/hide behavior
The examples above show a static header where the page contents is anchored to the bottom of the header. When the page contains a Flickable or ListView, this can be linked to the header so that it automatically moves with the flickable:
When PageHeader.flickable is set, the header automatically scrolls with the flickable, and the topMargin of the Flickable or ListView is set to leave enough space for the header, so the flickable can fill the page. Besides using the flickable to scroll the header in and out of the view, the PageHeader.exposed property can be set to show or hide the header. The PageHeader will automatically become more slim on a phone in landscape orientation to make better use of the limited vertical screen space.
Extending the header
Some applications require more functionality in the header besides the actions in the leading and trailing action bars. For this, we have the extension property which can be any Item that will be attached at the bottom of the header. For changing what is 'inside' the header, there is the contents property which will replace the default title label. The following example shows how to use the extension and contents properties to implement search mode and edit mode that can be switched between by clicking the action buttons in the default header:
Customize the looks
Now that we covered the basic functionality of the page header, let's see how we can customize the visuals. That can be done by creating a theme for your app that overrides the PageHeaderStyle of the Ambiance theme, or by using StyleHints inside the PageHeader. To change the looks of the header for every page in your application, it is recommended to create a custom theme, but the example below shows how to use StyleHints to change the properties of PageHeaderStyle for a single PageHeader instance:
If the header needs to be customized even further, use the contents property, as is demonstrated in the example above for the search mode, or use any Item for Page.header, as was shown in the first example. For a fully custom header that will still show and hide automatically when the user scrolls in the page, use the Header component which is the parent component of PageHeader, and set its flickable property.
That’s all. I am looking forward to see what you will do with the new and often-requested flexibility of the new header in the Ubuntu UI Toolkit.