1 files changed, 435 insertions, 0 deletions
diff --git a/doc/application-walkthrough.doc b/doc/application-walkthrough.doc
new file mode 100644
index 000000000..e3a5aa6a8
--- /dev/null
+++ b/doc/application-walkthrough.doc
@@ -0,0 +1,435 @@
+/****************************************************************************
+**
+** 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 [email protected].
+**
+** 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!
+
+*/