qapplication.3qt

Trolltech公司发布的基于C++图形开发环境

(Note that these are not member functions.)
.in +1c
.ti -1c
.BI "void \fBqFatal\fR (const char * " "msg" ", ...)"
.br
.ti -1c
.BI "void \fBqWarning\fR (const char * " "msg" ", ...)"
.br
.ti -1c
.BI "const char * \fBqVersion\fR ()"
.br
.ti -1c
.BI "void \fBqAddPostRoutine\fR (Q_CleanUpFunction " "p" ")"
.br
.ti -1c
.BI "void \fBASSERT\fR (bool " "test" ")"
.br
.ti -1c
.BI "void \fBqDebug\fR (const char * " "msg" ", ...)"
.br
.ti -1c
.BI "bool \fBqSysInfo\fR (int * " "wordSize" ", bool * " "bigEndian" ")"
.br
.ti -1c
.BI "void \fBCHECK_PTR\fR (void * " "p" ")"
.br
.ti -1c
.BI "msg_handler \fBqInstallMsgHandler\fR (msg_handler " "h" ")"
.br
.in -1c
.SH DESCRIPTION
The QApplication class manages the GUI application's control flow and main settings.
.PP
It contains the main event loop, where all events from the window system and other sources are processed and dispatched. It also handles the application initialization and finalization, and provides session management. Finally, it handles most system-wide and application-wide settings.
.PP
For any GUI application that uses Qt, there is precisely one QApplication object, no matter whether the application has 0, 1, 2 or even more windows at the moment.
.PP
This object (you can access is using the global variable \fCqApp)\fR does a great many things, most importantly: 
.TP
It initializes the application to the user's desktop settings like palette(), font() or the doubleClickInterval(). It keeps track of these properties in case the user changes the desktop globally in some kind of control panel.
.TP
It performs event handling, meaning that it receives events from the underlying window system and sends them to the destination widgets. By using sendEvent() and postEvent() you can send your own events to widgets.
.TP
It parses common command line arguments and sets its internal state accordingly. See the constructor documentation below for more details about this.
.TP
It defines the application's look and feel, which is encapsulated in a QStyle object. This can be changed during runtime with setStyle().
.TP
It specifies how the application is to allocate colors. See setColorSpec() for details.
.TP
It specifies the default text encoding (see setDefaultCodec() ) and provides localization of strings that are visible to the user via translate().
.TP
It provides some magic objects like the desktop() and the clipboard().
.TP
It knows about the application's windows, and lets you ask which widget is at a certain position using widgetAt(), lets you closeAllWindows(), gives you a list of topLevelWidgets(), etc.
.TP
It manages the application's mouse cursor handling, see setOverrideCursor() and setGlobalMouseTracking().
.TP
On the X window system, it provides functions to flush and sync the communication stream, see flushX() and syncX().
.TP
It provides support to implement sophisticated session management. This makes it possible for applications to terminate gracefully when the user logs out, to cancel a shutdown process if termination isn't possible and even to preserve the entire application state for a future session. See isSessionRestored(), sessionId() and commitData() and saveState() for details.
.IP
.PP
The Application walk-through example contains a typical complete main() that does the usual things with QApplication.
.PP
Since the QApplication object does so much initialization, it is absolutely necessary to create it before any other objects related to the user interface are created.
.PP
Since it also deals with common command line arguments, it is usually a good idea to create it \fIbefore\fR any interpretation or modification of \fCargv\fR is done in the application itself. (Note also that for X11, setMainWidget() may change the main widget according to the \fC-geometry\fR option. To preserve this functionality, you must set your defaults before setMainWidget() and any overrides after.)
.PP
\fBGroups of functions:\fR
.TP
System settings: desktopSettingsAware(), setDesktopSettingsAware(), cursorFlashTime(), setCursorFlashTime(), doubleClickInterval(), setDoubleClickInterval(), wheelScrollLines(), setWheelScrollLines(), palette(), setPalette(), font(), setFont(), fontMetrics().
.TP
Event handling: exec(), processEvents(), processOneEvent(), enter_loop(), exit_loop(), exit(), quit(). sendEvent(), postEvent(), sendPostedEvents(), removePostedEvents(), notify(), x11EventFilter(), x11ProcessEvent(), winEventFilter().
.TP
GUI Styles: style(), setStyle(), polish().
.TP
Color usage: colorSpec(), setColorSpec().
.TP
Text handling: setDefaultCodec(), installTranslator(), removeTranslator() translate().
.TP
Certain widgets: mainWidget(), setMainWidget(), allWidgets(), topLevelWidgets(), desktop(), activePopupWidget(), activeModalWidget(), clipboard(), focusWidget(), activeWindow(), widgetAt().
.TP
Advanced cursor handling: hasGlobalMouseTracking(), setGlobalMouseTracking(), overrideCursor(), setOverrideCursor(), restoreOverrideCursor().
.TP
X Window System synchronization: flushX(), syncX().
.TP
Session management: isSessionRestored(), sessionId(), commitData(), saveState()
.TP
Misc: closeAllWindows(), startingUp(), closingDown(),
.PP
\fBNon-GUI programs\fR
.br
While Qt is not optimized or designed for writing non-GUI programs, it's possible to use some of its classes without creating a QApplication. This can be useful if you wish to share code between a non-GUI server and a GUI client.
.PP
Examples:
.(l
showimg/main.cpp action/main.cpp rangecontrols/main.cpp iconview/main.cpp validator/main.cpp themes/main.cpp listviews/main.cpp aclock/main.cpp checklists/main.cpp drawlines/connect.cpp dclock/main.cpp wizard/main.cpp xform/xform.cpp application/main.cpp cursor/cursor.cpp layout/layout.cpp helpviewer/main.cpp buttongroups/main.cpp life/main.cpp i18n/main.cpp drawdemo/drawdemo.cpp lineedits/main.cpp popup/popup.cpp fileiconview/main.cpp listbox/main.cpp menu/menu.cpp progress/progress.cpp scribble/main.cpp qmag/qmag.cpp tabdialog/main.cpp splitter/splitter.cpp progressbar/main.cpp tooltip/main.cpp richtext/main.cpp qwerty/main.cpp forever/forever.cpp rot13/rot13.cpp xml/tagreader
.)l-with-features/tagreader.cpp
desktop/desktop.cpp scrollview/scrollview.cpp qfd/qfd.cpp addressbook/main.cpp movies/main.cpp picture/picture.cpp hello/main.cpp listboxcombo/main.cpp biff/main.cpp tictac/main.cpp customlayout/main.cpp mdi/main.cpp dirview/main.cpp
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QApplication::QApplication ( int & argc, char ** argv )"
Initializes the window system and constructs an application object with the command line arguments \fIargc\fR and \fIargv.\fR
.PP
The global \fCqApp\fR pointer refers to this application object. Only one application object should be created.
.PP
This application object must be constructed before any paint devices (includes widgets, pixmaps, bitmaps etc.)
.PP
Notice that \fIargc\fR and \fIargv\fR might be changed. Qt removes command line arguments that it recognizes. The original \fIargc\fR and \fIargv\fR are can be accessed later by \fCqApp->argc()\fR and \fCqApp->argv().\fR The documentation for argv() contains a detailed description of how to process command line arguments.
.PP
Qt debugging options (not available if Qt was compiled with the NO_DEBUG flag defined):
.TP
\fC-nograb,\fR tells Qt to never grab the mouse or the keyboard.
.TP
\fC-dograb\fR (only under X11), running under a debugger can cause an implicit -nograb, use -dograb to override.
.TP
\fC-sync\fR (only under X11), switches to synchronous mode for debugging.
.PP
See Debugging Techniques for a more detailed explanation.
.PP
All Qt programs automatically support the following command line options:
.TP
\fC-style=\fR \fIstyle,\fR sets the application GUI style. Possible values are \fCmotif, windows,\fR and \fCplatinum.\fR
.TP
\fC-session=\fR \fIsession,\fR restores the application from an earlier session.
.PP
The X11 version of Qt also supports some traditional X11 command line options:
.TP
\fC-display\fR \fIdisplay,\fR sets the X display (default is $DISPLAY).
.TP
\fC-geometry\fR \fIgeometry,\fR sets the client geometry of the main widget.
.TP
\fC-fn\fR or \fC-font\fR \fIfont,\fR defines the application font.
.TP
\fC-bg\fR or \fC-background\fR \fIcolor,\fR sets the default background color and an application palette (light and dark shades are calculated).
.TP
\fC-fg\fR or \fC-foreground\fR \fIcolor,\fR sets the default foreground color.
.TP
\fC-btn\fR or \fC-button\fR \fIcolor,\fR sets the default button color.
.TP
\fC-name\fR \fIname,\fR sets the application name.
.TP
\fC-title\fR \fItitle,\fR sets the application title (caption).
.TP
\fC-visual TrueColor,\fR forces the application to use a TrueColor visual on an 8-bit display.
.TP
\fC-ncols\fR \fIcount,\fR limits the number of colors allocated in the color cube on a 8-bit display, if the application is using the \fCQApplication::ManyColor\fR color specification. If \fIcount\fR is 216 then a 6x6x6 color cube is used (ie. 6 levels of red, 6 of green, and 6 of blue); for other values, a cube approximately proportional to a 2x3x1 cube is used.
.TP
\fC-cmap,\fR causes the application to install a private color map on an 8-bit display.
.PP
See also argc() and argv().
.SH "QApplication::QApplication ( int & argc, char ** argv, Type type )"
For Qt/Embedded, passing \fIQApplication::GuiServer\fR for \fItype\fR make this application the server (equivalent to running with the -qws option).
.SH "QApplication::QApplication ( int & argc, char ** argv, bool GUIenabled )"
Constructs an application object with the command line arguments \fIargc\fR and \fIargv.\fR If \fIGUIenabled\fR is TRUE, a normal application is constructed, otherwise a non-GUI application is created.
.PP
Set \fIGUIenabled\fR to FALSE for programs without a graphical user interface that should be able to run without a window system.
.PP
On X11, the window system is initialized if \fIGUIenabled\fR is TRUE. If \fIGUIenabled\fR is FALSE, the application does not connect to the X-server.
.PP
On Windows, currently the window system is always initialized, regardless of the value of GUIenabled. This may change in future versions of Qt.
.PP
The following example shows how to create an application that uses a graphical interface when available.
.PP
.nf
.br
  int main( int argc, char **argv )
