Creating a Qt Quick Application

This tutorial uses preset components and illustrates basic concepts of Qt Quick. For more information about the UI choices you have, see User Interfaces.

This tutorial describes how to use Qt Creator to implement states and transitions. We create an application that displays a Qt logo that moves between three rectangles on the page when you click them.

"States and transitions example"

For more information about developing Qt Quick applications in the Design mode, see Developing Qt Quick Applications.

For examples of using Qt Quick Controls, see Qt Quick Controls Examples.

Creating the Project

  1. Select File > New File or Project > Application (Qt Quick) > Qt Quick Application - Empty.
  2. Select Choose to open the Project Location dialog.
  3. In the Name field, enter a name for the application. When naming your own projects, keep in mind that they cannot be easily renamed later.
  4. In the Create in field, enter the path for the project files. You can move project folders later without problems.
  5. Select Next (or Continue on macOS) to open the Define Build System dialog.
  6. In the Build system field, select the build system to use for building and running the project: qmake, CMake, or Qbs.
  7. Select Next to open the Define Project Details dialog.
  8. In the Screen resolution field, select the initial size of the UI. You can easily change the screen size later in Properties.
  9. Select Next to open the Translation File dialog.
  10. Select Next to use the default settings and to open the Kit Selection dialog.
  11. Select kits for the platforms that you want to build the application for. To build applications for mobile devices, select kits for Android ARM and iPhone OS.

    Note: Kits are listed if they have been specified in Tools > Options > Kits (on Windows and Linux) or in Qt Creator > Preferences > Kits (on macOS). For more information, see Adding Kits.

  12. Select Next to open the Project Management dialog.
  13. Review the project settings, and select Finish (or Done on macOS) to create the project.

For more information about the settings that you skipped, see Creating Qt Quick Applications.

Qt Creator generates a component file, main.qml, and opens it in the Text Editor view. Select Design to open the file in the Form Editor view.

Note: The visibility of Design views depends on the selected workspace. To open hidden views, select View > Views in the Design mode. For more information about moving views around, see Managing Workspaces.

Creating the Main View

The main view of the application displays a Qt logo inside a rectangle in the top left corner of the view and two empty rectangles.

We use the qt-logo.png image in this tutorial, but you can also use any other image or a component, instead.

  1. In Library > Components > Default Components > Basic, select Rectangle and drag and drop it to Window in Navigator.
  2. Select the Rectangle instance in Navigator, and enter page in the ID field in Properties.
  3. In Layout, select the "Fill anchor button" fill anchor button to anchor the rectangle to the window on all sides.
  4. Select Library > Assets > to locate qt-logo.png (or your own image) and add it to the project folder.
  5. Drag and drop the image from Assets to page in Navigator. Qt Creator automatically generates an instance of the Image component for you, with the image as the source image.

    "Image properties"

  6. In Properties, edit the properties of the Image component instance:
    1. In the ID field, enter icon.
    2. In the Position field, set X and Y to 20.
  7. In Library > Components > Default Components > Basic, select Rectangle and drag and drop it to page in Navigator.

    "Rectangle properties"

  8. In Properties, edit the properties of the Rectangle component instance:
    1. In the ID field, enter topLeftRect.
    2. In the Size field, set W and H to values that match the image size (55 and 41).
    3. Select the Color field, and then select the "Transparent button" button in the color picker to make the rectangle transparent.
    4. In the Border color field, set the border color to #808080 to make the rectangle visible on the background.
    5. Click Layout, and then click the "Top anchor button" top and "Left anchor button" left anchor buttons to anchor the rectangle to the top left corner of the page.
    6. In the Margin field, select 20 for both anchors.

      "Anchor margins"

  9. Drag and drop a Mouse Area component from the Library to topLeftRect in Navigator.
  10. Click Layout, and then click the "Fill anchor button" button to anchor the mouse area to its parent.
  11. In the Navigator, copy topLeftRect (by pressing Ctrl+C) and paste it to page in Navigator twice (by pressing Ctrl+V). Qt Creator renames the new instances of the component topLeftRect1 and topLeftRect2.
  12. Select topLeftRect1 and edit its properties:
    1. In the ID field, enter middleRightRect.
    2. In Layout, select the "Vertical center anchor button" vertical center anchor button and then the "Right anchor button" right anchor button to anchor the rectangle to the middle right margin of its parent.
    3. In the Margin field, select 20 for the right anchor and 0 for the vertical center anchor.
  13. Select topLeftRect2 and edit its properties:
    1. In the ID field, enter bottomLeftRect.
    2. In Layout, select the (Bottom) and (Left) anchor buttons to anchor the rectangle to the bottom left margin of its parent.
    3. In the Margin field, select 20 for both anchors.
  14. Press Ctrl+S to save the changes.

