diff options
Diffstat (limited to 'doc/src/getting-started/gettingstarted.qdoc')
| -rw-r--r-- | doc/src/getting-started/gettingstarted.qdoc | 491 |
1 files changed, 6 insertions, 485 deletions
diff --git a/doc/src/getting-started/gettingstarted.qdoc b/doc/src/getting-started/gettingstarted.qdoc index 9b6b5d5..145982b 100644 --- a/doc/src/getting-started/gettingstarted.qdoc +++ b/doc/src/getting-started/gettingstarted.qdoc @@ -26,491 +26,12 @@ ****************************************************************************/ /*! - \page gettingstarted.html + \title Getting Started Guides - \title Getting Started - - Welcome to the world of Qt--the cross-platform GUI toolkit. In - this getting started guide, we teach basic Qt knowledge by - implementing a simple Notepad application. After reading this - guide, you should be ready to delve into our overviews and API - documentation, and find the information you need for the - application you are developing. - - \section1 Hello Notepad - - In this first example, we simply create and show a text edit in a - window frame on the desktop. This represents the simplest possible - Qt program that has a GUI. - - \image gs1.png - - Here is the code: - - \code - 1 #include <QApplication> - 2 #include <QTextEdit> - 3 - 4 int main(int argv, char **args) - 5 { - 6 QApplication app(argv, args); - 7 - 8 QTextEdit textEdit; - 9 textEdit.show(); -10 -11 return app.exec(); -12 } - \endcode - - Let us go through the code line by line. In the first two lines, we - include the header files for QApplication and QTextEdit, which are - the two classes that we need for this example. All Qt classes have - a header file named after them. - - Line 6 creates a QApplication object. This object manages - application-wide resources and is necessary to run any Qt program - that has a GUI. It needs \c argv and \c args because Qt accepts a - few command line arguments. - - Line 8 creates a QTextEdit object. A text edit is a visual element - in the GUI. In Qt, we call such elements widgets. Examples of - other widgets are scroll bars, labels, and radio buttons. A widget - can also be a container for other widgets; a dialog or a main - application window, for example. - - Line 9 shows the text edit on the screen in its own window frame. - Since widgets also function as containers (for instance a - QMainWindow, which has toolbars, menus, a status bar, and a few - other widgets), it is possible to show a single widget in its own - window. Widgets are not visible by default; the function - \l{QWidget::}{show()} makes the widget visible. - - Line 11 makes the QApplication enter its event loop. When a Qt - application is running, events are generated and sent to the - widgets of the application. Examples of events are mouse presses - and key strokes. When you type text in the text edit widget, it - receives key pressed events and responds by drawing the text - typed. - - To run the application, open a command prompt, and enter the - directory in which you have the \c .cpp file of the program. The - following shell commands build the program. - - \code - qmake -project - qmake - make - \endcode - - This will leave an executable in the \c part1 directory (note that - on Windows, you may have to use \c nmake instead of \c make. Also, - the executable will be placed in part1/debug or part1/release). \c - qmake is Qt's build tool, which takes a configuration file. \c - qmake generates this for us when given the \c{-project} argument. - Given the configuration file (suffixed .pro), \c qmake produces a - \c make file that will build the program for you. We will look - into writing our own \c .pro files later. - - \section2 Learn More - - \table - \header - \o About - \o Here - \row - \o Widgets and Window Geometry - \o \l{Window and Dialog Widgets} - \row - \o Events and event handling - \o \l{The Event System} - \endtable - - \section1 Adding a Quit Button - - In a real application, you will normally need more than one - widget. We will now introduce a QPushButton beneath the text edit. - The button will exit the Notepad application when pushed (i.e., - clicked on with the mouse). - - \image gs2.png - - Let us take a look at the code. - - \code - 1 #include <QtGui> - 2 - 3 int main(int argv, char **args) - 4 { - 5 QApplication app(argv, args); - 6 - 7 QTextEdit textEdit; - 8 QPushButton quitButton("Quit"); - 9 -10 QObject::connect(&quitButton, SIGNAL(clicked()), qApp, SLOT(quit())); -11 -12 QVBoxLayout layout; -13 layout.addWidget(&textEdit); -14 layout.addWidget(&quitButton); -15 -16 QWidget window; -17 window.setLayout(&layout); -18 -19 window.show(); -20 -21 return app.exec(); -22 } - \endcode - - Line 1 includes QtGui, which contains all of Qt's GUI classes. - - Line 10 uses Qt's Signals and Slots mechanism to make the - application exit when the \gui {Quit button} is pushed. A slot is - a function that can be invoked at runtime using its name (as a - literal string). A signal is a function that when called will - invoke slots registered with it; we call that to connect the slot - to the signal and to emit the signal. - - \l{QApplication::}{quit()} is a slot of QApplication that exits - the application. \l{QPushButton::}{clicked()} is a signal that - QPushButton emits when it is pushed. The static - QObject::connect() function takes care of connecting the slot to - the signal. SIGNAL() and SLOT() are two macros that take the - function signatures of the signal and slot to connect. We also - need to give pointers to the objects that should send and receive - the signal. - - Line 12 creates a QVBoxLayout. As mentioned, widgets can contain - other widgets. It is possible to set the bounds (the location and - size) of child widgets directly, but it is usually easier to use a - layout. A layout manages the bounds of a widget's children. - QVBoxLayout, for instance, places the children in a vertical row. - - Line 13 and 14 adds the text edit and button to the layout. In - line 17, we set the layout on a widget. - - \section2 Learn More - - \table - \header - \o About - \o Here - \row - \o Signals and slots - \o \l{Signals & Slots} - \row - \o Layouts - \o \l{Layout Management}, - \l{Widgets and Layouts}, - \l{Layout Examples} - \row - \o The widgets that come with Qt - \o \l{Qt Widget Gallery}, - \l{Widget Examples} - \endtable - - \section1 Subclassing QWidget - - When the user wants to quit an application, you might want to - pop-up a dialog that asks whether he/she really wants to quit. In - this example, we subclass QWidget, and add a slot that we connect - to the \gui {Quit button}. - - \image gs3.png - - Let us look at the code: - - \code - 5 class Notepad : public QWidget - 6 { - 7 Q_OBJECT - 8 - 9 public: -10 Notepad(); -11 -12 private slots: -13 void quit(); -14 -15 private: -16 QTextEdit *textEdit; -17 QPushButton *quitButton; -18 }; - \endcode - - The \c Q_OBJECT macro must be first in the class definition, and - declares our class as a \c QObject (Naturally, it must also - inherit from QObject). A \l{QObject} adds several abilities to a - normal C++ class. Notably, the class name and slot names can be - queried at run-time. It is also possible to query a slot's - parameter types and invoke it. - - Line 13 declares the slot \c quit(). This is easy using the \c - slots macro. The \c quit() slot can now be connected to signals - with a matching signature (any signal that takes no parameters). - - Instead of setting up the GUI and connecting the slot in the \c - main() function, we now use \c{Notepad}'s constructor. - - \code - Notepad::Notepad() - { - textEdit = new QTextEdit; - quitButton = new QPushButton(tr("Quit")); - - connect(quitButton, SIGNAL(clicked()), this, SLOT(quit())); - - QVBoxLayout *layout = new QVBoxLayout; - layout->addWidget(textEdit); - layout->addWidget(quitButton); - - setLayout(layout); - - setWindowTitle(tr("Notepad")); - } - \endcode - - As you saw in the class definition, we use pointers to our \l - {QObject}s (\c textEdit and \c quitButton). As a rule, you should - always allocate \l{QObject}s on the heap and never copy them. - - We now use the function \l{QObject::}{tr()} around our user - visible strings. This function is necessary when you want to - provide your application in more than one language (e.g. English - and Chinese). We will not go into details here, but you can follow - the \c {Qt Linguist} link from the learn more table. - - \section2 Learn More - - \table - \header - \o About - \o Here - \row - \o tr() and internationalization - \o \l{Qt Linguist Manual}, - \l{Writing Source Code for Translation}, - \l{Hello tr() Example}, - \l{Internationalization with Qt} - \row - \o QObjects and the Qt Object model (This is essential to understand Qt) - \o \l{Object Model} - \row - \o qmake and the Qt build system - \o \l{qmake Manual} - \endtable - - \section2 Creating a .pro file - - For this example, we write our own \c .pro file instead of - using \c qmake's \c -project option. - - \code - HEADERS = notepad.h - SOURCES = notepad.cpp \ - main.cpp - \endcode - - The following shell commands build the example. - - \code - qmake - make - \endcode - - \section1 Using a QMainWindow - - Many applications will benefit from using a QMainWindow, which has - its own layout to which you can add a menu bar, dock widgets, tool - bars, and a status bar. QMainWindow has a center area that can be - occupied by any kind of widget. In our case, we will place our - text edit there. - - \image gs4.png - - Let us look at the new \c Notepad class definition. - - \code - #include <QtGui> - - class Notepad : public QMainWindow - { - Q_OBJECT - - public: - Notepad(); - - private slots: - void open(); - void save(); - void quit(); - - private: - QTextEdit *textEdit; - - QAction *openAction; - QAction *saveAction; - QAction *exitAction; - - QMenu *fileMenu; - }; - \endcode - - We include two more slots that can save and open a document. We - will implement these in the next section. - - Often, in a main window, the same slot should be invoked by - several widgets. Examples are menu items and buttons on a tool - bar. To make this easier, Qt provides QAction, which can be given - to several widgets, and be connected to a slot. For instance, both - QMenu and QToolBar can create menu items and tool buttons from the - same \l{QAction}s. We will see how this works shortly. - - As before, we use the \c {Notepad}s constructor to set up the - GUI. - - \code - Notepad::Notepad() - { - saveAction = new QAction(tr("&Open"), this); - saveAction = new QAction(tr("&Save"), this); - exitAction = new QAction(tr("E&xit"), this); - - connect(openAction, SIGNAL(triggered()), this, SLOT(open())); - connect(saveAction, SIGNAL(triggered()), this, SLOT(save())); - connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit())); - - fileMenu = menuBar()->addMenu(tr("&File")); - fileMenu->addAction(openAction); - fileMenu->addAction(saveAction); - fileMenu->addSeparator(); - fileMenu->addAction(exitAction); - - textEdit = new QTextEdit; - setCentralWidget(textEdit); - - setWindowTitle(tr("Notepad")); - } - \endcode - - \l{QAction}s are created with the text that should appear on the - widgets that we add them to (in our case, menu items). If we also - wanted to add them to a tool bar, we could have given - \l{QIcon}{icons} to the actions. - - When a menu item is clicked now, the item will trigger the action, - and the respective slot will be invoked. - - \section2 Learn More - - \table - \header - \o About - \o Here - \row - \o Main windows and main window classes - \o \l{Application Main Window}, - \l{Main Window Examples} - \row - \o MDI applications - \o QMdiArea, - \l{MDI Example} - \endtable - - \section1 Saving and Loading - - In this example, we will implement the functionality of the \c - open() and \c save() slots that we added in the previous example. - - \image gs5.png - - We will start with the \c open() slot: - - \code - QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "", - tr("Text Files (*.txt);;C++ Files (*.cpp *.h)")); - - if (fileName != "") { - QFile file(fileName); - if (!file.open(QIODevice::ReadOnly)) { - QMessageBox::critical(this, tr("Error"), - tr("Could not open file")); - return; - } - QString contents = file.readAll().constData(); - textEdit->setPlainText(contents); - file.close(); - } - \endcode - - The first step is asking the user for the name of the file to - open. Qt comes with QFileDialog, which is a dialog from which the - user can select a file. The image above shows the dialog on - Kubuntu. The static \l{QFileDialog::}{getOpenFileName()} function - displays a modal file dialog, and does not return until the user - has selected a file. It returns the file path of the file - selected, or an empty string if the user canceled the dialog. - - If we have a file name, we try to open the file with - \l{QIODevice::}{open()}, which returns true if the file could be - opened. We will not go into error handling here, but you can follow - the links from the learn more section. If the file could not be - opened, we use QMessageBox to display a dialog with an error - message (see the QMessageBox class description for further - details). - - Actually reading in the data is trivial using the - \l{QIODevice::}{readAll()} function, which returns all data in the - file in a QByteArray. The \l{QByteArray::}{constData()} returns all - data in the array as a const char*, which QString has a - constructor for. The contents can then be displayed in the text - edit. We then \l{QIODevice::}{close()} the file to return the file - descriptor back to the operating system. - - Now, let us move on to the the \c save() slot. - - \code - QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "", - tr("Text Files (*.txt);;C++ Files (*.cpp *.h)")); - - if (fileName != "") { - QFile file(fileName); - if (!file.open(QIODevice::WriteOnly)) { - // error message - } else { - QTextStream stream(&file); - stream << textEdit->toPlainText(); - stream.flush(); - file.close(); - } - } - \endcode - - When we write the contents of the text edit to the file, we use - the QTextStream class, which wraps the QFile object. The text - stream can write QStrings directly to the file; QFile only accepts - raw data (char*) with the \l{QIODevice::}{write()} functions of - QIODevice. - - \section2 Learn More - - \table - \header - \o About - \o Here - \row - \o Files and I/O devices - \o QFile, QIODevice - \endtable - - \omit - \section1 Moving On - - This may not be true for the first release. - The Qt documentation comes with three getting started guides. You - have come to the end of the first, which concerns itself with - basic Qt concepts. We also have guides covering intermediate and - advanced topics. They are found here: You may also have noticed that the learn more sections in - this guide frequently linked to them. - Basic Qt Architecture - \endomit + \group gettingStarted + + Following is a list. + \generatelist{related} + */ |