.br
  {
.br
    QApplication app(argc, argv, useGUI);
.br
.br
    if ( useGUI ) {
.br
       //start GUI version
.br
       ...
.br
    } else {
.br
       //start non-GUI version
.br
       ...
.br
    }
.br
    return app.exec();
.br
  }
.fi
.SH "QApplication::~QApplication () \fC[virtual]\fR"
Cleans up any window system resources that were allocated by this application. Sets the global variable \fCqApp\fR to null.
.SH "void QApplication::aboutToQuit () \fC[signal]\fR"
This signal is emitted when the application is about to quit the main event loop. This may happen either after a call to quit() from inside the application or when the users shuts down the entire desktop session.
.PP
The signal is particularly useful if your application has to do some last-second cleanups. Note that no user interaction is possible at this state.
.PP
See also quit().
.SH "QWidget * QApplication::activeModalWidget () \fC[static]\fR"
Returns the active modal widget.
.PP
A modal widget is a special top level widget which is a subclass of QDialog that specifies the modal parameter of the constructor to TRUE. A modal widget must be finished before the user can continue with other parts of the program.
.PP
The modal widgets are organized in a stack. This function returns the active modal widget on top of the stack.
.PP
See also activePopupWidget() and topLevelWidgets().
.SH "QWidget * QApplication::activePopupWidget () \fC[static]\fR"
Returns the active popup widget.
.PP
A popup widget is a special top level widget that sets the \fCWType_Popup\fR widget flag, e.g. the QPopupMenu widget. When the application opens a popup widget, all events are sent to the popup. Normal widgets and modal widgets cannot be accessed before the popup widget is closed.
.PP
Only other popup widgets may be opened when a popup widget is shown. The popup widgets are organized in a stack. This function returns the active popup widget on top of the stack.
.PP
See also activeModalWidget() and topLevelWidgets().
.SH "QWidget * QApplication::activeWindow () const"
Returns the application top-level window that has the keyboard input focus, or null if no application window has the focus. Note that there might be an activeWindow even if there is no focusWidget(), for example if no widget in that window accepts key events.
.PP
See also QWidget::setFocus(), QWidget::hasFocus() and focusWidget().
.SH "QWidgetList * QApplication::allWidgets () \fC[static]\fR"
Returns a list of all the widgets in the application.
.PP
The list is created using new and must be deleted by the caller.
.PP
The list is empty (QList::isEmpty()) if there are no widgets.
.PP
Note that some of the widgets may be hidden.
.PP
Example:
.PP
.nf
.br
    //