To check your code, you can view your main.qml file in the Text Editor and compare it with the main.qml example file.

The UI design is now ready.

"Transitions UI"

For more information about the views you used, see:

Next, we will make the image move between the rectangles when users click them by adding states and by connecting mouse clicks to state changes.

Because the Window component requires states to be added into child components, we must first move page into a separate component.

Turning Page into a Custom Component

To turn page into a custom component, right-click it in Navigator or Form Editor, and select Move Component into Separate File in the context menu.

"Move page component instance into a separate file"

  1. In Component name, enter Page.
  2. In Property assignments for main.qml select both check boxes to preserve the appearance of the UI.
  3. Select OK to create a file called Page.qml that defines the Page custom component and to add an instance of it into main.qml.

Connecting Mouse Clicks to State Changes

To make the image move between the rectangles when users click them, we add states to the Page component, where we change the values of the x and y properties of icon to match those of the middle right and top left rectangles. Then, we connect the onClicked signals of the mouse areas to the state changes.

To make sure that the image is displayed within the rectangle when the view is scaled on different sizes of screens, we bind the values of the x and y properties of icon to those of the rectangles.

  1. Right-click page in Navigator, and select Go into Component in the context menu to open Page.qml in Form Editor.
  2. In the States view, select Create New State three times to create State1, State2, and State3.
  3. Select State1 in States.
  4. Select to open the Actions menu, and then select Set as Default to display State1 when the application starts.
  5. Select State2 in States.
  6. Select icon in Navigator to display its properties in Properties.
  7. In Geometry - 2D > Position > X, select "Actions button" , and then select Set Binding to open Binding Editor.
  8. Select the middleRightRect component and the x property to bind the x property value of icon to that of middleRightRect.

    "Binding Editor"

  9. Select OK to create the binding.
  10. Repeat for Y, but set the binding as middleRightRect.y.
  11. Select State3 in States, and bind the x and y property values of icon to those of bottomLeftRect (bottomLeftRect.x and bottomLeftRect.y).
  12. In Connection View > Connections, click the button to create a new connection.

    "Connections tab"

  13. Double-click the value in the Target column, and select mouseArea in the list.
  14. In the Signal Handler column, select onClicked.
  15. In the Action column, select page.state = 'State1'.
  16. Create two more connections to connect the onClicked signal of mouseArea1 to State2, and that of mouseArea2 to State3.
  17. Press Ctrl+R to run the application.

Click the rectangles to move the Qt logo from one rectangle to another.

If you develop with Qt 6, you must specify the connections as functions. This is currently not supported in Connections, so you must do it in Text Editor. For example:

MouseArea {
    id: mouseArea
    anchors.fill: parent

    Connections {
        target: mouseArea
        function onClicked()
        {
            page.state = "State1"
        }
    }
}

For more information about the views you used, see:

Animating Transitions

We will now create transitions to apply animation to the image. For example, the image bounces back when it moves to middleRightRect and eases into bottomLeftRect.

  1. In the Transition Editor view, click the button to create a new transition.
  2. Click the button to specify transitions for switching to each state.

    "Transition Settings dialog"

  3. In the Transition ID field, enter toState1.
  4. In the From field, select State2 and State3.
  5. In the To field, select State1.
  6. Click to add transitions for switching to State2 and State3, with the IDs toState2 and toState3.
  7. Select Close to save the settings and return to Transition Editor.
  8. Select toState2 in the list of transitions.

    "Transition Editor view"

  9. Pull the right edge of the blue bar next to icon to frame 1000 to specify that the x and y coordinates of the image change linearly over a duration of 1 second.
  10. Select the x property, and click to change the easing curve type from linear to easeOutBounce ([0.233,0.161,0.264,0.997,0.393,0.997,0.522,0.997,0.555,0.752, 0.61,0.75,0.664,0.748,0.736,1,0.775,1,0.814,0.999,0.861,0.901,0.888, 0.901,0.916,0.901,0.923,0.995,1,1]) in Easing Curve Editor.

    "Easing Curve Editor"

  11. Select the y property and set the easing curve for it, too.
  12. Close Easing Curve Editor to return to Transition Editor, and select toState3 in the list of transitions.
  13. Pull the right edge of the blue bar next to icon to frame 2000 to specify that the x and y coordinates of the image change linearly over a duration of 2 seconds.
  14. In Easing Curve Editor, change the easing curve type from linear to easeInOutQuad ([0.455,0.03,0.515,0.955,1,1]).
  15. Select toState1 in the list of transitions, and pull the blue bar to frame 200 to specify that the x and y coordinates of the image change linearly over a duration of 200 milliseconds.
  16. Press Ctrl+R to run the application.

For more information about the views you used, see:

Click the rectangles to view the animated transitions.

Files:

Images:

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.