Page

A single page within an application. More...

Import Statement: import VPlayApps 1.0
Inherits:

MouseArea

Inherited By:

ListPage and SocialPage

Properties

Signals

Detailed Description

The Page type provides a container for the contents of a single page within an application. This type is designed to be used together with components like Navigation or NavigationStack to provide a native-looking UI and user experience.

Note: Due to V-Play internal mechanisms that provide the native look-and-feel, the Page type places it's content inside of an additional container item. The Page type is thus not a direct parent of the items you add to the Page. This is for example relevant when anchoring content items to the Page. As anchoring is only allowed between siblings or to the direct parent, it is not possible to anchor an item directly to the Page. Please anchor your content items to their parent instead, which is the internal container item.

Property Documentation

[read-only] Item : NavigationStack

The nearest parent item in the QML hierarchy that is a NavigationStack item. (read-only)

If the current item or one of its parent items is a child of a NavigationStack item, this property contains the owning NavigationStack item. This property is null if the Page is not embedded inside a NavigationStack item.


backNavigationEnabled : bool

Set this property to false to disable the back navigation within a page in a NavigationStack if previous pages exist on the stack.

Disabling the back navigation hides the "back" button within a NavigationBar, deactivates the iOS back swipe gesture and also disables the hardware back button on Android and Windows Phone.

The default value is true.

Note: Setting this property only has an effect if the Page is used inside a NavigationStack.


backgroundColor : color

The background color of the Page which is displayed if no other items are placed within the page.

The default value is defined in the Theme::backgroundColor property and can be overridden.


[read-only] canNavigateBack : bool

Read-only property holds whether it is possible to actually navigate back within the current stack. The property is true if a previous page exists on the stack, otherwise false.

This QML property was introduced in V-Play 2.7.0.


[read-only] isCurrentStackPage : bool

Whether the page is currently the NavigationStack::currentPage on top of the stack.

This QML property was introduced in V-Play 2.9.2.


leftBarItem : NavigationBarItem

A custom navigation bar item displayed on the left of the navigation bar if the item is on top of a NavigationStack as a direct child of it.

By default this item displays a back navigation item if the current NavigationStack can navigate back. If setting the item to an explicit NavigationBarItem it replaces the back button with the custom item.

You can customize the item by using a IconButtonBarItem or TextButtonBarItem.


A boolean value indicating whether the navigation bar should be hidden for that specific Page if the item is presented within a NavigationStack item.

You can set this property to false to implement a custom styled full-screen page within a NavigationStack without the default navigation bar behavior (make sure to implement a custom back navigation action in that case).

By default this property is false, meaning that the navigation bar is visible for that Page.


Set this value to make the navigation bar translucent for that specific Page within a NavigationStack.

The allowed value range is 0.0 to 1.0. The default value is 0.0, meaning that the navigation bar is not translucent (fully opaque).

If using a translucent navigation bar, the page content will move beneath the navigation bar and you should add that extra spacing for your pages on your own (you can get the current height from ThemeNavigationBar::height).

This QML property was introduced in V-Play 2.7.0.


The nearest parent item in the QML hierarchy that is a NavigationStack item. (read-only)

If the current item or one of its parent items is a child of a NavigationStack item, this property contains the owning NavigationStack item. This property is null if the Page is not embedded inside a NavigationStack item.


preferredScreenOrientation : int

Set this property to specify a preferred screen orientation for the page.

This overrides the NativeUtils::preferredScreenOrientation as long as this page is the current page in a NavigationStack (i.e. isCurrentStackPage is true).

This property makes it easy to have parts of your app in different screen orientations. E.g., use this code to push a page fixed in portrait mode:

 import VPlay 2.0
 import VPlayApps 1.0
 import QtQuick 2.0

 App {
   id: app

   NavigationStack {
     id: stack

     Page {
       id: page
       title: "Screen orientation test"

       AppButton {
         text: "Push portrait page"
         onClicked: stack.push(portraitPage)
       }
     }
   }

   Component {
     id: portraitPage

     Page {
       id: page
       title: "Portrait page"
       preferredScreenOrientation: NativeUtils.ScreenOrientationPortrait
     }
   }
 }

After the user returns from the portrait page using the back button, the previous value of NativeUtils::preferredScreenOrientation gets restored.

Note: This property only has an effect on mobile platforms.

You can use NativeUtils::screenOrientation to find out the current orientation of the screen.

The default value for this property is NativeUtils.ScreenOrientationUnspecified, indicating that this page does not override the app's global screen orientation.

This QML property was introduced in V-Play 2.16.0.

See also NativeUtils::preferredScreenOrientation and NativeUtils::screenOrientation.


rightBarItem : NavigationBarItem

