Scene

The root element for a single game view. More...

Import Statement: import VPlay 2.0
Inherits:

Item

Properties

Signals

Methods

Detailed Description

This component contains the logic for auto-scaling its content (i.e. its children) to the parent GameWindow item.

The content of a Scene is scaled from its logical size to the GameWindow size depending on the scaleMode. This allows to use the same code for all screen resolutions. So if the Scene size is set to 480x320 for instance, the contents will be scaled by a factor of 2 with a GameWindow size of 960x640.

Example Usage

The simplest V-Play application consists of a GameWindow and a Scene. The scene has a default size of 480x320 and the scaleMode is letterbox. The blue rectangle fills the whole GameWindow and is anchored to its bottom. You can resize the GameWindow on your desktop by pressing the keyboard shortcuts ctrl(cmd)+1-7 to see the effect of different screen sizes. Fullscreen can be changed by pressing the keyboard button ctrl(cmd)+F.

 import QtQuick 2.0 // for the Rectangle element
 import VPlay 2.0 // for the GameWindow and Scene element

 GameWindow {

     Scene {
         id: scene
         // this Scene is centered horizontally and vertically by default

         Rectangle {
             color: "green"
             width: 100
             height: 50
         }

         // this Rectangle has the size of the whole GameWindow (not only the logical Scene)
         // it is also anchored to the bottom of it
         Rectangle {
             color: "blue"
             width: scene.gameWindowAnchorItem.width
             height: 20
             anchors.bottom: scene.gameWindowAnchorItem.bottom
         }
     }
 }

Also see the GameWindowSceneScaling Example for more information about different scaleModes.

See also GameWindow.

Property Documentation

backButtonAutoAccept : bool

Set this property to false if you want to handle the back button events manually. If this is false, the event.accepted property of the key event is not set to true. This causes the closing of the app on Android, if you do not handle the back button event on your own.

The default value is true and prevents closing of the app on Android when the Scene has active focus.

This QML property was introduced in V-Play 2.1.1.

See also backButtonPressed.


backButtonSimulationEnabled : bool

This property holds whether a Qt.Key_Backspace keyPressed event calls the backButtonPressed signal.

By default, it is set to system.desktopPlatform which is only true on Windows, Mac and Linux but false on iOS and Android.

With this property you can simplify testing the back button logic also on Desktop.

This QML property was introduced in V-Play 2.1.1.

See also backButtonPressed.


dpScale : real

The scale factor all dp() values are multiplied with.

The default value is 1.

This QML property was introduced in V-Play 2.2.0.

See also dp(), spScale, and uiScale.


gameWindowAnchorItem : alias

This property alias to an Item can be used for anchoring direct children of a Scene to the parent GameWindow and not the logical Scene size.

For example use anchors.bottom: gameWindowAnchorItem.bottom to position an item to the bottom of GameWindow and not to the logical Scene size, with the benefit of applied content scaling.

See also How to create mobile games for different screen sizes and resolutions and GameWindowSceneScaling Example.


gridSize : real

The gridSize can be set when the level editing feature is used and the entities should be snapped to a raster. The default gridSize is 16. So for instance for a 480x320 scene with gridSize 16, a 30x20 grid is created.

If you dont want to use entity snapping, disable it by setting the gridSize to 1.


scaleMode : string

This property specifies how the Scene gets scaled its contents to the parent GameWindow.

There are 4 scaleMode settings available:

  • letterbox: The scene gets scaled to the smaller side so no content is cropped. This is the default setting.
  • zoomToBiggerSide: The bigger scale factor is used for x&y, so a uniform scale is applied but content is cropped.
  • zoomNonUniform: The scene is scaled so it fits into the GameWindow. When the window has a different aspect ratio than the scene, a non-uniform scale is applied which leads to distortions of images and is thus not recommended.
  • none: No scaling to the GameWindow size is applied, so the scene will always stay at the logical size specified initially.

By default, this property is set to the GameWindow default scaleMode which is letterbox. It can however be set for each scene individually too.

See also GameWindowItem::scaleMode and How to create mobile games for different screen sizes and resolutions.


sceneAlignmentX : string

This property defines the horizontal position of the Scene based on the scaleMode and the GameWindow size.

It can have the values "left", "center" and "right". The default value is center.

Also see the GameWindowSceneScaling Example for more information about different scaleModes.

