QML Page Element

Defines one screen of the user interface content. More...

Inherits Item

List of all members, including inherited members

Properties

• orientationLock : int
• pageStack : PageStack
• status : int
• tools : Item

Detailed Description

The screen area of a mobile device is small, so an application's user interface is often composed of a set of separate screens of content or "pages". You can use pages in conjunction with the PageStack component to provide a navigation system for your application. Another navigation alternative is the TabGroup component that provides parallel sets of content.

See the Page Based Application Navigation overview for a higher level discussion about pages and page stacks.

Defining the Content of a Page

Normally you base the pages (screens of content) of your application on the Page component but you can use other components or elements if you want. However, the benefit of the Page component is that it defines a contract how the page and the page stack interact. A Page component based page is notified when it becomes active or inactive and this allows you to perform various page-specific operations while the page is animated into the view or out of the view.

You can implement an application page either as a QML item or a QML component. You can regard a QML item as a particular page object and a QML component as a class definition of page objects. If your page is an item, you use the page directly as you have defined it. If you want to use a component page, you have to create an instance of that component page and use that instance. PageStack works transparently with either type of the page. The main thing you need to consider is how long you want the page to stay in the memory.

Example of a QML Page as an Item

The code snippet below defines a page as an item. It is a page with a text that can be accessed externally.

 // a page item
 Page {
     id: itemPage
     property alias message: pageText.text
     Text {
         id: pageText
         anchors.centerIn: parent
         text: "item page"
         font.pointSize: 25
         color: "white"
     }
 }

Example of a QML page in a component file

The page described above can also be declared in its own file. This is probably the type of a page you will use most often because it encapsulates the page in its own file making its maintenance easy. The following code snippet is from FilePage.qml file.

 import QtQuick 1.0
 import Qt.labs.components.native 1.0

 Page {
     id: filePage
     property alias message: pageText.text
     Text {
         id: pageText
         anchors.centerIn: parent
         text: "page from file"
         font.pointSize: 25
         color: "white"
     }
 }

Example of a QML Component Page

The page described earlier is an example of a simple page declared as a QML item. Declaring this same page as a component looks like this:

 // a page component
 Component {
     id: componentPage
     Page {
         id: myComponentPage
         property alias message: pageText.text
         Text {
             id: pageText
             anchors.centerIn: parent
             text: "component page"
             font.pointSize: 25
             color: "White"
         }
     }
 }

Defining Toolbar Contents of a Page

The default value of tools is null resulting in the toolbar belonging to the PageStack to be invisible.

If each Page in your application requires a different ToolBarLayout, then the PageStack can manage the ToolBar on your behalf. All that is required are the following steps:

1. Set the PageStack::toolBar property of the PageStack to be a ToolBar instance
2. Set the Page::tools property of each Page to be the appropriate ToolBarLayout instance that corresponds to that Page.

When the current Page on the top of the PageStack changes, its tools will be set to be the ToolBarLayout contained within the ToolBar

See the ToolBar documentation for more details and example code.

Life Cycle Signals of a Page

The page's life cycle phases are instantiation, activation, deactivation, and destruction. The following rules apply:

• The page can switch between activation and deactivation phases any number of times during its life cycle.
• When a page is activated it becomes visible on the screen and can be considered to be "the current" page.
• If the page stack is not visible, the top-most page in the stack is deactivated and is not visible.
• When the page stack becomes visible, the top-most page in the stack is activated.
• When the page stack is made hidden the top-most page is deactivated.
• When a any other than top-most page is popped off from the stack, it does not result in deactivation since the page is not active.

The status property indicates the current state of the page. Combined with the normal Component.onCompleted() and Component.onDestruction() signals you can follow the entire life cycle of the page as follows:

• Created: Component.onCompleted()
• Activating: onStatusChanged (status is PageStatus.Activating)
• Activated: onStatusChanged (status is PageStatus.Active)
• Deactivating: onStatusChanged (status is PageStatus.Deactivating)
• Deactivated: onStatusChanged (status is PageStatus.Inactive)
• Destruction: Component.onDestruction()

See also PageStack, ToolButton, and ToolBarLayout.

Property Documentation