/****************************************************************************
** $Id:  qt/application-walkthrough.doc   3.0.3   edited Oct 12 12:18 $
**
** Application example documentation
**
** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be distributed under the terms of the Q Public License
** as defined by Trolltech AS of Norway and appearing in the file
** LICENSE.QPL included in the packaging of this file.
**
** This file may be distributed and/or modified under the terms of the
** GNU General Public License version 2 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.
**
** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
** 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
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
**   information about Qt Commercial License Agreements.
** See http://www.trolltech.com/qpl/ for QPL licensing information.
** See http://www.trolltech.com/gpl/ for GPL licensing information.
**
** Contact info@trolltech.com if any conditions of this licensing are
** not clear to you.
**
**********************************************************************/

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

It further illustrates some aspects of \l QWhatsThis (for simple help) and a
typical \e main() using \l QApplication.

Finally, it shows a typical printout function based on \l QPrinter.

<h2>The declaration of ApplicationWindow</h2>

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 predeclaration of \l QTextEdit at the beginning
(instead of an include) helps to speed up compiles.  With this trick, make
depend won't insist on recompiling every \e .cpp file that includes \e
application.h when \e qtextedit.h changes.

<a name="simplemain"></a>
<h2>A simple main()</h2>

Let's first have a look at \e examples/main.cpp, in full ...

\include application/main.cpp

... and go over \e main() 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, thus the program automatically
behaves 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.

<a name="close"></a>
\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 }

<a name="ApplicationWindow"></a>
<h2>The Implementation of ApplicationWindow</h2>

\quotefile application/application.cpp

Since the implementation is quite large (almost 300 lines) we 
won't bore you with the preliminary headerfile \e #includes. Before we 
start with the constructor there are however three \e #include lines
worth mentioning:

\skipto "filesave.xpm"
\printuntil "fileprint.xpm"

The tool buttons in our application wouldn't be real without icons.
These icons can be found in the above xpm files. 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 simplicity reasons, our example has no more than three 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 drops it somewhere on 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 \e fileopen.xpm we included at the beginning 
contains the definition of a pixmap named \e fileopen.
This we use as the icon to illustrate our first tool button.  

\printuntil SLOT(print())

Likewise 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 <A HREF="#printer">\e ApplicationWindow::print()</A>.

\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 different from usual.

\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 have to do is to add the help-text to the button.
Be however careful: To invoke the rich-text elements in \e fileSaveText,
the entire string must be surrounded by \<p\> and \</p\>. In \e 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 previous to the letter F,
we allow the user to use the shortcut \e Alt+F to open this menu.

\printline &New

Its first entry is connected to the (yet to be implementled) slot \e
newDoc(). When the user chooses this \e New entry (e.g. via 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).

\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 <A HREF="#closeEvent">\e closeEvent()</A> which we will
implement later.

<A NAME="common_constructor"></A>
\printline insertSeparator

Now that we are done with 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 
suggests so.

\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 central widget of this window.

\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 reveal at this line 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 this 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 }

At this stage, we are done with the constructor. Among others we have learned 
about the classic way of creating menus and toolbars. There is
however a more modern approach to deal with this: actions that
help you saving some work. You may
have a look at how the \e ApplicationWindow constructor is implemented
using 
<A HREF="simple-application-action.html">actions</A>. Here
we'll continue 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 as appropriate.

Now our task is to implement all the slots mentioned in the header file
and used in the constructor.

<A NAME="newDoc()"></A>
\printline ::newDoc
\printuntil }

This slot, connected to the \e File->New menu item, simply creates a 
new \e ApplicationWindow and shows it.

<A NAME="choose()"></A>
\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.

<A NAME="save()"></A>
\printline ::save
\printuntil close

As its name suggests, this function saves the current file. 
If no filename has been
specified so far, the <A HREF="#saveAs()">\e saveAs()</A> routine is called. 
Unwritable files cause the \e ApplicationWindow object to provide
an error-message in the statusbar. Note that there are more than
one possibilities 
to achieve this: compare the above \e statusBar()->message() line 
with the appropriate code in the \e 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, 
<A HREF="#closeEvent">\e ApplicationWindow::closeEvent()</A>  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.

<A NAME="saveAs()"></A>
\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.

<a name="printer"></a>

\printuntil {
\skipto Margin
\printuntil pageNo

\e print() is called by the \e File->Print menu item and the \e filePrint 
tool button.

Because we don't want to print to the very edges of the paper, we use a
little margin: 10 points.  Furthermore we keep track of the page count.

\printline setup

\l QPrinter::setup() invokes a print dialog, configures the printer
object, and returns TRUE if the user wants to print or FALSE if not.
So we test the return value; if it's TRUE, we...

\printline message

... set a statusbar message in case printing takes a while.

\printline QPainter
\printuntil return

We create a painter for the output and decide that we wish to paint
on the printer or do nothing at all.

\printuntil surface

Then we select the font our \l QTextEdit object returns as its current
one, and set up some variables we'll need.

\printline for

As long as the editing widget contains more lines, we want to print them.

\printline if

Before we print a line, we make sure that there is space for it on 
the current page.  If not, we start a new page:

\printline QString
\printuntil yPos

(Four lines to tell the user what we're doing, two lines to do it.)

\printline }

Now we know that there's space for the current line ...

\printuntil DontClip
\printuntil e->text(

... and we use the painter to print it. 

In Qt, output to printers uses the exact same code as output to screen,
pixmaps and picture metafiles.  Therefore, we don't call a QPrinter
function to draw text, but a QPainter function.  QPainter works on all the
output devices mentioned and has a device independent API.  Most of its
code is device independent, too, therefore it is less likely that your
application will have odd bugs.  (If the same code is used to print and to
draw on the screen, it's less likely that you'll have print-only or
screen-only bugs.)

\printline yPos

With this line, we keep count of how much of the paper we've used
so far.

\printline }
\printline end

At this point we've printed all of the text in the editing widget 
and told the printer to finish off the last page. 

\printline message

Finally the user receives the message that we're done.

\printline else
\printline message
\printline }

If the user did not want to print (and \l QPrinter::setup() returned
FALSE), we inform him or her about it.

\printline }

With this little effort we have printed a text document.
So let's care about what happens when a user wishes to \e close()
an \e ApplicationWindow.

<a name="closeEvent"></a>
\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 \e ApplicationWindow() constructor\endlink, 
the widget will be deleted.

\printline QMessageBox
\printuntil {

Otherwise we ask the user: What do you want
to do?  

\printuntil break

If he/she wants to save and then exit, we do that.  


\printuntil break

If the user however 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, in less than 300 lines of code. As we promised -
a simple application.

*/