qapplication.3qt

tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件

Advanced cursor handling: hasGlobalMouseTracking(), setGlobalMouseTracking(), overrideCursor(), setOverrideCursor(), restoreOverrideCursor().
.IP
.TP
X Window System synchronization: flushX(), syncX().
.IP
.TP
Session management: isSessionRestored(), sessionId(), commitData(), saveState()
.IP
.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
qdir/qdir.cpp showimg/main.cpp rangecontrols/main.cpp validator/main.cpp themes/main.cpp listviews/main.cpp aclock/main.cpp checklists/main.cpp buttons_groups/main.cpp drawlines/connect.cpp dclock/main.cpp wizard/main.cpp xform/xform.cpp application/main.cpp qiconview/main.cpp cursor/cursor.cpp layout/layout.cpp life/main.cpp i18n/main.cpp drawdemo/drawdemo.cpp lineedits/main.cpp popup/popup.cpp listbox/main.cpp menu/menu.cpp progress/progress.cpp scribble/main.cpp qmag/qmag.cpp table/main.cpp splitter/splitter.cpp progressbar/main.cpp richtext/main.cpp tooltip/main.cpp qwerty/main.cpp forever/forever.cpp rot13/rot13.cpp desktop/desktop.cpp scrollview/scrollview.cpp qfd/qfd.cpp addressbook/main.cpp movies/main.cpp picture/picture.cpp listbox_combo/main.cpp hello/main.cpp qfileiconview/main.cpp qbrowser/main.cpp biff/main.cpp tictac/main.cpp customlayout/main.cpp dirview/main.cpp
.)l
.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. \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.
.TP
\fC-qdevel\fR activates the Application Builder window, which allows run-time inspection of the program.
.TP
\fC-qtranslate\fR activates the Application Translator window, which allows translation of the texts shown in the program.
.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 () \fC[virtual]\fR"
Cleans up any window system resources that were allocated by this application. Sets the global variable \fCqApp\fR to null. Unlike former versions of Qt the destructor does \fInot\fR delete all remaining widgets.
.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 applicaton 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: currentPopupWidget() 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 WType_Popup widget flag, e.g. the QPopupMenu widget. When the application opens a popup widget, all events are sent to the popup and 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: currentModalWidget() and topLevelWidgets().
.SH "QWidget * QApplication::activeWindow () const"
Returns the application toplevel 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, 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 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
    while ( it.current() ) {            // for each top level widget...
.br
        it.current()->update();
.br
        ++it;
.br
    }
.br
    delete list;                        // delete the list, not the widgets
.fi
.PP
The QWidgetList class is defined in the qwidcoll.h header file.
.PP
\fBWarning:\fR Delete the list away as soon you have finished using it. You can get in serious trouble if you for instance try to access a widget that has been deleted.
.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
See also: argc() and QApplication::QApplication().
.SH "void QApplication::beep () \fC[static]\fR"
Sounds the bell, using the default volume and sound.
.SH "QClipboard * QApplication::clipboard () \fC[static]\fR"
Returns a pointer to the application global clipboard.
.SH "void QApplication::closeAllWindows () \fC[slot]\fR"
A convenience function that closes all toplevel windows.
.PP
The function is particularly useful for applications with many toplevel windows. It could for example be connected to a "Quit" entry in the file menu as shown in the following code example:
.PP
.nf
.br
    // the "Quit" menu entry should try to close all windows
.br
    QPopupMenu* file = new QPopupMenu( this );
.br
    file->insertItem( tr("&Quit"), qApp, SLOT(closeAllWindows()), CTRL+Key_Q );
.br
.br
    // when the last window was closed, the application should quit
.br
    connect( qApp, SIGNAL( lastWindowClosed() ), qApp, SLOT( quit() ) );
.fi
.PP
The windows are closed in random order, until one window does not accept the close event.
.PP
See also: QWidget::close(), QWidget::closeEvent(), lastWindowClosed(), quit(), topLevelWidgets() and QWidget::isTopLevel().
.SH "bool QApplication::closingDown () \fC[static]\fR"
Returns TRUE if the application objects are being destroyed.
.PP
See also: startingUp().
.SH "int QApplication::colorSpec () \fC[static]\fR"
Returns the color specification.
.PP
See also: QApplication::setColorSpec().
.SH "void QApplication::commitData ( QSessionManager & sm ) \fC[virtual]\fR"
This function deals with session management. It is invoked when the session manager wants the application to commit all its data.
.PP
Usually this means saving of all open files, after getting permission from the user. Furthermore you may want to provide the user a way to cancel the shutdown.
.PP
Note that you should not exit the application within this function. Instead, the session manager may or may not do this afterwards, depending on the context.
.PP
\fBImportant\fR
.br
Within this function, no user interaction is possible, \fIunless\fR you ask the session manager \fIsm\fR for explicit permission. See QSessionManager::allowsInteraction() and QSessionManager::allowsErrorInteraction() for details and example usage.
.PP
Details about session management in general can be found here.
.PP
See also: isSessionRestored(), sessionId() and saveState().
.SH "int QApplication::cursorFlashTime () \fC[static]\fR"
Returns the text cursor's flash time in milliseconds. The flash time is the time requried to display, invert and restore the caret display.
.PP
The default value is 1000 milliseconds. Under Windows, the control panel value is used.
.PP
Widgets should not cache this value since it may vary any time the user changes the global desktop settings.
.PP
See also: setCursorFlashTime().
.SH "QTextCodec* QApplication::defaultCodec () const"
Returns the default codec (see setDefaultCodec()). Returns 0 by default (no codec).
.SH "QWidget * QApplication::desktop () \fC[static]\fR"
Returns the desktop widget (also called the root window).
.PP
The desktop widget is useful for obtaining the size of the screen. It can also be used to draw on the desktop.
.PP
.nf
.br
    QWidget *d = QApplication::desktop();
