/**************************************************************************** ** ** Application example documentation ** ** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. ** ** This file is part of the Qt GUI Toolkit. ** ** This file may be used under the terms of the GNU General ** Public License versions 2.0 or 3.0 as published by the Free ** Software Foundation and appearing in the files LICENSE.GPL2 ** and LICENSE.GPL3 included in the packaging of this file. ** Alternatively you may (at your option) use any later version ** of the GNU General Public License if such license has been ** publicly approved by Trolltech ASA (or its successors, if any) ** and the KDE Free Qt Foundation. ** ** Please review the following information to ensure GNU General ** Public Licensing retquirements will be met: ** http://trolltech.com/products/qt/licenses/licensing/opensource/. ** If you are unsure which license is appropriate for your use, please ** review the following information: ** http://trolltech.com/products/qt/licenses/licensing/licensingoverview ** or contact the sales department at sales@trolltech.com. ** ** This file may be used under the terms of the Q Public License as ** defined by Trolltech ASA and appearing in the file LICENSE.QPL ** included in the packaging of this file. Licensees holding valid Qt ** Commercial licenses may use this file in accordance with the Qt ** Commercial License Agreement provided with the Software. ** ** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, ** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR ** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted ** herein. ** **********************************************************************/ /*! \page simple-application.html \ingroup step-by-step-examples \title Walkthrough: A Simple Application This walkthrough shows simple use of \l QMainWindow, \l QMenuBar, \l QPopupMenu, \l QToolBar and \l QStatusBar - classes that every modern application window tends to use. (See also \link tutorial2.html Tutorial #2\endlink.) It also illustrates some aspects of \l QWhatsThis (for simple help) and a typical \c main() using \l QApplication. Finally, it shows a typical print function based on \l QPrinter. \section1 The declaration of ApplicationWindow Here's the header file in full: \include application/application.h It declares a class that inherits \l QMainWindow, with slots and private variables. The class pre-declaration of \l QTextEdit at the beginning (instead of an include) helps to speed up compilation. With this trick, \c{make depend} won't insist on recompiling every \c .cpp file that includes \c application.h when \c qtextedit.h changes. \target simplemain \section1 A simple main() Here is \c main.cpp in full: \include application/main.cpp Now we'll look at \c main.cpp in detail. \quotefile application/main.cpp \skipto argc \printline argc \printline QApplication With the above line, we create a QApplication object with the usual constructor and let it parse \e argc and \e argv. QApplication itself takes care of X11-specific command-line options like \e -geometry, so the program will automatically behave the way X clients are expected to. \printline ApplicationWindow \printline setCaption \printline show We create an \e ApplicationWindow as a top-level widget, set its window system caption to "Document 1", and \e show() it. \target close \printline connect When the application's last window is closed, it should tquit. Both the signal and the slot are predefined members of QApplication. \printline exec Having completed the application's initialization, we start the main event loop (the GUI), and eventually return the error code that QApplication returns when it leaves the event loop. \printline } \target ApplicationWindow \section1 The Implementation of ApplicationWindow \quotefile application/application.cpp Since the implementation is tquite large (almost 300 lines) we won't list the whole thing. (The source code is included in the examples/application directory.) Before we start with the constructor there are three \c{#include}s worth mentioning: \skipto "filesave.xpm" \printuntil "fileprint.xpm" The tool buttons in our application wouldn't look good without icons! These icons can be found in the XPM files included above. If you ever moved a program to a different location and wondered why icons were missing afterwards you will probably agree that it is a good idea to compile them into the binary. This is what we are doing here. \skipto ApplicationWindow::ApplicationWindow \printline ApplicationWindow::ApplicationWindow \printuntil { \e ApplicationWindow inherits QMainWindow, the Qt class that provides typical application main windows, with menu bars, toolbars, etc. \printuntil QPrinter The application example can print things, and we chose to have a QPrinter object lying around so that when the user changes a setting during one printing, the new setting will be the default next time. \printline QPixmap For the sake of simplicity, our example only has a few commands in the toolbar. The above variables are used to hold an icon for each of them. \printline QToolBar We create a toolbar in \e this window ... \printline "File Operations" ... and define a title for it. When a user drags the toolbar out of its location and floats it over the desktop, the toolbar-window will show "File Operations" as caption. \printline fileopen \printuntil SLOT(choose()) Now we create the first tool button for the \e fileTools toolbar with the appropriate icon and the tool-tip text "Open File". The \c fileopen.xpm we included at the beginning contains the definition of a pixmap called \e fileopen. We use this icon to illustrate our first tool button. \printuntil SLOT(print()) In a similar way we create two more tool buttons in this toolbar, each with appropriate icons and tool-tip text. All three buttons are connected to appropriate slots in this object; for example, the "Print File" button to \link #printer ApplicationWindow::print()\endlink. \printline whatsThisButton The fourth button in the toolbar is somewhat peculiar: it's the one that provides "What's This?" help. This must be set up using a special function, as its mouse interface is unusual. \printuntil fileOpenText ) With the above line we add the "What's This?" help-text to the \e fileOpen button... \printline openIcon ... and tell the rich-text engine that when a help-text (like the one saved in \e fileOpenText) requests an image named "fileopen", the \e openIcon pixmap is used. \printuntil fileSaveText ) \printuntil filePrintText ) The "What's This?" help of the remaining two buttons doesn't make use of pixmaps, therefore all we need to do is to add the help-text to the button. Be careful though: To invoke the rich-text elements in \c fileSaveText(), the entire string must be surrounded by \<p\> and \</p\>. In \c filePrintText(), we don't have rich-text elements, so this is not necessary. \printuntil &File Next we create a \l QPopupMenu for the \e File menu and add it to the menu bar. With the ampersand in front of the letter F, we allow the user to use the shortcut \e Alt+F to pop up this menu. \printline &New Its first entry is connected to the (yet to be implemented) slot \c newDoc(). When the user chooses this \e New entry (e.g. by typing the letter N as marked by the ampersand) or uses the \e Ctrl+N accelerator, a new editor-window will pop up. \printuntil &Open \printuntil &Save \printuntil Save &As \printuntil fileSaveText We populate the \e File menu with three more commands (\e Open, \e Save and \e{Save As}), and set "What's This?" help for them. Note in particular that "What's This?" help and pixmaps are used in both the toolbar (above) and the menu bar (here). (See QAction and the \c examples/action example for a shorter and easier approach.) \printline insertSeparator( Then we insert a separator, ... \printline &Print \printuntil &Close \printline &Quit ... the \e Print command with "What's This?" help, another separator and two more commands (\e Close and \e Quit) without "What's This?" and pixmaps. In case of the \e Close command, the signal is connected to the \e close() slot of the respective \e ApplicationWindow object whilst the \e Quit command affects the entire application. Because \e ApplicationWindow is a QWidget, the \e close() function triggers a call to \link #closeEvent closeEvent()\endlink which we will implement later. \target common_constructor \printline insertSeparator Now that we have done the File menu we shift our focus back to the menu bar and insert a separator. From now on further menu bar entries will be aligned to the right if the windows system style retquires it. \printline help \printuntil whatsThis We create a \e Help menu, add it to the menu bar, and insert a few commands. Depending on the style it will appear on the right hand side of the menu bar or not. \printline QTextEdit \printline setFocus \printline setCentralWidget Now we create a simple text-editor, set the initial focus to it, and make it the window's central widget. \l QMainWindow::centralWidget() is the heart of the entire application: It's what menu bar, statusbar and toolbars are all arranged around. Since the central widget is a text editing widget, we can now reveal that our simple application is a text editor. :) \printline "Ready" We make the statusbar say "Ready" for two seconds at startup, just to tell the user that the window has finished initialization and can be used. \printline resize Finally it's time to resize the new window to a a nice default size. \printline } We have now finished with the constructor. Now we'll deal with the destructor. \printline ::~ \printuntil } The only thing an \e ApplicationWindow widget needs to do in its destructor is to delete the printer it created. All other objects are child widgets, which Qt will delete when appropriate. Now our task is to implement all the slots mentioned in the header file and used in the constructor. \target newDoc() \printline ::newDoc \printuntil } This slot, connected to the \e{File|New} menu item, simply creates a new \e ApplicationWindow and shows it. \target choose() \printline ::choose \printuntil getOpenFileName \printuntil } The \e choose() slot is connected to the \e Open menu item and tool button. With a little help from \l QFileDialog::getOpenFileName(), it asks the user for a file name and then either loads that file or gives an error message in the statusbar. \printline ::load \printuntil statusBar \printline } This function loads a file into the editor. When it's done, it sets the window system caption to the file name and displays a success message in the statusbar for two seconds. With files that exist but are not readable, nothing happens. \target save() \printline ::save \printuntil close As its name suggests, this function saves the current file. If no filename has been specified so far, the \link #saveAs() saveAs()\endlink function is called. Unwritable files cause the \e ApplicationWindow object to provide an error-message in the statusbar. Note that there is more than one way to do this: compare the above \c{statusBar()->message()} line with the equivalent code in the \c load() function. \printline setModified Tell the editor that the contents haven't been edited since the last save. When the user does some further editing and wishes to close the window without explicit saving, \link #closeEvent ApplicationWindow::closeEvent()\endlink will ask about it. \printline setCaption It may be that the document was saved under a different name than the old caption suggests, so we set the window caption just to be sure. \printuntil } With a message in the statusbar, we inform the user that the file was saved successfully. \target saveAs() \printline ::saveAs \printuntil message \printline } \printline } This function asks for a new name, saves the document under that name, and implicitly changes the window system caption to the new name. \target printer \skipto ::print \printuntil aborted \printuntil aborted \printline } \printline } \e print() is called by the \e{File|Print} menu item and the \e filePrint tool button. We present the user with the print setup dialog, and abandon printing if they cancel. We create a QSimpleRichText object and give it the text. This object is able to format the text nicely as one long page. We achieve pagination by printing one paper page's worth of text from the QSimpleRichText page at a time. Now let's see what happens when a user wishes to \e close() an \e ApplicationWindow. \target closeEvent \printline ::closeEvent \printline { This event gets to process window system close events. A close event is subtly different from a hide event: hide often means "iconify" whereas close means that the window is going away for good. \printline isModified \printline accept \printline return \printline } If the text hasn't been edited, we just accept the event. The window will be closed, and because we used the \e WDestructiveClose widget flag in the \link #ApplicationWindow <i>ApplicationWindow()</i> constructor\endlink, the widget will be deleted. \printline QMessageBox \printuntil { Otherwise we ask the user: What do you want to do? \printuntil break If they want to save and then exit, we do that. \printuntil break If the user doesn't want to exit, we ignore the close event (there is a chance that we can't block it but we try). \printuntil break The last case -- the user wants to abandon the edits and exit -- is very simple. \printline } \printline } Last but not least we implement the slots used by the help menu entries. \printline ::about \printuntil aboutQt \printuntil } These two slots use ready-made "about" functions to provide some information about this program and the GUI toolkit it uses. (Although you don't need to provide an About Qt in your programs, if you use Qt for free we would appreciate it if you tell people what you're using.) That was all we needed to write a complete, almost useful application with nice help-functions, almost as good as the "editors" some computer vendors ship with their desktops, and in less than 300 lines of code! */