Qt Quick Components

Page

A Page defines one screen of user interface content. More...

  • List of all members, including inherited members
  • Properties

    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 Tab component that provides parallel sets of content.

    See the Creating pages and navigating to them overview for a higher level discussion about pages and page stacks.

    Defining the content of a page

    Usually you base the pages (screens of content) of your application on the Page component but you can use other components or elements if you wish. However, the benefit of the Page component is that it defines a contract for how the page and page stack and work together. 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 view or animated out of view.

    You can implement an application page either as a QML item or as a QML component. One way to think of the difference between an item and a component is to think of a QML item as a particular page object and a QML component as defining a class 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. Note that PageStack works transparently with either type of page. The main thing you need to consider is how long you want the page to be staying around in memory.

    Example of a QML page as an item

    Here is an example page defined 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 page you will use most often because it encapsulates the page in its own file which makes for easier maintenance. The following code snippet comes from a file called FilePage.qml.

     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 would look 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"
                 }
             }
         }

    Adding a toolbar to a page

    ###TBD. See ToolBar, ToolButton and ToolBarLayout.

    Using the lifecycle signals of a Page

    The page lifecycle goes from instantiation to activation to deactivation to destruction, moving any number of times between activation and deactivation. When a page is activated it means it is visible on the screen and can be considered to be "the current" page. If the page stack itself is not visible, then 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. Likewise, if the page stack is made hidden the top-most page is deactivated. Popping the page off the top of the stack at this point does not result in further deactivation since the page is not active.

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

    1. Created: Component.onCompleted()
    2. Activating: onStatusChanged (status is PageStatus.Activating)
    3. Activated: onStatusChanged (status is PageStatus.Active)
    4. Deactivating: onStatusChanged (status is PageStatus.Deactivating)
    5. Deactivated: onStatusChanged (status is PageStatus.Inactive)
    6. Destruction: Component.onDestruction()

    See also PageStack.

    Property Documentation

    orientationLock : int

    Defines the page's orientation. Possible values:

    • PageOrientation.Automatic (default) - the orientation switches to match how the user is holding the device.
    • PageOrientation.LockPortrait - lock this page in portrait mode, irrespective of how the user is holding the device.
    • PageOrientation.LockLandscape - lock this page in landscape mode, irrespective of how the user is holding the device.
    • PageOrientation.LockPrevious - keep this page in the current orientation. The orientation will not be changed if the user rotates the device.

    pageStack : PageStack

    The page stack that this page is owned by.


    status : int

    This is the status of the page. It can be one of the following values:

    • PageStatus.Inactive - the page is not visible
    • PageStatus.Activating - the page is transitioning into becoming the active page
    • PageStatus.Active - the page is the current active page
    • PageStatus.Deactivating - the page is transitioning into becoming inactive

    tools : Item

    Defines the tools for the page; null for none.

    ### Need more details here.