A custom navigation bar item displayed on the right of the navigation bar if the item is on top of a NavigationStack as a direct child of it.

By default this item is empty.

You can customize the item by using a IconButtonBarItem or TextButtonBarItem.


[read-only] safeArea : Item

On modern devices like the iPhone X, some parts of the screen are covered by native device overlays and buttons. Use this property to anchor and layout your items based on the safe area within the page:

 Page {
   useSafeArea: false // page content can cover whole screen

   Rectangle {
     anchors.fill: parent.safeArea
     color: "lightgreen"
   }
 }

Note: If useSafeArea is set to true, which is the default, all children of page are kept within the safe area automatically.

To access the applied safe area insets for the Page, you can use the insets property:

  • safeArea.insets.left
  • safeArea.insets.top
  • safeArea.insets.right
  • safeArea.insets.bottom

Depending on other used components, the given pixel values can differ from the actual NativeUtils::safeAreaInsets. For example, if the navigation bar of a parent NavigationStack already covers the top inset. The Page itself does not require an additional inset in this case, so safeArea.insets.top will return 0.

This QML property was introduced in V-Play 2.16.0.

See also useSafeArea.


tabBarHidden : bool

A boolean value indicating whether a tab bar should be hidden for that specific Page if the item is presented within a Navigation item showing tabs.

By default this property is false, meaning that the tab bar is visible for that Page.

This QML property was introduced in V-Play 2.7.0.


title : string

A localized, human-readable string that represents the the content of this page.

The title is used as string in a navigation bar if the Page item is a child of a NavigationStack.


titleItem : Item

A custom navigation bar item displayed at the title slot of the navigation bar if the item is on top of a NavigationStack as a direct child of it.

By default, the title of the page is displayed.

This QML property was introduced in V-Play 2.6.2.


useSafeArea : bool

On modern devices like the iPhone X, some parts of the screen are covered by native device overlays and buttons. This property handles whether the Page automatically places child items within the safe area, to not collide with such interface elements.

Set this property to false to manually handle your page layout. You can anchor your items to the safe area with the parent.safeArea property. For instance, you can achieve a layout similar to the safe area example above with:

 import VPlayApps 1.0
 import QtQuick 2.9

 App {
   NavigationStack {

     Page {
       id: myPage
       title: "Your Page"

       // page content can cover whole screen
       useSafeArea: false

       // fills whole page
       Rectangle {
         anchors.fill: parent
         color: "lightblue"
       }

       // fills safe area
       Rectangle {
         anchors.fill: parent.safeArea
         color: "lightgreen"

         AppText {
           anchors.centerIn: parent
           text: "Safe Area"
           font.pixelSize: sp(20)
         }
       }
     }

   }
 }

The NavigationBar is added by the NavigationStack in the above example. It automatically covers a bigger height and layouts correctly. Your tab navigation or app drawer menu added by the Navigation component also automatically adapts to work with the safe area:

To manually work with the safe area insets of the screen, you can use the NativeUtils::safeAreaInsets property.

This QML property was introduced in V-Play 2.16.0.

See also safeArea.


Signal Documentation

appeared()

This signal fires when Page::isCurrentStackPage changes to true. This is the case, whenever the page becomes the active page of a NavigationStack and thus appears on the stack. As long as a page is not popped from the stack, it will appear and disappear whenever the user navigates back and forth between this page and other pages on the stack.

This QML signal was introduced in V-Play 2.18.1.

See also disappeared, pushed, and popped.


disappeared()

This signal fires when Page::isCurrentStackPage changes to false. This is the case, when the page is popped or another page is pushed to the NavigationStack, causing the page to disappear. As long as a page is not popped from the stack, it will appear and disappear whenever the user navigates back and forth between this page and other pages on the stack.

This QML signal was introduced in V-Play 2.18.1.

See also appeared, pushed, and popped.


popped()

This signal triggers whenever the Page got popped from its NavigationStack. Popping the top-level page from the stack causes it to disappear, so the disappeared signal fires as well. As long as a page is not popped from the stack, it will appear and disappear whenever the user navigates back and forth between this page and other pages on the stack.

Note: Only the popped signal of the top-most page is triggered when you remove more than one page at once with methods like NavigationStack::popAllExceptFirst or NavigationStack::popAllExceptFirstAndPush.

This QML signal was introduced in V-Play 2.9.2.

See also pushed, appeared, and disappeared.


pushed()

This signal tiggers whenever the Page got pushed to a NavigationStack. Pushing a page causes it to appear at the top of the NavigationStack, so the appeared signal fires as well. As long as a page is not popped from the stack, it will appear and disappear whenever the user navigates back and forth between this page and other pages on the stack.

This QML signal was introduced in V-Play 2.9.2.

See also popped, appeared, and disappeared.


Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support