MauiKit Controls
In a previous post I introduced the MauiKit project, the idea with this post is to follow up the previous one and demonstrate some of the controls from the MauiKit and show you how to get started.
Just to recap, the MauiKit project is a helpful set of templated controls and custom widgets based on QCC2 and Kirigami that follows the Maui HIG and makes it easier to create convergent applications that work well on GNU Linux distros, Plasma Mobile and Android.
How to use the MauiKit?
The MauiKit works as a submodule and it relies on the KDE framework Kirigami.
It makes use of qmake to be included into your project and then be built.
But you can also now make use of cmake to add it as a subdirectory and linked as a static library.
So let’s say your new project name is Nota, a simple and convergent text editor.
This is how the project folder would look like when we first create the project using Qt Creator:
Now, you will include the MauiKit submodule to your project, but first you need to clone the sources.
git clone https://github.com/maui-project/mauikit — recursive
Don’t forget to add the “ — recursive” parameter when cloning it, because Maui Kit includes another submodule named “tagging” that needs to be present. It is a shared tagging system that allows all the Maui apps to share tags and metadata information between each other, but I will cover that one on another occasion.
Now your project folder should look more like this:
And now it is time to add it to your project sources, so open up your nota.pro file and add the following lines:
linux:unix:!android {
message(Building for Linux )
} else:android {
message(Building for Android)
include($$PWD/3rdparty/kirigami/kirigami.pri)} else {
message(“Unknown configuration”)
}include($$PWD/mauikit/mauikit.pri)
As I mentioned earlier Maui Kit works on top of Kirigami and so it depends on it. If you plan to deploy your app on a device running Android you will also need to add the Kirigami submodule. That’s what is going on in the first previous lines, it is including the Kirigami module and sources if the platform where your project is being deployed is Android.
And in the final line we’re including the Maui Kit module and sources, feel free to check out its content and see what’s in there.
Now we need to expose the MauiKit controls to the QML engine.
Open up your main.cpp file and add the following lines:
First include the Maui Kit header.
#include “mauikit.h”
and then register the MauiKit components.
MauiKit::getInstance().registerTypes();
Your project source files would look now a little more like this:
And now you’re ready to start creating your next convergent application.
On your QML files you now can import the Maui Kit controls like this:
import org.kde.maui 1.0 as Maui
Now, let’s take a first look of the controls included on the Maui Kit.
The most important control is the ApplicationWindow, it is what will make your app a Maui app, so it is the one I will be covering on this post.
Components
ApplicationWindow
Properties:
bool altToolBars
If set to True, the HeadBar will be moved to the bottom of the application window. By default is set to the isMobile property, so if the target device is a mobile device the HeadBar will move to the bottom.
If set to False, then the HeadBar will stay at the top of the application window even on mobile devices.
bool floatingBar
If set to True, the FootBar will act as a floating bar, it will not occupy the full width of the application window, but instead use the minimum width required to place its children content. Also it will be coloured by making use of the theming property accentColor and cast a shadow.
By default the floating bar does not overlaps the content, to make it overlap the content the footBarOverlap property will have to be set to True
By default this property is set to the altToolBars property.
int footBarAligment
By default it is set to Qt.AlignCenter, but can be set to any other alignment value. Changes will be only visible if the floatingBar property is set to True.
bool footBarOverlap
If set to True, and also only if the floatingBar property is set to True too, the FootBar will act as a floating bar overlapping the content of the window.
When this property is set to True, the content will flick when scrolled down to show a reserved space for the FootBar in order to not overlap important content positioned at the bottom.
By default this property is set to False
int footBarMargins
This property adds margins to the FootBar when it is set as a floating bar using the floatinBar property. It is useful when the FootBar needs to stand out.
Theming Properties:
This properties can be changed to alter the look of the application from the Maui Kit controls and to the application own controls.
By default the colours are picked up from the system colour palette.
int iconSize
color borderColor
color backgroundColor
color textColor
color highlightColor
color highlightedTextColor
color buttonBackgroundColor
color viewBackgroundColor
color altColor
color altColorText
color accentColor
color bgColor
Read only properties:
bool isMobile
Defines if the target device is a mobile device or not. By default it uses the property Kirigami.Settings.isMobile
bool isAndroid
Defines if the operating system of the target device is Android or not.
int unit
Defines an unit making use of point size rather than pixel size. It is useful when the target device does not support pixel units right, like Plasma Mobile right now. By default is uses the property Kirigami.Units.devicePixelRatio
int rowHeight
Defines a standardized height for rows, such is in lists and menus. It is used on the templated controls inside the Maui Kit, and it is recommend it to be used in the application.
int rowHeightAlt
Defines a standardized height for alternative rows, such is in sub-items in lists and menus. It is used on the templated controls inside the Maui Kit, and it is recommend it to be used in the application. It has a smaller height size than the rowHeight property
int toolBarHeight
Defines a standardized height for the toolbars. It is used on the templated controls inside the Maui Kit and for the Maui.ToolBar control, and it is recommend it to be used in the application where fitted.
int toolBarHeightAlt
Defines a standardized height for the alternative toolbars. It is used on the templated controls inside the Maui Kit and for toolbars inside the Maui.Page control, and it is recommend it to be used in the application where fitted.
int contentMargins
Defines a standardized size for content margins in places like Page, Panes and other controls.
var fontSizes
Defines a standardized set of sizes to be used to with fonts.
The possible values are: tiny, small, medium, default, big, large
var space
Defines a standardized set of sizes to be used for spacing items and layouts.
The possible values are: tiny, small, medium, big, large, huge, enormus
var iconSizes
Defines a standardized set of sizes to be used for icons and buttons.
The possible values are: tiny, small, medium, big, large, huge, enormus
The Application window is based off Kirigami.ApplicationWindow.
The Maui implementation follows the Maui HIG and suggests the use of toolbars. It is layout vertically and contains: a HeadBar, the Content, a FootBar and a GlobalDrawer.
The HeadBar and FootBar, are both based on another Maui component: Maui.ToolBar, so they inhere its properties.
The Content can be any other QCC2 control, such a a SwipeView, StackView, or Maui.Page, etc…, but for default there is a PageRow from Kirigami, given that Maui.ApplicationWindow is based on Kirigami.ApplicationWindow.
The Content area, as mentioned earlier can be any other control, although the Maui HIG suggests the following horizontal layouts, that can be achieve by making use of a SwipeView or Kirigami.PageRow.
Here’s an example from VVAVE:
By default and for reach-ability the HeadBar is moved to the bottom when it is being deployed on a mobile device, but this can be changed by setting the altToolBars property.
Also, the FootBar is styled differently on mobile devices, it is drawn as a floating bar that does not occupy the full width of the window and uses a background color set by the property accentColor. It can be set to overlap the content or not with the property footBarOverlap and the floating bar can be set with the property floatingBar
Here’s a preview the floating bar overlapping the content:
The following app sets the properties mentioned above as:
accentColor: altColor
highlightColor: “#8682dd”
altColor: “#43455a”
altColorText: “#ffffff”
altToolBars: false
floatingBar: isMobile
footBarOverlap: true
This results in the following UI:
Here are other Maui Kit controls I will be covering next:
ToolBar
ToolButton
Page
FileDialog
ShareDialog
PieButton
Holder
SelectionBar
GlobalDrawer
IconDelegate
Style
SideBar
TagsBar
NewDialog
