tqt3/doc/application-walkthrough.doc

/****************************************************************************
**
** 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 quit. 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 quite 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!

*/