This tutorial explains the usage of the MeeGo UX Components step by step in order to create a complete application using the window/book/page concept. For an example of a running application please refer to the meego-ux-widgetgallery and the meego-ux-app-photos application.
Create a new QML project in the QtCreator. Make sure that you have installed the meego-ux-components properly. For installation instructions please refer to the README in the repository or the general MeeGo UX Components documentation.
The Window is the base item of every Window-Book-Page based application. In order to use a window, the main.qml must have the Window item as the root item as seen in the step1 project of the tutorial:
// main.qml
Window {
id: window
toolBarTitle: "My Window"
Component.onCompleted: {
console.log("Window loaded")
}
}
The Window object will be existent in the whole life cycle of the application. Make sure to insert global available items, e.g. a settings component here.
In order to add books to the Window, AppPages must be created inside a Component. These AppPages are the first pages of each book. To load them into the bookMenu, all components must be added to the bookMenuPayload and should get a name in the bookMenuModel. In order to switch to a book on startup of the application, the switchBook function must be triggered by one of the Components. Attention: If a switch of books occurs, the complete page stack will be cleared. If the application needs to store global properties, it is helpful to create them in the Window or create a global Item inside the Window for them.
// main.qml
import Qt 4.7
import MeeGo.Components 0.1
Window {
id: window
toolBarTitle: "Book menu test"
bookMenuModel: [ qsTr("Book1"), qsTr("Book2") ]
bookMenuPayload: [ book1Component, book2Component ]
Component { id: book1Component; Page1 {} }
Component { id: book2Component; Page2 {} }
Component.onCompleted: {
switchBook( book1Component )
}
}
// Page1.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page1
pageTitle: "Page 1 of Book 1"
anchors.fill: parent
Rectangle {
anchors.fill: parent
anchors.margins: 30
color: "lightblue"
Text {
anchors.centerIn: parent
text: "Content of Book1/Page1"
}
}
}
// Page2.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page2
pageTitle: "Page 1 of Book 2"
anchors.fill: parent
Rectangle {
anchors.fill: parent
anchors.margins: 30
color: "lightgreen"
Text {
anchors.centerIn: parent
text: "Content of Book2/Page1"
}
}
}
In order to jump to one page of a book after the application started, a switchBook call must be inserted in the onCompleted slot. If the user switches the book via the menu, all current pages on the stack will be removed and destroyed. Please make sure that gobal properties of your application are stored in the window or any item which is independent of the page stack.
In order to fill up the books with pages, the addPage function of the window can be used. After the user jumps to a page, the page will be pushed onto the PageStack and will be shown. If the user is switching back to the old page the current page will be destroyed.
// main.qml
import Qt 4.7
import MeeGo.Components 0.1
Window {
id: window
bookMenuModel: [ qsTr("Book1"), qsTr("Book2") ]
bookMenuPayload: [ book1Component, book2Component ]
Component { id: book1Component; Page1 {} }
Component { id: book2Component; Page2 {} }
Component.onCompleted: {
console.log("Window loaded")
switchBook( book1Component )
}
onActionMenuTriggered: {
// selectedItem contains the selected payload entry
}
}
// Page1.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page1
pageTitle: "Page 1 of Book 1"
anchors.fill: parent
Button {
anchors.centerIn: parent
text: "Next Page"
onClicked: { window.addPage( page1bcomponent ) }
}
Component { id: page1bComponent; Page1b{} }
}
// Page1b.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page1b
pageTitle: "Page 2 of Book 1"
anchors.fill: parent
Rectangle {
anchors.fill: parent
anchors.margins: 30
color: "lightgreen"
}
}
// Page1.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page2
pageTitle: "Page 1 of Book 2"
anchors.fill: parent
Button {
anchors.centerIn: parent
text: "Next Page"
onClicked: { window.addPage( page2bcomponent ) }
}
Component { id: page2bComponent; Page2b{} }
}
// Page1b.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page2b
pageTitle: "Page 2 of Book 2"
anchors.fill: parent
Rectangle {
anchors.fill: parent
anchors.margins: 30
color: "lightblue"
}
}
A ModalContextMenu can be used to open up a context menu on any item shown in the window or page. The content property can be used to set the content of the menu. Usually it is an ActionMenu.
//main.qml
import Qt 4.7
import MeeGo.Components 0.1
Window {
id: window
Component { id: page1; Page1{} }
Component.onCompleted: switchBook( page1 )
}
// Page1.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page1
function doActionOne() {
area.color = "lightgreen"
}
function doActionTwo() {
area.color = "lightblue"
}
pageTitle: qsTr("ModalContextMenu Test")
Rectangle {
id: area
anchors.fill: parent
anchors.margins: 30
color: "lightgrey"
MouseArea {
anchors.fill: parent
onClicked: {
contextMenu.setPosition( mapToItem( topItem.topItem, mouseX, mouseY ).x, mapToItem( topItem.topItem, mouseX, mouseY ).y )
contextMenu.show()
}
}
}
TopItem{ id: topItem }
ModalContextMenu {
id: contextMenu
forceFingerMode: -1
content: ActionMenu{
id: colorMenu
maxWidth: 200
minWidth: 100
model: [ "lightgreen", "lightblue"]
onTriggered: {
if( index == 0 )
page1.doActionOne()
if( index == 1 )
page1.doActionTwo()
contextMenu.hide()
}
}
}
}
Each page can have a global ActionMenu which can be triggered from the status bar of the application. In order to create that ActionMenu you have to set the actionMenuModel and actionMenuPayload for a page. To react to a selection in the ActionMenu, you have to use onActionMenuTriggered like in the example code below:
// main.qml
import Qt 4.7
import MeeGo.Components 0.1
Window {
id: window
Component { id: page1Component; Page1 {} }
Component.onCompleted: {
console.log("Window loaded")
switchBook( page1Component )
}
}
// Page1.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page1
function doActionOne() {
area.color = "lightgreen"
}
function doActionTwo() {
area.color = "lightblue"
}
pageTitle: "ActionMenu Test"
anchors.fill: parent
actionMenuModel: [ qsTr("Make it green"), qsTr("Make it blue") ]
actionMenuPayload: [ 1 , 2 ]
actionMenuTitle: qsTr("ActionMenu")
onActionMenuTriggered: {
if( selectedItem == 1 ) {
doActionOne()
} else if( selectedItem == 2 ) {
doActionTwo()
}
}
Rectangle {
id: area
anchors.fill: parent
anchors.margins: 30
color: "lightgrey"
}
}
ModalMessageBox and other ModalDialogs like the pickers can be used to show information or content to the user. In order to show a ModalMessageBox its function show must be triggered. After the user accepts or rejects the MessageBox, the dialog will disappear automatically. It is also possible to trigger the hide function if the dialog becomes obsolete during runtime.
// main.qml
import Qt 4.7
import MeeGo.Components 0.1
Window {
id: window
toolBarTitle: "My Window"
Component { id: page1Component; Page1{} }
Component.onCompleted: {
console.log("Window loaded")
switchBook( page1Component )
}
}
// Page1.qml
import Qt 4.7
import MeeGo.Components 0.1
AppPage {
id: page1
pageTitle: "ModalDialog Test"
anchors.fill: parent
Button {
id: button
anchors.centerIn: parent
width: 300
height: 80
text: "Show ModalMessageBox"
onClicked: {
messageBox.show()
}
}
ModalMessageBox {
id: messageBox
title: "This is a ModalMessageBox"
text: "Did you press the button gently?"
showAcceptButton: true
showCancelButton: true
fogClickable: false //false means clicking outside the dialog won't close it
onAccepted: { } // do something
onRejected: { } // do something
}
}