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. 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 concurrent applications that work well on GNU Linux distros, Plasma Mobile and Android.

How to use MauiKit?

The MauiKit works as a submodule, and it relies on the KDE framework Kirigami. It makes use of qmake to be included in 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, MauiKit 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 include 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 at 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 colored by making use of the theming property accentColor and cast a shadow.
By default the floating bar does not overlap 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 floatingBar property. It is useful when the FootBar needs to stand out.

Theming Properties:

These properties can be changed to alter the look of the application from the Maui Kit controls and to the application’s controls. By default, the colors are picked up from the system color 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 a 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, it uses the property Kirigami.Units.devicePixelRatio

int rowHeight
It defines a standardized height for rows, such as in lists and menus. It is used on the templated controls inside the Maui Kit, and it is recommended 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 recommended to be used in the application. It has a smaller height size than the rowHeight property

int toolBarHeight
It 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 recommended to be used in the application where fitted.

int toolBarHeightAlt
It 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 recommended to be used in the application where fitted.

int contentMargins
It defines a standardized size for content margins in places like Page, Panes, and other controls.

var fontSizes
It defines a standardized set of sizes to be used 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, enormous

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, enormous


The Application window is based on 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 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 achieved 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, and 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 of 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

© 2017-2020 Some Rights Reserved. Made with ♥ by Nitrux Latinoamericana S.C.