.br
    // Updates all widgets.
.br
    //
.br
    QWidgetList  *list = QApplication::allWidgets();
.br
    QWidgetListIt it( *list );          // iterate over the widgets
.br
    QWidget * w;
.br
    while ( (w=it.current()) != 0 ) {   // for each widget...
.br
        ++it;
.br
        w->update();
.br
    }
.br
    delete list;                        // delete the list, not the widgets
.fi
.PP
The QWidgetList class is defined in the qwidgetlist.h header file.
.PP
\fBWarning:\fR Delete the list away as soon you have finished using it. The widgets in the list may be deleted by someone else at any time.
.PP
See also topLevelWidgets(), QWidget::isVisible() and QList::isEmpty(),.
.SH "int QApplication::argc () const"
Returns the number of command line arguments.
.PP
The documentation for argv() contains a detailed description of how to process command line arguments.
.PP
See also argv() and QApplication::QApplication().
.SH "char ** QApplication::argv () const"
Returns the command line argument vector.
.PP
\fCargv()[0]\fR is the program name, \fCargv()[1]\fR is the first argument and \fCargv()[argc()-1]\fR is the last argument.
.PP
A QApplication object is constructed by passing \fIargc\fR and \fIargv\fR from the \fCmain()\fR function. Some of the arguments may be recognized as Qt options removed from the argument vector. For example, the X11 version of Qt knows about \fC-display, -font\fR and a few more options.
.PP
Example:
.PP
.nf
.br
    // showargs.cpp - displays program arguments in a list box
.br
.br
    #include <qapplication.h>
.br
    #include <qlistbox.h>
.br
.br
    int main( int argc, char **argv )
.br
    {
.br
        QApplication a( argc, argv );
.br
        QListBox b;
.br
        a.setMainWidget( &b );
.br
        for ( int i=0; i<a.argc(); i++ )        // a.argc() == argc
.br
            b.insertItem( a.argv()[i] );        // a.argv()[i] == argv[i]
.br
        b.show();
.br
        return a.exec();
.br
    }
.fi
.PP
If you run \fCshowargs -display unix:0 -font 9x15bold hello world\fR under X11, the list box contains the three strings" showargs", "hello" and "world".
.PP