|
|
|
/****************************************************************************
|
|
|
|
**
|
|
|
|
** 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 requirements 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 ntqtextedit.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 requires 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 aboutTQt
|
|
|
|
\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!
|
|
|
|
|
|
|
|
*/
|