See also sceneAlignmentY.


sceneAlignmentY : string

This property defines the vertical position of the Scene based on the scaleMode and the GameWindow size.

It can have the values "top", "center" and "bottom". The default value is center.

Also see the GameWindowSceneScaling Example for more information about different scaleModes.

See also sceneAlignmentX.


sceneGameWindow : variant

This property can be set if the Scene is not a direct child of the GameWindow. By default, this property is set to parent.

It is used internally to calculate the top left position based on the scaleMode.


spScale : real

The scale factor all sp() values are multiplied with.

The default value is 1.

This QML property was introduced in V-Play 2.2.0.

See also sp(), dpScale, and uiScale.


uiScale : real

The scale factor all dp() and sp() values are multiplied with.

The default value is 1.

This QML property was introduced in V-Play 2.2.0.

See also dp(), sp(), spScale, and dpScale.


xScaleForScene : real

This property contains the applied scale factor for the children items of Scene. It gets internally calculated based on the scaleMode, the Scene size and the GameWindow size. Use this property if you want to write custom items that depend on the content scaling factor.

The xScaleForScene and yScaleForScene property are equal when scaleMode is set to letterbox or zoomToBiggerSide. They are both 1 when scaleMode is set to none.

Internally, V-Play uses this scaleFactor to determine which image version should be loaded, so with an sd, hd or hd2 suffix. See MultiResolutionImage for this.

See also yScaleForScene.


yScaleForScene : real

This property contains the applied scale factor for the children items of Scene. It gets internally calculated based on the scaleMode, the Scene size and the GameWindow size. Use this property if you want to write custom items that depend on the content scaling factor.

The xScaleForScene and yScaleForScene property are equal when scaleMode is set to letterbox or zoomToBiggerSide. They are both 1 when scaleMode is set to none.

Internally, V-Play uses this scaleFactor to determine which image version should be loaded, so with an sd, hd or hd2 suffix. See MultiResolutionImage for this.

See also xScaleForScene.


Signal Documentation

backButtonPressed()

This signal is emitted when the back button (Qt.Key_Back) was pressed. Handling the back button is required for a good user experience of your game on Android.

This signal is emitted when the Scene gets Item::focus. This is done automatically if GameWindowItem::activeScene is set to this Scene.

For an example with back button handling per scene, see Advanced Example with Android Back Button and Focus Handling.

To prevent the app from accepting the back button event when it has focus, set backButtonAutoAccept to false. If you change this setting, do accept the back button event manually to avoid closing the application on Android when the back button is pressed.

Simulate Back Button Handling

When testing an app, it is often useful to simulate the back button handling and logic on Desktop platforms Windows, Mac and Linux. This is enabled by default when you press the Qt.Key_Backspace key. To disable this simulation, set backButtonSimulationEnabled to false.

The corresponding handler is onBackButtonPressed.

This QML signal was introduced in V-Play 2.1.1.


Method Documentation

dp(value)

Returns the density-independent unit for this pixel value for children of Scene components.

This allows you to define the same physical size for Item elements across platforms and screens with different densities.

DPI Examples

The dp value is calculated with the following formula: dp = pixel * screenDpi / 160

This means:

  • On a 160 dpi screen like the iPhone 3 (non-retina display), the pixel value of 1 will return 1 dp unit.
  • On a 320 dpi screen like the iPhone 4 (retina display), the pixel value of 2 will return 1 dp unit.

Although the pixel values are different, the physical size of them is the same!

160 dp equals 1 inch. You can calculate the inch value from the pixel value with pixelToInches().

Note: The recommended button height is 48dp. This equals 3/10 of an inch or 0.8 centimeters.

You can modify the result of all dp() function calls by changing the dpScale or uiScale properties.

Example Usage

 import VPlay 2.0
 import QtQuick 2.0

 GameWindow {
   id: gameWindow

   Scene {
     id: gameScene
     // position on top of the GameWindow
     sceneAlignmentY: "top"

     Rectangle {
       width: parent.width
       height: gameScene.dp(48)

       Text {
         text: "20sp"
         font.pixelSize: gameScene.sp(20)
       }
     }
   }// Scene

   // this Rectangle & Text has the same size as the one defined in the Scene
   Rectangle {
     // position below the Rectangle of the Scene
     y: gameWindow.dp(48)
     width: parent.width
     height: gameWindow.dp(48)

     Text {
       text: "20sp"
       font.pixelSize: gameWindow.sp(20)
     }
   }// Rectangle
 }

