From fc6e0155cc3fa9beb3b48704a1effe87a74c2779 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 20 May 2009 14:23:47 +0200 Subject: Doc: First attempt at a simpler widgets tutorial. Task-number: 253710 Reviewed-by: Trust Me --- doc/src/snippets/widgets-tutorial/template.cpp | 14 +++ doc/src/tutorials/widgets-tutorial.qdoc | 132 +++++++++++++++++++-- .../tutorials/widgets/childwidget/childwidget.pro | 7 ++ examples/tutorials/widgets/childwidget/main.cpp | 60 ++++++++++ examples/tutorials/widgets/nestedlayouts/main.cpp | 100 ++++++++++++++++ .../widgets/nestedlayouts/nestedlayouts.pro | 7 ++ examples/tutorials/widgets/toplevel/main.cpp | 56 +++++++++ examples/tutorials/widgets/toplevel/toplevel.pro | 7 ++ examples/tutorials/widgets/widgets.pro | 8 ++ examples/tutorials/widgets/windowlayout/main.cpp | 62 ++++++++++ .../widgets/windowlayout/windowlayout.pro | 7 ++ 11 files changed, 449 insertions(+), 11 deletions(-) create mode 100644 doc/src/snippets/widgets-tutorial/template.cpp create mode 100644 examples/tutorials/widgets/childwidget/childwidget.pro create mode 100644 examples/tutorials/widgets/childwidget/main.cpp create mode 100644 examples/tutorials/widgets/nestedlayouts/main.cpp create mode 100644 examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro create mode 100644 examples/tutorials/widgets/toplevel/main.cpp create mode 100644 examples/tutorials/widgets/toplevel/toplevel.pro create mode 100644 examples/tutorials/widgets/widgets.pro create mode 100644 examples/tutorials/widgets/windowlayout/main.cpp create mode 100644 examples/tutorials/widgets/windowlayout/windowlayout.pro diff --git a/doc/src/snippets/widgets-tutorial/template.cpp b/doc/src/snippets/widgets-tutorial/template.cpp new file mode 100644 index 0000000..5958676 --- /dev/null +++ b/doc/src/snippets/widgets-tutorial/template.cpp @@ -0,0 +1,14 @@ +#include + +// Include header files for application components. +// ... + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + // Set up and show widgets. + // ... + + return app.exec(); +} diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc index ead44af..1e89431 100644 --- a/doc/src/tutorials/widgets-tutorial.qdoc +++ b/doc/src/tutorials/widgets-tutorial.qdoc @@ -41,11 +41,14 @@ /*! \page widgets-tutorial.html + \startpage {index.html}{Qt Reference Documentation} + \nextpage {tutorials/widgets/toplevel}{Creating a Window} \title Widgets Tutorial \ingroup tutorials - \brief This tutorial covers basic usage of widgets and layouts, showing how they are used to build GUI applications. + \brief This tutorial covers basic usage of widgets and layouts, showing how + they are used to build GUI applications. \section1 Introduction @@ -68,7 +71,60 @@ occupied by its parent. This means that, when a window is deleted, all the widgets it contains are automatically deleted. - \section1 Creating a Window + \section1 Writing a main Function + + Many of the GUI examples in Qt follow the pattern of having a \c{main.cpp} + file containing code to initialize the application, and a number of other + source and header files containing the application logic and custom GUI + components. + + A typical \c main() function, written in \c{main.cpp}, looks like this: + + \quotefile doc/src/snippets/widgets-tutorial/template.cpp + + We first construct a QApplication object which is configured using any + arguments passed in from the command line. After any widgets have been + created and shown, we call QApplication::exec() to start Qt's event loop. + Control passes to Qt until this function returns, at which point we return + the value we obtain from this function. + + In each part of this tutorial, we provide an example that is written + entirely within a \c main() function. In more sophisticated examples, the + code to set up widgets and layouts is written in other parts of the + example. For example, the GUI for a main window may be set up in the + constructor of a QMainWindow subclass. + + The \l{Qt Examples#Widgets}{Widgets examples} are a good place to look for + more complex and complete examples and applications. + + \section1 Building Examples and Tutorials + + If you obtained a binary package of Qt or compiled it yourself, the + examples described in this tutorial should already be ready to run. + However, if you may wish to modify them and recompile them, you need to + perform the following steps: + + \list 1 + \o At the command line, enter the directory containing the example you + wish to recompile. + \o Type \c qmake and press \key{Return}. If this doesn't work, make sure + that the executable is on your path, or enter its full location. + \o On Linux/Unix and Mac OS X, type \c make and press \key{Return}; + on Windows with Visual Studio, type \c nmake and press \key{Return}. + \endlist + + An executable file should have been created within the current directory. + On Windows, this file may be located within a \c debug or \c release + subdirectory. You can run this file to see the example code at work. +*/ + +/*! + \page widgets-tutorial-toplevel.html + \contentspage {Widgets Tutorial}{Contents} + \previouspage {Widgets Tutorial} + \nextpage {Widgets Tutorial - Child Widgets} + \example tutorials/widgets/toplevel + \title Widgets Tutorial - Creating a Window If a widget is created without a parent, it is treated as a window, or \e{top-level widget}, when it is shown. Since it has no parent object to @@ -82,7 +138,7 @@
\endraw - \snippet snippets/widgets-tutorial/toplevel/main.cpp create, resize and show + \snippet tutorials/widgets/toplevel/main.cpp main program \raw HTML \endraw @@ -92,15 +148,28 @@
\endraw - We can add a child widget to this window by passing \c window as the - parent to its constructor. In this case, we add a button to the window - and place it in a specific location: + To create a real GUI, we need to place widgets inside the window. To do + this, we pass a QWidget instance to a widget's constructor, as we will + demonstrate in the next part of this tutorial. +*/ + +/*! + \page widgets-tutorial-childwidget.html + \contentspage {Widgets Tutorial}{Contents} + \previouspage {Widgets Tutorial - Creating a Window} + \nextpage {Widgets Tutorial - Using Layouts} + \example tutorials/widgets/childwidget + \title Widgets Tutorial - Child Widgets + + We can add a child widget to the window created in the previous example by + passing \c window as the parent to its constructor. In this case, we add a + button to the window and place it in a specific location: \raw HTML
\endraw - \snippet snippets/widgets-tutorial/childwidget/main.cpp create, position and show + \snippet tutorials/widgets/childwidget/main.cpp main program \raw HTML \endraw @@ -112,9 +181,16 @@ The button is now a child of the window and will be deleted when the window is destroyed. Note that hiding or closing the window does not - automatically destroy it. + automatically destroy it. It will be destroyed when the example exits. +*/ - \section1 Using Layouts +/*! + \page widgets-tutorial-windowlayout.html + \contentspage {Widgets Tutorial}{Contents} + \previouspage {Widgets Tutorial - Child Widgets} + \nextpage {Widgets Tutorial - Nested Layouts} + \example tutorials/widgets/windowlayout + \title Widgets Tutorial - Using Layouts Usually, child widgets are arranged inside a window using layout objects rather than by specifying positions and sizes explicitly. Here, we @@ -125,7 +201,7 @@
\endraw - \snippet snippets/widgets-tutorial/windowlayout/main.cpp create, lay out widgets and show + \snippet tutorials/widgets/windowlayout/main.cpp main program \raw HTML \endraw @@ -149,17 +225,31 @@ manage the label and line edit and set the layout on the window, both the widgets and the layout itself are ''reparented'' to become children of the window. +*/ + +/*! + \page widgets-tutorial-nestedlayouts.html + \contentspage {Widgets Tutorial}{Contents} + \previouspage {Widgets Tutorial - Using Layouts} + \example tutorials/widgets/nestedlayouts + \title Widgets Tutorial - Nested Layouts Just as widgets can contain other widgets, layouts can be used to provide different levels of grouping for widgets. Here, we want to display a label alongside a line edit at the top of a window, above a table view showing the results of a query. + We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout + that contains QLabel and QLineEdit widgets placed side-by-side; + \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a + QTableView arranged vertically. + \raw HTML
\endraw - \snippet snippets/widgets-tutorial/nestedlayouts/main.cpp create, lay out widgets and show + \snippet tutorials/widgets/nestedlayouts/main.cpp first part + \snippet tutorials/widgets/nestedlayouts/main.cpp last part \raw HTML \endraw @@ -169,6 +259,26 @@
\endraw + Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()} + function to insert the \c{queryLayout} above the \c{resultView} table. + + We have omitted the code that sets up the model containing the data shown + by the QTableView widget, \c resultView. For completeness, we show this below. + As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout and QFormLayout classes to help with more complex user interfaces. + These can be seen if you run \l{Qt Designer}. + + \section1 Setting up the Model + + In the code above, we did not show where the table's data came from + because we wanted to concentrate on the use of layouts. Here, we see + that the model holds a number of items corresponding to rows, each of + which is set up to contain data for two columns. + + \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model + + The use of models and views is covered in the + \l{Qt Examples#Item Views}{item view examples} and in the + \l{Model/View Programming} overview. */ diff --git a/examples/tutorials/widgets/childwidget/childwidget.pro b/examples/tutorials/widgets/childwidget/childwidget.pro new file mode 100644 index 0000000..37ae98e --- /dev/null +++ b/examples/tutorials/widgets/childwidget/childwidget.pro @@ -0,0 +1,7 @@ +SOURCES = main.cpp + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/childwidget +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS childwidget.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/childwidget +INSTALLS += target sources diff --git a/examples/tutorials/widgets/childwidget/main.cpp b/examples/tutorials/widgets/childwidget/main.cpp new file mode 100644 index 0000000..99235bd --- /dev/null +++ b/examples/tutorials/widgets/childwidget/main.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [main program] +#include + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QWidget *window = new QWidget(); + window->resize(320, 240); + window->setWindowTitle(tr("Child widget")); + window->show(); + +//! [create, position and show] + QPushButton *button = new QPushButton(tr("Press me"), window); + button->move(100, 100); + button->show(); +//! [create, position and show] + return app.exec(); +} +//! [main program] diff --git a/examples/tutorials/widgets/nestedlayouts/main.cpp b/examples/tutorials/widgets/nestedlayouts/main.cpp new file mode 100644 index 0000000..29996c6 --- /dev/null +++ b/examples/tutorials/widgets/nestedlayouts/main.cpp @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [main program] +//! [first part] +#include + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QWidget *window = new QWidget(); + + QLabel *queryLabel = new QLabel(tr("Query:")); + QLineEdit *queryEdit = new QLineEdit(); + QTableView *resultView = new QTableView(); + + QHBoxLayout *queryLayout = new QHBoxLayout(); + queryLayout->addWidget(queryLabel); + queryLayout->addWidget(queryEdit); + + QVBoxLayout *mainLayout = new QVBoxLayout(); + mainLayout->addLayout(queryLayout); + mainLayout->addWidget(resultView); + window->setLayout(mainLayout); + + // Set up the model and configure the view... +//! [first part] + +//! [set up the model] + QStandardItemModel model; + model.setHorizontalHeaderLabels(QStringList() << tr("Name") << tr("Office")); + + QList rows = QList() + << (QStringList() << "Verne Nilsen" << "123") + << (QStringList() << "Carlos Tang" << "77") + << (QStringList() << "Bronwyn Hawcroft" << "119") + << (QStringList() << "Alessandro Hanssen" << "32") + << (QStringList() << "Andrew John Bakken" << "54") + << (QStringList() << "Vanessa Weatherley" << "85") + << (QStringList() << "Rebecca Dickens" << "17") + << (QStringList() << "David Bradley" << "42") + << (QStringList() << "Knut Walters" << "25") + << (QStringList() << "Andrea Jones" << "34"); + + foreach (QStringList row, rows) { + QList items; + foreach (QString text, row) + items.append(new QStandardItem(text)); + model.appendRow(items); + } + + resultView->setModel(&model); + resultView->verticalHeader()->hide(); + resultView->horizontalHeader()->setStretchLastSection(true); +//! [set up the model] +//! [last part] + window->setWindowTitle(tr("Nested layouts")); + window->show(); + return app.exec(); +} +//! [last part] +//! [main program] diff --git a/examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro b/examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro new file mode 100644 index 0000000..a7f141c --- /dev/null +++ b/examples/tutorials/widgets/nestedlayouts/nestedlayouts.pro @@ -0,0 +1,7 @@ +SOURCES = main.cpp + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/nestedlayouts +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS nestedlayouts.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/nestedlayouts +INSTALLS += target sources diff --git a/examples/tutorials/widgets/toplevel/main.cpp b/examples/tutorials/widgets/toplevel/main.cpp new file mode 100644 index 0000000..c966037 --- /dev/null +++ b/examples/tutorials/widgets/toplevel/main.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [main program] +#include + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); +//! [create, resize and show] + QWidget *window = new QWidget(); + window->resize(320, 240); + window->show(); +//! [create, resize and show] + window->setWindowTitle(tr("Top-level widget")); + return app.exec(); +} +//! [main program] diff --git a/examples/tutorials/widgets/toplevel/toplevel.pro b/examples/tutorials/widgets/toplevel/toplevel.pro new file mode 100644 index 0000000..58d59c5 --- /dev/null +++ b/examples/tutorials/widgets/toplevel/toplevel.pro @@ -0,0 +1,7 @@ +SOURCES = main.cpp + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/toplevel +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS toplevel.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/toplevel +INSTALLS += target sources diff --git a/examples/tutorials/widgets/widgets.pro b/examples/tutorials/widgets/widgets.pro new file mode 100644 index 0000000..7a870e7 --- /dev/null +++ b/examples/tutorials/widgets/widgets.pro @@ -0,0 +1,8 @@ +TEMPLATE = subdirs +SUBDIRS = toplevel childwidget windowlayout nestedlayouts + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS widgets.pro README +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets +INSTALLS += target sources diff --git a/examples/tutorials/widgets/windowlayout/main.cpp b/examples/tutorials/widgets/windowlayout/main.cpp new file mode 100644 index 0000000..d7c75a3 --- /dev/null +++ b/examples/tutorials/widgets/windowlayout/main.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [main program] +#include + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QWidget *window = new QWidget(); +//! [create, lay out widgets and show] + QLabel *label = new QLabel(tr("Name:")); + QLineEdit *lineEdit = new QLineEdit(); + + QHBoxLayout *layout = new QHBoxLayout(); + layout->addWidget(label); + layout->addWidget(lineEdit); + window->setLayout(layout); +//! [create, lay out widgets and show] + window->setWindowTitle(tr("Window layout")); + window->show(); + return app.exec(); +} +//! [main program] diff --git a/examples/tutorials/widgets/windowlayout/windowlayout.pro b/examples/tutorials/widgets/windowlayout/windowlayout.pro new file mode 100644 index 0000000..408f6ef --- /dev/null +++ b/examples/tutorials/widgets/windowlayout/windowlayout.pro @@ -0,0 +1,7 @@ +SOURCES = main.cpp + +# install +target.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/windowlayout +sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS windowlayout.pro +sources.path = $$[QT_INSTALL_EXAMPLES]/tutorials/widgets/windowlayout +INSTALLS += target sources -- cgit v0.12