/**************************************************************************** ** ** Copyright (C) 2015 The Qt Company Ltd. ** Contact: http://www.qt.io/licensing ** ** This file is part of Qt Creator ** ** ** GNU Free Documentation License ** ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of this ** file. ** ** ****************************************************************************/ /*! \contentspage {Qt Creator Manual} \previouspage {Creating a Mobile Application} \example uiforms \nextpage creator-project-managing.html \title Using Qt Quick UI Forms \commercial This tutorial describes how to develop an application that uses \e ui.qml files to separate the application logic from the UI. The tutorial uses \QMLD to implement a simplified version of the \l{Qt Quick Controls - UI Forms} {UI Forms example}, which provides an interface to a customer database and is purely written in QML and JavaScript. \note Some of the described features are only available in the commercial version of \QC. \image qmldesigner-uiforms-example.png \e {UI forms} consist of \e .qml and \e .js files that implement the business logic, and corresponding \e .ui.qml files that only contain the purely declarative description of the UI. The \e .ui.qml files should be edited only in the \uicontrol Design mode of \QC. However, \QMLD does not fully support all QML controls, such as the TableView, so you sometimes need to edit UI forms also in the \uicontrol Edit mode. You can keep this to the minimum by creating custom QML types that you edit in the \uicontrol Edit mode. \section1 Creating the UI Forms Project \list 1 \li Select \uicontrol File > \uicontrol {New File or Project} > \uicontrol Application > \uicontrol {Qt Quick Controls Application} > \uicontrol Choose. \li In the \uicontrol Name field, type \b uiforms. \li In the \uicontrol {Create in} field, enter the path for the project files and then click \uicontrol Next (or \uicontrol Continue on OS X). \li In the \uicontrol {Minimal required Qt version} field, select \uicontrol {Qt 5.4}, or later. \li Select \l{glossary-buildandrun-kit}{kits} for your project and click \uicontrol{Next}. \note Kits are listed if they have been specified in \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} > \uicontrol Kits (on Windows and Linux) or in \uicontrol {Qt Creator} > \uicontrol Preferences \uicontrol {Build & Run} > \uicontrol Kits (on OS X). \li Review the project settings, and click \uicontrol Finish (or \uicontrol Done on OS X). \endlist \QC generates a default UI file, \e MainForm.ui.qml, that you can modify to create the main view of the application. \section1 Creating the UI Forms Main View The main view of the application displays a customer list in a table view and detailed information about the selected customer in a tab view. \image qmldesigner-uiforms-example-main-view.png To create the main view: \list 1 \li In the \uicontrol Projects view (1), double-click the \e MainForm.ui.qml file to open it in \QMLD. \li In the \uicontrol Navigator (2), select the \uicontrol RowLayout and press \key Delete to delete it. \li In \uicontrol Library > \uicontrol {QML Types} (3), select \uicontrol SplitView and drag and drop it to the \uicontrol Item in the navigator. \li Select the split view in the navigator, then select the \uicontrol Layout tab in \uicontrol Properties (4), and then click the \inlineimage qmldesigner-anchor-fill-screen.png (\uicontrol {Fill to Parent}) button to anchor the split view to the item. \li Drag and drop a \uicontrol TableView and a \uicontrol {Tab View} from the library to the split view in the navigator. \li Select the \inlineimage qmldesigner-export-item-button.png (\uicontrol Export) button in the navigator to export the table view as a property. \li Right-click \uicontrol TabView to open the context menu and select \uicontrol {Add Tab} to create a Tab element. \QC creates the element as a separate QML file with the name that you enter in the dialog. By default, the element is called \uicontrol Tab. \li Select the tab in the navigator and enter \b {Customer Settings} in the \uicontrol Title field in the properties. \li Press \key Ctrl+C to copy the tab to the clipboard, and then press \key Ctrl+V twice to create two more tabs that you name \b {Customer Notes} and \b {Customer History}. \QC uses the \l Tab type in the \e MainForm.ui.qml file. You will create separate UI forms for the tab contents later. \endlist \section2 Editing the Table View \QMLD does not support adding columns to TableView types, and therefore, you must use the code editor to add them. To keep editing the \e MainForm.ui.qml file in the \uicontrol Edit mode to the minimum, move the TableView type to a separate QML file called \e CustomerTableView.qml: \list 1 \li Click \uicontrol Edit to open \e MainForm.ui.qml in \uicontrol Edit mode. \li To move the TableView type to a separate QML file, right-click it and select \uicontrol Refactoring > \uicontrol {Move Component into Separate File}. \li Add the code from the \l {uiforms/CustomerTableView.qml} {CustomerTableView.qml} example file to the file that \QC creates for you. \endlist \section1 Implementing the Application Logic for the Main View The new project wizard adds boilerplate code to the \e main.qml file to create menu items and push buttons. Modify the boilerplate code by removing obsolete code and by adding new code. You removed the push buttons from the UI Form, so you also need to remove the corresponding code from \e main.qml (or the application cannot be built). You will want to keep the dialog box and menu bar, but change their contents, as instructed later. Edit the \e main.qml file in the code editor, as described in the following sections. \section2 Specifying Main View Size The wizard creates an ApplicationWindow type and a MainForm type that specify the application main view. Enter the application name as the value of the \c title property. Clean up the MainForm code by removing the obsolete lines that call functions when buttons are clicked: \badcode MainForm { anchors.fill: parent button1.onClicked: messageDialog.show(qsTr("Button 1 pressed")) button2.onClicked: messageDialog.show(qsTr("Button 2 pressed")) } \endcode Remove the \c width and \c height properties from the ApplicationWindow type and use a Layout type in the MainForm type to set the minimum and preferred size of the main view. To use the Layouts, import QtQuick Layouts: \quotefromfile uiforms/main.qml \skipto QtQuick.Layouts \printline Layouts Then specify the following properties for the MainForm: \skipto MainForm \printuntil Layout.preferredHeight \section2 Creating the Table View Model Use a list model to display customer data in the table view. Because the list model is accessed from several different \e .qml files, access it through a singleton type defined in \e CustomerModelSingleton.qml and registered in \e main.cpp. This way, you do not have to rely on the QML context scoping rules to access the list model. \list 1 \li In the \uicontrol Projects view, right-click \uicontrol qml.qrc and select \uicontrol {Add New} > \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} to create the \e CustomerModelSingleton.qml file and to add it to the project. \li Copy the implementation from \l{uiforms/CustomerModelSingleton.qml} {CustomerModelSingleton.qml}. \li Add the following code to the MainForm in \e main.qml to access the list model: \quotefromfile uiforms/main.qml \skipto tableView1.model: CustomerModel \printuntil tableView1.selection \li To register the singleton type in the \e main.cpp file, include the Qt QML module and call the \c qmlRegisterSingletonType() function in the initialization function: \quotefromfile uiforms/main.cpp \dots \skipto QtQml \printuntil "CustomerModel"); \li To use the registered singleton type in \e main.qml, you must import the singleton type: \quotefromfile uiforms/main.qml \skipto my.customermodel.singleton \printline 1.0 \endlist \section1 Creating Tabs You can use the new file wizard to create UI forms that specify tab contents and functionality. You set the QML files as sources for the tabs in the \e MainForm.ui.qml file and modify the corresponding UI forms in the \uicontrol Design mode. \section2 Creating UI Forms for Tab Contents To create UI forms for the tab contents: \list 1 \li Select \uicontrol File > \uicontrol {New File or Project} > \uicontrol Qt > \uicontrol {QtQuick UI File} > \uicontrol Choose. \li In the \uicontrol {Component name} field, enter \b Settings. \li Click \uicontrol Next. \li Click \uicontrol Finish to create the UI form, \e SettingsForm.ui.qml, and a corresponding QML file, \e Settings.qml. \endlist Create the UI form, \e NotesForm.ui.qml, and the corresponding QML file, \e Notes.qml, for the notes tab in the same way. You will not need an \e ui.qml file for the history tab, so you will create the QML file for it later. \section2 Creating the Settings Tab The \uicontrol {Customer Settings} tab contains information about the selected user. \image qmldesigner-uiforms-example-settings-tab.png To create the tab contents: \list 1 \li Double-click \e SettingsForm.ui.qml in the \uicontrol Projects view to open it for editing in the \uicontrol Design mode. \li Select \uicontrol Item in the \uicontrol Navigator and enter \b content in the \uicontrol Id field in \uicontrol Properties. \li In \uicontrol Library, select \uicontrol Imports > \uicontrol {Add Import} and import Qt Quick Controls and Layouts to make the QML types in those modules visible in the library. \li Drag and drop a \uicontrol {Grid Layout} from the library to the \b content item in the navigator. \li Select \uicontrol Layout > \uicontrol Top, \uicontrol Left, and \uicontrol Right buttons to anchor the grid layout to the parent. \li In the \uicontrol Margin fields for the anchors, set the margins to \b 12. \li In \uicontrol Properties, set \uicontrol {Column spacing} and \uicontrol {Row spacing} to \b 8, \uicontrol Columns to \b 3, and \uicontrol Rows to \b 4. If you add more fields, add the necessary amount of rows. \li Drag and drop four \uicontrol Label controls, a \uicontrol {Combo Box}, and three \uicontrol {Text Field} controls from the library to the navigator. \li Use the down arrow in the navigator to move one label down to the position above the last text field. \li In the properties, change the label text for each field in the \uicontrol Text field. You need the following labels: \b Title, \b {First Name}, \b {Last Name}, and \b {Customer Id}. \li In the properties, change the placeholder text for each text field in the \uicontrol {Placeholder text} field to be the same as the field label. \li Select the customer ID text field, then select \uicontrol Layout in properties and set \uicontrol {Column span} to 3 and check \uicontrol {Fill width} to make the ID field span the length of the grid layout. \li Drag and drop a \uicontrol {Row Layout} from the library to the \b content item in the navigator and click on it. \li Reset the height of the row layout in properties. \image qmldesigner-uiforms-reset-height.png \li Select \uicontrol Layout > \uicontrol Bottom and \uicontrol Right buttons to anchor the row layout to the parent. \li In the \uicontrol Margin fields for the anchors, set the margins to \b 12. \li Drag and drop two \uicontrol Button controls from the library to the row layout in the navigator. \li In the properties, change the button labels in the \uicontrol Text field to \b Save and \b Cancel. \li Select \uicontrol Layout and > \uicontrol {Fill width} and \uicontrol {Fill height} in properties for each button to have the buttons fill the row layout. \li In the navigator, select \uicontrol Export for each field to export the field IDs as properties. The following items should be exported, so that they can be referred to in \e Settings.qml: \quotefromfile uiforms/SettingsForm.ui.qml \skipto property \printuntil title \endlist \section2 Creating the Notes Tab The \uicontrol {Customer Notes} tab contains a text area for entering notes about the selected customer and buttons for saving or canceling the changes. To create the tab contents: \list 1 \li Double-click \e NotesForm.ui.qml in the \uicontrol Projects view to open it for editing in the \uicontrol Design mode. \li Select \uicontrol Item in the \uicontrol Navigator and enter \b content in the \uicontrol Id field in \uicontrol Properties. \li In \uicontrol Library, select \uicontrol Imports > \uicontrol {Add Import} and import Qt Quick Controls and Layouts. \li Drag and drop a \uicontrol {Column Layout} from the library to the \b content item in the navigator. \li Select \uicontrol Layout > \uicontrol Top, \uicontrol Left, and \uicontrol Right buttons to anchor the grid layout to the parent and set the margins to \b 12. \li Drag and drop a \uicontrol {Text Area} from the library to the column layout. \li Select \uicontrol Layout and > \uicontrol {Fill width} and \uicontrol {Fill height} in properties to have the text area fill the column layout. \li Create the \uicontrol Save and \uicontrol Cancel buttons as instructed in \l {Creating the Settings Tab}. You can also copy and paste the row layout from SettingsForm.ui.qml. \li In the navigator, select \uicontrol Export for each field to export the field IDs as properties. The following items should be exported, so that they can be referred to in \e Notes.qml: \quotefromfile uiforms/NotesForm.ui.qml \skipto property \printuntil save \endlist \section2 Creating the History Tab The \uicontrol {Customer History} tab contains a table view that displays the transactions performed by the customer. Create a custom HistoryTableView type that you can edit in the \uicontrol Edit mode. For the history tab, you do not need an \e ui.qml file at all. To create the history tab: \list 1 \li In the \uicontrol Projects view, right-click \uicontrol qml.qrc and select \uicontrol {Add New} > \uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} to create the \e HistoryTableView.qml file and to add it to the project. \li Copy the implementation from \l{uiforms/HistoryTableView.qml} {HistoryTableView.qml}. \li Add the code from the example \l{uiforms/History.qml}{History.qml} file to your \e History.qml file to access the code model. \endlist \section1 Adding Tab Functionality Add functions for displaying data from the customer model in the tabs. You have already created the files that you need. You now need to copy the implementation for the settings tab from the \l {uiforms/Settings.qml} {Settings.qml} file and for the notes tab from the \l {uiforms/Notes.qml} {Notes.qml} file. To display the tab contents in the main view, set the QML files as sources for the tabs in the \uicontrol Design mode. Select the settings tab in the \uicontrol Navigator and specify for example \e Settings.qml in the \uicontrol Source field in the \uicontrol Properties view. Similarly, specify the sources for the notes and history tabs. You can then remove the \e Tab.qml file that the wizard generated but that you no longer need by selecting \uicontrol {Remove File} in the context menu. \section1 Creating Menus The wizard adds a menu bar to the \e main.qml file that contains a \uicontrol File menu with the \uicontrol Open and \uicontrol Exit menu items. Keep the menu and the \uicontrol Exit menu item, and add the \uicontrol Edit and \uicontrol Help menus with standard menu items. The wizard creates the following code: \badcode menuBar: MenuBar { Menu { title: qsTr("&File") MenuItem { text: qsTr("&Open") onTriggered: messageDialog.show(qsTr("Open action triggered")); } MenuItem { text: qsTr("E&xit") onTriggered: Qt.quit(); } } } \endcode Remove the \uicontrol Open menu item and add the following code to create the new menus: \quotefromfile uiforms/main.qml \skipto menuBar \printuntil activeFocusItem.paste \printuntil } \section1 Creating Dialogs \image qmldesigner-uiforms-example-about-dialog.png The wizard creates a message box in the \e main.qml file that you should turn into an \uicontrol About dialog for the purpose of this example: \badcode MessageDialog { id: messageDialog title: qsTr("May I have your attention, please?") function show(caption) { messageDialog.text = caption; messageDialog.open(); } \endcode Modify the code created by the wizard to add an icon and some text: \quotefromfile uiforms/main.qml \skipto MessageDialog \printuntil } Enable access to the \uicontrol About dialog from the \uicontrol Help menu that you create next. \section1 Running the Application The application is complete and ready to be run on the desktop or deployed to a device. To run the application, press \key {Ctrl+R}. */