Note: To calculate the dp value of elements that are NOT children of a Scene but from GameWindow, use GameWindowItem::dp().

Also see the guide Density Independence Support: dp, sp, pixelToInches, tablet, orientation for more information on density independence. The Android Developers Guide about Supporting Multiple Screens is also a great read to better understand density independence, as the same concepts of Android are used in V-Play.

This QML method was introduced in V-Play 2.2.0.

See also sp(), dpScale, and uiScale.


fromGameWindowPixel(pixel)

Helper function to return the Scene pixel value from a GameWindow pixel value.

The pixel value is divided by xScaleForScene.

You can use this function to convert for example a GameWindow position to a Scene position.

This QML method was introduced in V-Play 2.2.0.

See also fromGameWindowPixel().


physicalPixels(pixel)

Returns the pixel value multiplied with the devicePixelRatio of the screen.

On iOS & Mac devices, the reported screen size of GameWindow is a virtual point size. To get the real pixels of the screen, a multiplication with devicePixelRatio is needed.

You will mostly not need this value, but it may be useful for debug output or certain scenarios.

Note: The physicalPixels value of the screen is used in V-Play to choose the default V-Play File Selectors to support Dynamic Image Switching.

This QML method was introduced in V-Play 2.2.0.


pixelToInches(pixel)

Returns the value in inches from the pixel value.

You can use the inch value for example to load different layouts based on the physical size.

This QML method was introduced in V-Play 2.2.0.

See also dp() and sp().


sp(value)

Returns the density-independent unit for this pixel value for children of Scene components. Only use this function for Text element font.pixelSize values.

This allows you to define the same physical size for Text elements across platforms and screens with different densities.

DPI Examples

The dp value is calculated with the following formula: dp = pixel * screenDpi / 160

This means:

  • On a 160 dpi screen like the iPhone 3 (non-retina display), the pixel value of 1 will return 1 dp unit.
  • On a 320 dpi screen like the iPhone 4 (retina display), the pixel value of 2 will return 1 dp unit.

Although the pixel values are different, the physical size of them is the same!

160 dp equals 1 inch. You can calculate the inch value from the pixel value with pixelToInches().

Note: The recommended button height is 48dp. This equals 3/10 of an inch or 0.8 centimeters.

You can modify the result of all sp() function calls by changing the spScale or uiScale properties.

Note: The only difference to dp() is that you have a different spScale value available to change the scale factor of Text elements. You could read the user settings for font sizes of the system and change it accordingly. This is done by default for native Android applications - you could implement this function yourself by querying the user font settings and then changing the spScale value.

You could also use the spSale to allow users change the font size in your app at runtime, for example with a slider in a settings scene.

Example Usage

 import VPlay 2.0
 import QtQuick 2.0

 GameWindow {
   id: gameWindow

   Scene {
     id: gameScene
     // position on top of the GameWindow
     sceneAlignmentY: "top"

     Rectangle {
       width: parent.width
       height: gameScene.dp(48)

       Text {
         text: "20sp"
         font.pixelSize: gameScene.sp(20)
       }
     }
   }// Scene

   // this Rectangle & Text has the same size as the one defined in the Scene
   Rectangle {
     // position below the Rectangle of the Scene
     y: gameWindow.dp(48)
     width: parent.width
     height: gameWindow.dp(48)

     Text {
       text: "20sp"
       font.pixelSize: gameWindow.sp(20)
     }
   }// Rectangle
 }

Note: To calculate the sp value of elements that are NOT children of a Scene but from GameWindow, use GameWindowItem::dp().

Also see the guide Density Independence Support: dp, sp, pixelToInches, tablet, orientation for more information on density independence. The Android Developers Guide about Supporting Multiple Screens is also a great read to better understand density independence, as the same concepts of Android are used in V-Play.

This QML method was introduced in V-Play 2.2.0.

See also dp(), dpScale, and uiScale.


toGameWindowPixel(pixel)

Helper function to return the GameWindow pixel value from a Scene Window pixel value.

The pixel value is multiplied by xScaleForScene.

You can use this function to convert for example a Scene position to a GameWindow position.

This QML method was introduced in V-Play 2.2.0.

See also fromGameWindowPixel().


Videos

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