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().


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
Sign up for Free and start developing right away!
I want to make Games
I want to make Apps
Game Development
Cross-Platform, Any Resolution

Use one IDE to deploy to all supported platforms, including iOS and Android, from a single code base.

Support all screen resolutions, aspect ratios and sizes with auto-adapting UI elements, smart scene scaling and memory efficient asset selection.

Learn More

V-Play ranked #1 at research2guidance cross-platform tool benchmarking 2014 by 2188 developers comparing 40 leading tools.

Multiplayer

V-Play Multiplayer supports both real-time and turn-based gameplay, so you can use it to make many different types of cross-platform multiplayer games. It's perfect for making player-vs-player games like 'Words with Friends' or games for a large amount of players, such as 'Clash of Clans'.

Learn More Video

Highscores & Achievements

The V-Play Game Network is a cross-platform gaming service that allows players around the world to compare game highscores and achievements. Players can also challenge each other across multiple platforms and share their progress on Facebook.

Learn More

QML & JavaScript

Qt Meta Language is a highly intuitive reactive language, which is super easy to learn, yet it's extremely powerful and flexible. Mix it with JavaScript to create awesome stuff, with just a few lines of code.

import QtQuick 2.0
import VPlay 2.0

GameWindow {
  Scene {
    
    SimpleButton {
      anchors.centerIn: parent
      text: "Press Me"
      onClicked: {
        console.debug("Wow you pressed me!")
      }
    }
  }
}

Learn More

Monetize & Analyze

With V-Play, you can use many 3rd party services for ads, in-app purchases, analytics and more, with just a few lines of code. All of these plugins work cross-platform, which allows you to maintain a single code base.

Learn More

Level Editor

The LevelEditor can be used during development to create and modify levels for your game, which you can then bundle in your final publishing build. Additionally, you can also integrate the in-game level editor to your published game and let your gamers create new levels.

Learn More Video

Card Game like UNO, Hearthstone or Poker

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/OneCard/OneCard.pro

Match-3 like Candy Crush Saga

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/JuicySquash/JuicySquash.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/JuicySquashAdvanced/JuicySquashAdvanced.pro

Puzzle like 2048 or Threes!

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/2048/2048.pro

Casino like Big Win Slots

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/FlaskOfRum/FlaskOfRum.pro

Side Scroller like Jetpack Joyride or Flappy Bird

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/FlappyBird/FlappyBird.pro

Tower Defense like Castle Defense or Bloons TD

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/Squaby/Squaby.pro

Falldown & Jump like Doodle Jump or Mega Jump

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/ChickenOutbreak/ChickenOutbreak.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/ChickenOutbreak2/ChickenOutbreak2.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/DoodleJump/DoodleJump.pro

Platformer like Super Mario or Lep's World

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/Platformer/Platformer.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/PlatformerWithLevelEditor/PlatformerWithLevelEditor.pro

Action like Angry Birds, Fruit Ninja, Cut the Rope

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/StackTheBoxWithCommunityEditor/StackTheBoxWithCommunityEditor.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/BalloonPop/BalloonPop.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/CarChallenge/CarChallenge.pro

Arcade like Arkanoid or Space Invaders

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/demos/ZombieBreak/ZombieBreak.pro

Community like Super Mario Maker or Minecraft

We got a demo game for you!

The V-Play SDK includes an open-source demo for this game genre. You can use its source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/examples/Squaby/Squaby.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/StackTheBoxWithCommunityEditor/StackTheBoxWithCommunityEditor.pro

<Path to V-PlaySDK>/Examples/V-Play/demos/PlatformerWithLevelEditor/PlatformerWithLevelEditor.pro

Any other Idea? let us know how we can help you

You are looking for another demo?

The V-Play SDK includes many open-source demos for different game genres. You can use their source code and build your game in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

If you do not find your game genre in this list and wonder if V-Play is the right choice, just contact us, we are happy to help!

Contact Us

App Development
Better Apps, Less Effort

Develop feature-rich, cross-platform mobile apps from a single code base.

V-Play apps look, feel and perform exactly like native iOS, Android and Desktop apps. With less code & much faster development time.

Learn More Highlights Video

V-Play ranked #1 at research2guidance cross-platform tool benchmarking 2014 by 2188 developers comparing 40 leading tools.

Save Time, Code & Money

Save up to 90% source code with V-Play, compared to frameworks like Xamarin, Titanium, React Native and others.

Learn More

QML & JavaScript

Qt Meta Language is a highly intuitive reactive language, which is super easy to learn, yet it's extremely powerful and flexible. Mix it with JavaScript to create awesome stuff, with just a few lines of code. QML also allows you to easily create smooth and complex animations.

import QtQuick 2.0
import VPlayApps 2.0

App {
  Page {
    
    AppButton {
      anchors.centerIn: parent
      text: "Press Me"
      onClicked: {
        console.debug("Wow you pressed me!")
      }
    }
  }
}

Learn More

Monetize & Analyze

With V-Play, you can use many 3rd party services for ads, in-app purchases, analytics and more, with just a few lines of code. All of these plugins work cross-platform, which allows you to maintain a single code base.

Learn More

Native Sensors & More

V-Play Apps harness the power of Qt, the leading cross-platform development framework used by over 1,000,000 developers.

This gives your access to native device features like sensors, camera, file system as well as multimedia, networking, localization and much more.

Learn More

Responsive Design

V-Play has built in responsive design capabilities, you can target phones and tablets with the same source code.

Learn More

Highly Extensible

You have existing JavaScript, C++ or native code? You want to add any 3rd party SDK that we do not offer already?

No worries, you can add any JS, C++, Java or Objective-C code to your project.

Learn More

Component Showcase App shows the most important V-Play features and components

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/showcase/Showcase.pro

Qt World Summit Conference App a full-featured conference management app made by V-Play

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/qtws2016/QtWS2016.pro

Twitter App how to build layouts like in the official Twitter app for iOS and Android

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/twitter/Twitter.pro

Maps App displays free bikes or boxes at bike stations for Vienna's bike sharing service Citybike Wien

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/maps/Maps.pro

Messaging App demonstrates how to create the UI of a Facebook Messenger like app

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/messaging/Messaging.pro

Weather App how to include powerful animations into your user interface

We got a demo app for you!

The V-Play SDK includes an open-source demo for this app type. You can use its source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play.

<Path to V-PlaySDK>/Examples/V-Play/appdemos/waether/Weather.pro

Any other Idea? let us know how we can help you

You are looking for another app demo?

The V-Play SDK includes many open-source demos for different app types. You can use their source code and build your app in record time. After installing V-Play, you can simply open the .pro file with Qt Creator, the development environment used for V-Play..

If you do not find your app type in this list and wonder if V-Play is the right choice, just contact us, we are happy to help!

Contact Us