.br
    int w=d->width();                   // returns screen width
.br
    int h=d->height();                  // returns screen height
.br
    d->setBackgroundColor( red );       // makes desktop red
.fi
.PP
Examples:
.(l
qmag/qmag.cpp
.)l
.SH "bool QApplication::desktopSettingsAware () \fC[static]\fR"
Returns the value set by setDesktopSettingsAware(), by default TRUE.
.PP
See also: setDesktopSettingsAware().
.SH "int QApplication::doubleClickInterval () \fC[static]\fR"
Returns the maximum duration for a double click.
.PP
The default value is 400 milliseconds. Under Windows, the control panel value is used.
.PP
See also: setDoubleClickInterval().
.SH "int QApplication::enter_loop ()"
This function enters the main event loop (recursively). Do not call it unless you really know what you are doing.
.PP
See also: exit_loop().
.SH "int QApplication::exec ()"
Enters the main event loop and waits until exit() is called or the main widget is destroyed. Returns the value that was specified to exit(), which is 0 if exit() is called via quit().
.PP
It is necessary to call this function to start event handling. The main event loop receives events from the window system and dispatches these to the application widgets.
.PP
Generally, no user interaction can take place before calling exec(). As a special case, modal widgets like QMessageBox can be used before calling exec(), because modal widget have a local event loop.
.PP
To make your application perform idle processing, i.e. executing a special function whenever there are no pending events, use a QTimer with 0 timeout. More advanced idle processing schemes can be achieved by using processEvents() and processOneEvent().
.PP
See also: quit(), exit(), processEvents() and setMainWidget().
.PP
Examples:
.(l
showimg/main.cpp rangecontrols/main.cpp validator/main.cpp themes/main.cpp listviews/main.cpp aclock/main.cpp checklists/main.cpp buttons_groups/main.cpp drawlines/connect.cpp dclock/main.cpp mainlyQt/editor.cpp xform/xform.cpp application/main.cpp qiconview/main.cpp cursor/cursor.cpp layout/layout.cpp life/main.cpp i18n/main.cpp drawdemo/drawdemo.cpp lineedits/main.cpp popup/popup.cpp listbox/main.cpp menu/menu.cpp progress/progress.cpp scribble/main.cpp qmag/qmag.cpp table/main.cpp splitter/splitter.cpp progressbar/main.cpp richtext/main.cpp tooltip/main.cpp qwerty/main.cpp forever/forever.cpp rot13/rot13.cpp scrollview/scrollview.cpp qfd/qfd.cpp addressbook/main.cpp movies/main.cpp picture/picture.cpp listbox_combo/main.cpp hello/main.cpp qfileiconview/main.cpp qbrowser/main.cpp biff/main.cpp tictac/main.cpp customlayout/main.cpp dirview/main.cpp
.)l
.SH "void QApplication::exit ( int retcode=0 ) \fC[static]\fR"
Tells the application to exit with a return code.
.PP
After this function has been called, the application leaves the main event loop and returns from the call to exec(). The exec() function returns \fIretcode.\fR
.PP
By convention, \fIretcode\fR 0 means success, any non-zero value indicates an error.
.PP
Note that unlike the C library exit function, this function \fIdoes\fR returns to the caller - it is event processing that stops.
.PP
See also: quit() and exec().
.PP
Examples:
.(l
picture/picture.cpp
.)l
.SH "void QApplication::exit_loop ()"
This function leaves from a recursive call to the main event loop. Do not call it unless you are an expert.
.PP
See also: enter_loop().
.SH "void QApplication::flushX () \fC[static]\fR"
Flushes the X event queue in the X11 implementation. Does nothing on other platforms.
.PP
See also: syncX().
.SH "QWidget * QApplication::focusWidget () const"
Returns the application widget that has the keyboard input focus, or null if no application widget has the focus.
.PP
See also: QWidget::setFocus(), QWidget::hasFocus() and activeWindow().
.SH "QFont QApplication::font ( const QWidget * w = 0 ) \fC[static]\fR"
Returns the default font for a widget. Basicly this function uses the class name of the widget to get a font for it.
.PP
If \fIw\fR is 0 the default application font is returned. There is always an application font, i.e. the returned pointer is guaranteed to be non-null if a QApplication object has been constructed.
.PP
See also: setFont(), fontMetrics() and QWidget::font().
.SH "QFontMetrics QApplication::fontMetrics () \fC[static]\fR"
Returns display (screen) font metrics for the application font.
.PP
See also: font(), setFont(), QWidget::fontMetrics() and QPainter::fontMetrics().
.SH "bool QApplication::hasGlobalMouseTracking () \fC[static]\fR"
Returns TRUE if global mouse tracking is enabled, otherwise FALSE.
.PP
See also: setGlobalMouseTracking().
.SH "void QApplication::installTranslator ( QTranslator * mf )"
Adds \fImf\fR to the list of message files to be used for localization. Message files are searched starting with the most recently added file.
.PP
See also: removeTranslator(), translate() and QObject::tr().
.PP