summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorKavindra Devi Palaraja <kavindra.palaraja@nokia.com>2009-03-25 14:40:39 (GMT)
committerKavindra Devi Palaraja <kavindra.palaraja@nokia.com>2009-03-25 14:42:22 (GMT)
commitec1a593fd480655ec461186160cdcdd890a778ab (patch)
treee074a149d4dde9947a0ddce8900d88b722f4f1a9 /src
parenta794ded85f74516239a08cf848e6b4f8b6dcac6a (diff)
downloadQt-ec1a593fd480655ec461186160cdcdd890a778ab.zip
Qt-ec1a593fd480655ec461186160cdcdd890a778ab.tar.gz
Qt-ec1a593fd480655ec461186160cdcdd890a778ab.tar.bz2
Doc - removed mention of an internal function. Also gave the
QApplication class and the QSessionManager class a documentation overhaul. Task-number: 249220 Reviewed-by: TrustMe
Diffstat (limited to 'src')
-rw-r--r--src/gui/kernel/qapplication.cpp1891
1 files changed, 918 insertions, 973 deletions
diff --git a/src/gui/kernel/qapplication.cpp b/src/gui/kernel/qapplication.cpp
index 7e59fad..03d74d6 100644
--- a/src/gui/kernel/qapplication.cpp
+++ b/src/gui/kernel/qapplication.cpp
@@ -169,189 +169,174 @@ QApplicationPrivate::~QApplicationPrivate()
}
/*!
- \class QApplication
- \brief The QApplication class manages the GUI application's control
- flow and main settings.
-
- \ingroup application
- \mainclass
-
- 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's initialization and finalization, and
- provides session management. It also handles most system-wide and
- application-wide settings.
-
- For any GUI application that uses Qt, there is precisely one
- QApplication object, no matter whether the application has 0, 1, 2
- or more windows at any time. For non-GUI Qt applications, use
- QCoreApplication instead, which doesn't depend on the \l QtGui
- library.
-
- The QApplication object is accessible through the instance()
- function which return a pointer equivalent to the global qApp
- pointer.
-
- QApplication's main areas of responsibility are:
- \list
-
- \o It initializes the application with the user's desktop settings
- such as palette(), font() and doubleClickInterval(). It keeps track
- of these properties in case the user changes the desktop globally, for
- example through some kind of control panel.
-
- \o It performs event handling, meaning that it receives events
- from the underlying window system and dispatches them to the relevant
- widgets. By using sendEvent() and postEvent() you can send your own
- events to widgets.
-
- \o It parses common command line arguments and sets its internal
- state accordingly. See the \link QApplication::QApplication()
- constructor documentation\endlink below for more details about this.
-
- \o It defines the application's look and feel, which is
- encapsulated in a QStyle object. This can be changed at runtime
- with setStyle().
-
- \o It specifies how the application is to allocate colors.
- See setColorSpec() for details.
-
- \o It provides localization of strings that are visible to the user
- via translate().
-
- \o It provides some magical objects like the desktop() and the
- clipboard().
-
- \o It knows about the application's windows. You can ask which
- widget is at a certain position using widgetAt(), get a list of
- topLevelWidgets() and closeAllWindows(), etc.
-
- \o It manages the application's mouse cursor handling,
- see setOverrideCursor()
-
- \o On the X window system, it provides functions to flush and sync
- the communication stream, see flushX() and syncX().
-
- \o It provides support for sophisticated \link
- session.html session management \endlink. 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's state for a future session. See
- isSessionRestored(), sessionId() and commitData() and saveState()
- for details.
-
- \endlist
-
- Since the QApplication object does so much initialization, it
- \e{must} be created before any other objects related to the user
- interface are created.
-
- Since it also deals with common command line arguments, it is
- usually a good idea to create it \e before any interpretation or
- modification of \c argv is done in the application itself.
-
- \table
- \header \o{2,1} Groups of functions
- \row
- \o System settings
- \o
- desktopSettingsAware(),
- setDesktopSettingsAware(),
- cursorFlashTime(),
- setCursorFlashTime(),
- doubleClickInterval(),
- setDoubleClickInterval(),
- setKeyboardInputInterval(),
- wheelScrollLines(),
- setWheelScrollLines(),
- palette(),
- setPalette(),
- font(),
- setFont(),
- fontMetrics().
-
- \row
- \o Event handling
- \o
- exec(),
- processEvents(),
- exit(),
- quit().
- sendEvent(),
- postEvent(),
- sendPostedEvents(),
- removePostedEvents(),
- hasPendingEvents(),
- notify(),
- macEventFilter(),
- qwsEventFilter(),
- x11EventFilter(),
- x11ProcessEvent(),
- winEventFilter().
-
- \row
- \o GUI Styles
- \o
- style(),
- setStyle().
-
- \row
- \o Color usage
- \o
- colorSpec(),
- setColorSpec(),
- qwsSetCustomColors().
-
- \row
- \o Text handling
- \o
- installTranslator(),
- removeTranslator()
- translate().
-
- \row
- \o Widgets
- \o
- allWidgets(),
- topLevelWidgets(),
- desktop(),
- activePopupWidget(),
- activeModalWidget(),
- clipboard(),
- focusWidget(),
- winFocus(),
- activeWindow(),
- widgetAt().
-
- \row
- \o Advanced cursor handling
- \o
- overrideCursor(),
- setOverrideCursor(),
- restoreOverrideCursor().
-
- \row
- \o X Window System synchronization
- \o
- flushX(),
- syncX().
-
- \row
- \o Session management
- \o
- isSessionRestored(),
- sessionId(),
- commitData(),
- saveState().
-
- \row
- \o Miscellaneous
- \o
- closeAllWindows(),
- startingUp(),
- closingDown(),
- type().
- \endtable
+ \class QApplication
+ \brief The QApplication class manages the GUI application's control
+ flow and main settings.
+
+ \ingroup application
+ \mainclass
+
+ QApplication contains the main event loop, where all events from the window
+ system and other sources are processed and dispatched. It also handles the
+ application's initialization and finalization, and provides session
+ management. In addition, it handles most system-wide and application-wide
+ settings.
+
+ For any GUI application using Qt, there is precisely one QApplication
+ object, no matter whether the application has 0, 1, 2 or more windows at
+ any given time. For non-GUI Qt applications, use QCoreApplication instead,
+ as it does not depend on the \l QtGui library.
+
+ The QApplication object is accessible through the instance() function that
+ returns a pointer equivalent to the global qApp pointer.
+
+ QApplication's main areas of responsibility are:
+ \list
+ \o It initializes the application with the user's desktop settings
+ such as palette(), font() and doubleClickInterval(). It keeps
+ track of these properties in case the user changes the desktop
+ globally, for example through some kind of control panel.
+
+ \o It performs event handling, meaning that it receives events
+ from the underlying window system and dispatches them to the
+ relevant widgets. By using sendEvent() and postEvent() you can
+ send your own events to widgets.
+
+ \o It parses common command line arguments and sets its internal
+ state accordingly. See the \l{QApplication::QApplication()}
+ {constructor documentation} below for more details.
+
+ \o It defines the application's look and feel, which is
+ encapsulated in a QStyle object. This can be changed at runtime
+ with setStyle().
+
+ \o It specifies how the application is to allocate colors. See
+ setColorSpec() for details.
+
+ \o It provides localization of strings that are visible to the
+ user via translate().
+
+ \o It provides some magical objects like the desktop() and the
+ clipboard().
+
+ \o It knows about the application's windows. You can ask which
+ widget is at a certain position using widgetAt(), get a list of
+ topLevelWidgets() and closeAllWindows(), etc.
+
+ \o It manages the application's mouse cursor handling, see
+ setOverrideCursor()
+
+ \o On the X window system, it provides functions to flush and sync
+ the communication stream, see flushX() and syncX().
+
+ \o It provides support for sophisticated \l{Session Management}
+ {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's state for a future session.
+ See isSessionRestored(), sessionId() and commitData() and
+ saveState() for details.
+ \endlist
+
+ The QApplication object does so much initialization. Hence, it \e{must} be
+ created before any other objects related to the user interface are created.
+ Since QApplication also deals with common command line arguments, it is
+ usually a good idea to create it \e before any interpretation or
+ modification of \c argv is done in the application itself.
+
+ \table
+ \header
+ \o{2,1} Groups of functions
+
+ \row
+ \o System settings
+ \o desktopSettingsAware(),
+ setDesktopSettingsAware(),
+ cursorFlashTime(),
+ setCursorFlashTime(),
+ doubleClickInterval(),
+ setDoubleClickInterval(),
+ setKeyboardInputInterval(),
+ wheelScrollLines(),
+ setWheelScrollLines(),
+ palette(),
+ setPalette(),
+ font(),
+ setFont(),
+ fontMetrics().
+
+ \row
+ \o Event handling
+ \o exec(),
+ processEvents(),
+ exit(),
+ quit().
+ sendEvent(),
+ postEvent(),
+ sendPostedEvents(),
+ removePostedEvents(),
+ hasPendingEvents(),
+ notify(),
+ macEventFilter(),
+ qwsEventFilter(),
+ x11EventFilter(),
+ x11ProcessEvent(),
+ winEventFilter().
+
+ \row
+ \o GUI Styles
+ \o style(),
+ setStyle().
+
+ \row
+ \o Color usage
+ \o colorSpec(),
+ setColorSpec(),
+ qwsSetCustomColors().
+
+ \row
+ \o Text handling
+ \o installTranslator(),
+ removeTranslator()
+ translate().
+
+ \row
+ \o Widgets
+ \o allWidgets(),
+ topLevelWidgets(),
+ desktop(),
+ activePopupWidget(),
+ activeModalWidget(),
+ clipboard(),
+ focusWidget(),
+ activeWindow(),
+ widgetAt().
+
+ \row
+ \o Advanced cursor handling
+ \o overrideCursor(),
+ setOverrideCursor(),
+ restoreOverrideCursor().
+
+ \row
+ \o X Window System synchronization
+ \o flushX(),
+ syncX().
+
+ \row
+ \o Session management
+ \o isSessionRestored(),
+ sessionId(),
+ commitData(),
+ saveState().
+
+ \row
+ \o Miscellaneous
+ \o closeAllWindows(),
+ startingUp(),
+ closingDown(),
+ type().
+ \endtable
\sa QCoreApplication, QAbstractEventDispatcher, QEventLoop, QSettings
*/
@@ -382,6 +367,7 @@ QApplicationPrivate::~QApplicationPrivate()
Returns the top-level widget at the given \a point; returns 0 if
there is no such widget.
*/
+
/*!
\fn QWidget *QApplication::topLevelAt(int x, int y)
@@ -393,8 +379,8 @@ QApplicationPrivate::~QApplicationPrivate()
/*
- The qt_init() and qt_cleanup() functions are implemented in the
- qapplication_xyz.cpp file.
+ The qt_init() and qt_cleanup() functions are implemented in the
+ qapplication_xyz.cpp file.
*/
void qt_init(QApplicationPrivate *priv, int type
@@ -580,99 +566,100 @@ void QApplicationPrivate::process_cmdline()
}
/*!
- Initializes the window system and constructs an application object
- with \a argc command line arguments in \a argv.
-
- \warning The data referred to by \a argc and \a argv must stay valid
- for the entire lifetime of the QApplication object. In addition,
- \a argc must be greater than zero and \a argv must contain at least
- one valid character string.
-
- The global \c qApp pointer refers to this application object. Only
- one application object should be created.
-
- This application object must be constructed before any \link
- QPaintDevice paint devices\endlink (including widgets, pixmaps, bitmaps
- etc.).
-
- Note that \a argc and \a argv might be changed. Qt removes command
- line arguments that it recognizes.
-
- Qt debugging options (not available if Qt was compiled without the
- QT_DEBUG flag defined):
- \list
- \o -nograb, tells Qt that it must never grab the mouse or the keyboard.
- \o -dograb (only under X11), running under a debugger can cause
- an implicit -nograb, use -dograb to override.
- \o -sync (only under X11), switches to synchronous mode for
- debugging.
- \endlist
-
- See \link debug.html Debugging Techniques \endlink for a more
- detailed explanation.
-
- All Qt programs automatically support the following command line options:
- \list
- \o -style= \e style, sets the application GUI style. Possible values
- are \c motif, \c windows, and \c platinum. If you compiled Qt
- with additional styles or have additional styles as plugins these
- will be available to the \c -style command line option.
- \o -style \e style, is the same as listed above.
- \o -stylesheet= \e stylesheet, sets the application \l styleSheet. The value
- must be a path to a file that contains the Style Sheet. Note that relative URLs
- in the Style Sheet file are relative to the Style Sheet file's path.
- \o -stylesheet \e stylesheet, is the same as listed above.
- \o -session= \e session, restores the application from an earlier
- \link session.html session \endlink.
- \o -session \e session, is the same as listed above.
- \o -widgetcount, prints debug message at the end about number of widgets left
- undestroyed and maximum number of widgets existed at the same time
- \o -reverse, sets the application's layout direction to Qt::RightToLeft
- \o -graphicssystem, sets the backend to be used for on-screen
- widgets and QPixmaps. Available options are \c{raster} and \c{opengl}.
-
- \endlist
-
- The Windows version of Qt also support one additional command line
- option, if Direct3D support has been compiled into Qt:
- \list
- \o -direct3d will make the Direct3D paint engine the default widget
- paint engine in Qt. \bold {This functionality is experimental.}
- \endlist
-
- The X11 version of Qt also supports some traditional X11
- command line options:
- \list
- \o -display \e display, sets the X display (default is $DISPLAY).
- \o -geometry \e geometry, sets the client geometry of the
- first window that is shown.
- \o -fn or \c -font \e font, defines the application font. The
- font should be specified using an X logical font description.
- \o -bg or \c -background \e color, sets the default background color
- and an application palette (light and dark shades are calculated).
- \o -fg or \c -foreground \e color, sets the default foreground color.
- \o -btn or \c -button \e color, sets the default button color.
- \o -name \e name, sets the application name.
- \o -title \e title, sets the application title.
- \o -visual \c TrueColor, forces the application to use a TrueColor visual
- on an 8-bit display.
- \o -ncols \e count, limits the number of colors allocated in the
- color cube on an 8-bit display, if the application is using the
- QApplication::ManyColor color specification. If \e count is
- 216 then a 6x6x6 color cube is used (i.e. 6 levels of red, 6 of green,
- and 6 of blue); for other values, a cube
- approximately proportional to a 2x3x1 cube is used.
- \o -cmap, causes the application to install a private color map
- on an 8-bit display.
- \o -im, sets the input method server (equivalent to setting the XMODIFIERS
- environment variable)
- \o -inputstyle, defines how the input is inserted into the given widget. E.g.,
- \c onTheSpot makes the input appear directly in the widget, while
- \c overTheSpot makes the input appear in a box floating over the
- widget and is not inserted until the editing is done.
- \endlist
-
- \sa arguments()
+ Initializes the window system and constructs an application object with
+ \a argc command line arguments in \a argv.
+
+ \warning The data referred to by \a argc and \a argv must stay valid for
+ the entire lifetime of the QApplication object. In addition, \a argc must
+ be greater than zero and \a argv must contain at least one valid character
+ string.
+
+ The global \c qApp pointer refers to this application object. Only one
+ application object should be created.
+
+ This application object must be constructed before any \l{QPaintDevice}
+ {paint devices} (including widgets, pixmaps, bitmaps etc.).
+
+ \note \a argc and \a argv might be changed as Qt removes command line
+ arguments that it recognizes.
+
+ Qt debugging options (not available if Qt was compiled without the QT_DEBUG
+ flag defined):
+ \list
+ \o -nograb, tells Qt that it must never grab the mouse or the
+ keyboard.
+ \o -dograb (only under X11), running under a debugger can cause an
+ implicit -nograb, use -dograb to override.
+ \o -sync (only under X11), switches to synchronous mode for
+ debugging.
+ \endlist
+
+ See \l{Debugging Techniques} for a more detailed explanation.
+
+ All Qt programs automatically support the following command line options:
+ \list
+ \o -style= \e style, sets the application GUI style. Possible values
+ are \c motif, \c windows, and \c platinum. If you compiled Qt with
+ additional styles or have additional styles as plugins these will
+ be available to the \c -style command line option.
+ \o -style \e style, is the same as listed above.
+ \o -stylesheet= \e stylesheet, sets the application \l styleSheet. The
+ value must be a path to a file that contains the Style Sheet.
+ \note Relative URLs in the Style Sheet file are relative to the
+ Style Sheet file's path.
+ \o -stylesheet \e stylesheet, is the same as listed above.
+ \o -session= \e session, restores the application from an earlier
+ \l{Session Management}{session}.
+ \o -session \e session, is the same as listed above.
+ \o -widgetcount, prints debug message at the end about number of
+ widgets left undestroyed and maximum number of widgets existed at
+ the same time
+ \o -reverse, sets the application's layout direction to
+ Qt::RightToLeft
+ \o -graphicssystem, sets the backend to be used for on-screen widgets
+ and QPixmaps. Available options are \c{raster} and \c{opengl}.
+ \endlist
+
+ The Windows version of Qt supports an additional command line option, if
+ Direct3D support has been compiled into Qt:
+ \list
+ \o -direct3d will make the Direct3D paint engine the default widget
+ paint engine in Qt. \bold {This functionality is experimental.}
+ \endlist
+
+ The X11 version of Qt supports some traditional X11 command line options:
+ \list
+ \o -display \e display, sets the X display (default is $DISPLAY).
+ \o -geometry \e geometry, sets the client geometry of the first window
+ that is shown.
+ \o -fn or \c -font \e font, defines the application font. The font
+ should be specified using an X logical font description.
+ \o -bg or \c -background \e color, sets the default background color
+ and an application palette (light and dark shades are calculated).
+ \o -fg or \c -foreground \e color, sets the default foreground color.
+ \o -btn or \c -button \e color, sets the default button color.
+ \o -name \e name, sets the application name.
+ \o -title \e title, sets the application title.
+ \o -visual \c TrueColor, forces the application to use a TrueColor
+ visual on an 8-bit display.
+ \o -ncols \e count, limits the number of colors allocated in the color
+ cube on an 8-bit display, if the application is using the
+ QApplication::ManyColor color specification. If \e count is 216
+ then a 6x6x6 color cube is used (i.e. 6 levels of red, 6 of green,
+ and 6 of blue); for other values, a cube approximately proportional
+ to a 2x3x1 cube is used.
+ \o -cmap, causes the application to install a private color map on an
+ 8-bit display.
+ \o -im, sets the input method server (equivalent to setting the
+ XMODIFIERS environment variable)
+ \o -inputstyle, defines how the input is inserted into the given
+ widget, e.g., \c onTheSpot makes the input appear directly in the
+ widget, while \c overTheSpot makes the input appear in a box
+ floating over the widget and is not inserted until the editing is
+ done.
+ \endlist
+
+ \sa arguments()
*/
QApplication::QApplication(int &argc, char **argv)
@@ -685,26 +672,26 @@ QApplication::QApplication(int &argc, char **argv, int _internal)
/*!
- Constructs an application object with \a argc command line arguments
- in \a argv. If \a GUIenabled is true, a GUI application is
- constructed, otherwise a non-GUI (console) application is created.
+ Constructs an application object with \a argc command line arguments in
+ \a argv. If \a GUIenabled is true, a GUI application is constructed,
+ otherwise a non-GUI (console) application is created.
- \warning The data referred to by \a argc and \a argv must stay valid
- for the entire lifetime of the QApplication object. In addition,
- \a argc must be greater than zero and \a argv must contain at least
- one valid character string.
+ \warning The data referred to by \a argc and \a argv must stay valid for
+ the entire lifetime of the QApplication object. In addition, \a argc must
+ be greater than zero and \a argv must contain at least one valid character
+ string.
- Set \a GUIenabled to false for programs without a graphical user
- interface that should be able to run without a window system.
+ Set \a GUIenabled to false for programs without a graphical user interface
+ that should be able to run without a window system.
- On X11, the window system is initialized if \a GUIenabled is true.
- If \a GUIenabled is false, the application does not connect to the
- X server. On Windows and Macintosh, currently the window system is
- always initialized, regardless of the value of GUIenabled. This may
- change in future versions of Qt.
+ On X11, the window system is initialized if \a GUIenabled is true. If
+ \a GUIenabled is false, the application does not connect to the X server.
+ On Windows and Macintosh, currently the window system is always
+ initialized, regardless of the value of GUIenabled. This may change in
+ future versions of Qt.
- The following example shows how to create an application that
- uses a graphical interface when available.
+ The following example shows how to create an application that uses a
+ graphical interface when available.
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 0
*/
@@ -720,17 +707,17 @@ QApplication::QApplication(int &argc, char **argv, bool GUIenabled , int _intern
/*!
- Constructs an application object with \a argc command line arguments
- in \a argv.
+ Constructs an application object with \a argc command line arguments in
+ \a argv.
- \warning The data referred to by \a argc and \a argv must stay valid
- for the entire lifetime of the QApplication object. In addition,
- \a argc must be greater than zero and \a argv must contain at least
- one valid character string.
+ \warning The data referred to by \a argc and \a argv must stay valid for
+ the entire lifetime of the QApplication object. In addition, \a argc must
+ be greater than zero and \a argv must contain at least one valid character
+ string.
- With Qt for Embedded Linux, passing QApplication::GuiServer for \a type
- makes this application the server (equivalent to running with the
- \c -qws option).
+ With Qt for Embedded Linux, passing QApplication::GuiServer for \a type
+ makes this application the server (equivalent to running with the
+ \c -qws option).
*/
QApplication::QApplication(int &argc, char **argv, Type type)
: QCoreApplication(*new QApplicationPrivate(argc, argv, type))
@@ -778,16 +765,16 @@ static int aargc = 1;
static char *aargv[] = { (char*)"unknown", 0 };
/*!
- \fn QApplication::QApplication(Display* display, Qt::HANDLE visual, Qt::HANDLE colormap)
+ \fn QApplication::QApplication(Display* display, Qt::HANDLE visual, Qt::HANDLE colormap)
- Create an application, given an already open display \a display. If \a
- visual and \a colormap are non-zero, the application will use those as
- the default Visual and Colormap contexts.
+ Creates an application, given an already open display \a display. If
+ \a visual and \a colormap are non-zero, the application will use those
+ values as the default Visual and Colormap contexts.
- \warning Qt only supports TrueColor visuals at depths higher than 8
- bits-per-pixel.
+ \warning Qt only supports TrueColor visuals at depths higher than 8
+ bits-per-pixel.
- This is available only on X11.
+ This function is only available on X11.
*/
QApplication::QApplication(Display* dpy, Qt::HANDLE visual, Qt::HANDLE colormap)
: QCoreApplication(*new QApplicationPrivate(aargc, aargv, GuiClient))
@@ -809,19 +796,18 @@ QApplication::QApplication(Display* dpy, Qt::HANDLE visual, Qt::HANDLE colormap,
}
/*!
- \fn QApplication::QApplication(Display *display, int &argc, char **argv,
- Qt::HANDLE visual, Qt::HANDLE colormap)
+ \fn QApplication::QApplication(Display *display, int &argc, char **argv,
+ Qt::HANDLE visual, Qt::HANDLE colormap)
- Create an application, given an already open \a display and using \a
- argc command line arguments in \a argv. If \a visual and \a colormap
- are non-zero, the application will use those as the default Visual
- and Colormap contexts.
+ Creates an application, given an already open \a display and using \a argc
+ command line arguments in \a argv. If \a visual and \a colormap are
+ non-zero, the application will use those values as the default Visual
+ and Colormap contexts.
- \warning Qt only supports TrueColor visuals at depths higher than 8
- bits-per-pixel.
-
- This is available only on X11.
+ \warning Qt only supports TrueColor visuals at depths higher than 8
+ bits-per-pixel.
+ This function is only available on X11.
*/
QApplication::QApplication(Display *dpy, int &argc, char **argv,
Qt::HANDLE visual, Qt::HANDLE colormap)
@@ -923,19 +909,18 @@ QApplication::Type QApplication::type()
*****************************************************************************/
/*!
- Returns the active popup widget.
+ Returns the active popup widget.
- A popup widget is a special top-level widget that sets the \c
- Qt::WType_Popup widget flag, e.g. the QMenu 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.
+ A popup widget is a special top-level widget that sets the \c
+ Qt::WType_Popup widget flag, e.g. the QMenu 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.
- 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 at the top of the stack.
+ 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 at the top of the stack.
- \sa activeModalWidget(), topLevelWidgets()
+ \sa activeModalWidget(), topLevelWidgets()
*/
QWidget *QApplication::activePopupWidget()
@@ -946,17 +931,17 @@ QWidget *QApplication::activePopupWidget()
/*!
- Returns the active modal widget.
+ Returns the active modal widget.
- A modal widget is a special top-level widget which is a subclass of
- QDialog that specifies the modal parameter of the constructor as
- true. A modal widget must be closed before the user can continue
- with other parts of the program.
+ A modal widget is a special top-level widget which is a subclass of QDialog
+ that specifies the modal parameter of the constructor as true. A modal
+ widget must be closed before the user can continue with other parts of the
+ program.
- Modal widgets are organized in a stack. This function returns
- the active modal widget at the top of the stack.
+ Modal widgets are organized in a stack. This function returns the active
+ modal widget at the top of the stack.
- \sa activePopupWidget(), topLevelWidgets()
+ \sa activePopupWidget(), topLevelWidgets()
*/
QWidget *QApplication::activeModalWidget()
@@ -965,8 +950,8 @@ QWidget *QApplication::activeModalWidget()
}
/*!
- Cleans up any window system resources that were allocated by this
- application. Sets the global variable \c qApp to 0.
+ Cleans up any window system resources that were allocated by this
+ application. Sets the global variable \c qApp to 0.
*/
QApplication::~QApplication()
@@ -1092,8 +1077,8 @@ QApplication::~QApplication()
/*!
\fn QWidget *QApplication::widgetAt(const QPoint &point)
- Returns the widget at global screen position \a point, or 0 if there
- is no Qt widget there.
+ Returns the widget at global screen position \a point, or 0 if there is no
+ Qt widget there.
This function can be slow.
@@ -1141,8 +1126,8 @@ QWidget *QApplication::widgetAt(const QPoint &p)
\overload
- Returns the widget at global screen position (\a x, \a y), or 0
- if there is no Qt widget there.
+ Returns the widget at global screen position (\a x, \a y), or 0 if there is
+ no Qt widget there.
*/
/*!
@@ -1211,16 +1196,17 @@ bool QApplication::compressEvent(QEvent *event, QObject *receiver, QPostEventLis
\since 4.4
\brief defines a threshold for auto maximizing widgets
- The auto maximize threshold is only available
- as part of Qt for Windows CE.
+ The auto maximize threshold is only available as part of Qt for Windows CE.
This property defines a threshold for the size of a window as a percentage
- of the screen size. If the minimum size hint of a window exceeds the threshold,
- calling show() will then cause the window to be maximized automatically.
+ of the screen size. If the minimum size hint of a window exceeds the
+ threshold, calling show() will then cause the window to be maximized
+ automatically.
- Setting the threshold to be 100 or greater means that it will cause it to always
- be maximized. Setting it to be 50 means that the widget is maximized if the vertical
- minimum size hint is at least 50% of the vertical screen size.
+ Setting the threshold to be 100 or greater means that it will cause it to
+ always be maximized. Setting it to be 50 means that the widget is maximized
+ if the vertical minimum size hint is at least 50% of the vertical screen
+ size.
If -1 is specified then this will disable the feature.
@@ -1233,12 +1219,11 @@ bool QApplication::compressEvent(QEvent *event, QObject *receiver, QPostEventLis
\since 4.5
\brief toggles automatic SIP (software input panel) visibility
- The auto SIP property is only available
- as part of Qt for Windows CE.
+ The auto SIP property is only available as part of Qt for Windows CE.
Set this property to true to automatically display the SIP when entering
- widgets that accept keyboard input. This only affects widgets that have the
- attribute WA_InputMethodEnabled set.
+ widgets that accept keyboard input. This property only affects widgets with
+ the WA_InputMethodEnabled attribute set.
*/
#ifdef Q_OS_WINCE
@@ -1290,9 +1275,9 @@ void QApplication::setStyleSheet(const QString& styleSheet)
#endif // QT_NO_STYLE_STYLESHEET
/*!
- Returns the application's style object.
+ Returns the application's style object.
- \sa setStyle(), QStyle
+ \sa setStyle(), QStyle
*/
QStyle *QApplication::style()
{
@@ -1375,22 +1360,21 @@ QStyle *QApplication::style()
}
/*!
- Sets the application's GUI style to \a style. Ownership of the style
- object is transferred to QApplication, so QApplication will delete
- the style object on application exit or when a new style is set and
- the old style is still the parent of the application object.
+ Sets the application's GUI style to \a style. Ownership of the style object
+ is transferred to QApplication, so QApplication will delete the style
+ object on application exit or when a new style is set and the old style is
+ still the parent of the application object.
Example usage:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 1
- When switching application styles, the color palette is set back to
- the initial colors or the system defaults. This is necessary since
- certain styles have to adapt the color palette to be fully
- style-guide compliant.
+ When switching application styles, the color palette is set back to the
+ initial colors or the system defaults. This is necessary since certain
+ styles have to adapt the color palette to be fully style-guide compliant.
- Note that setting the style before a palette has been set
- (i.e. before creating QApplication) will cause the application to
- use QStyle::standardPalette() for the palette.
+ Setting the style before a palette has been se, i.e., before creating
+ QApplication, will cause the application to use QStyle::standardPalette()
+ for the palette.
\warning Qt style sheets are currently not supported for custom QStyle
subclasses. We plan to address this in some future release.
@@ -1493,20 +1477,20 @@ void QApplication::setStyle(QStyle *style)
}
/*!
- \overload
+ \overload
- Requests a QStyle object for \a style from the QStyleFactory.
+ Requests a QStyle object for \a style from the QStyleFactory.
- The string must be one of the QStyleFactory::keys(), typically one
- of "windows", "motif", "cde", "plastique", "windowsxp", or
- "macintosh". Style names are case insensitive.
+ The string must be one of the QStyleFactory::keys(), typically one of
+ "windows", "motif", "cde", "plastique", "windowsxp", or "macintosh". Style
+ names are case insensitive.
- Returns 0 if an unknown \a style is passed, otherwise the QStyle object
- returned is set as the application's GUI style.
+ Returns 0 if an unknown \a style is passed, otherwise the QStyle object
+ returned is set as the application's GUI style.
- \warning To ensure that the application's style is set correctly, it is
- best to call this function before the QApplication constructor, if
- possible.
+ \warning To ensure that the application's style is set correctly, it is
+ best to call this function before the QApplication constructor, if
+ possible.
*/
QStyle* QApplication::setStyle(const QString& style)
{
@@ -1519,20 +1503,19 @@ QStyle* QApplication::setStyle(const QString& style)
}
/*!
- \since 4.5
+ \since 4.5
- Sets the default graphics backend to \a system, which will be used
- for on-screen widgets and QPixmaps. The available systems are
- \c{"native"}, \c{"raster"} and \c{"opengl"}.
+ Sets the default graphics backend to \a system, which will be used for
+ on-screen widgets and QPixmaps. The available systems are \c{"native"},
+ \c{"raster"} and \c{"opengl"}.
- Note that this function call overrides both the application
- commandline \c{-graphicssystem} switch and the configure
- \c{-graphicssystem} switch.
+ This function call overrides both the application commandline
+ \c{-graphicssystem} switch and the configure \c{-graphicssystem} switch.
- \warning This function must be called before the QApplication
- constructor is called.
+ \warning This function must be called before the QApplication constructor
+ is called.
- The \c{"opengl"} option is currently considered experimental.
+ \note The \c{"opengl"} option is currently experimental.
*/
void QApplication::setGraphicsSystem(const QString &system)
@@ -1541,9 +1524,10 @@ void QApplication::setGraphicsSystem(const QString &system)
}
/*!
- Returns the color specification.
- \sa QApplication::setColorSpec()
- */
+ Returns the color specification.
+
+ \sa QApplication::setColorSpec()
+*/
int QApplication::colorSpec()
{
@@ -1551,54 +1535,54 @@ int QApplication::colorSpec()
}
/*!
- Sets the color specification for the application to \a spec.
-
- The color specification controls how the application allocates colors
- when run on a display with a limited amount of colors, e.g. 8 bit / 256
- color displays.
-
- The color specification must be set before you create the QApplication
- object.
-
- The options are:
- \list
- \o QApplication::NormalColor.
- This is the default color allocation strategy. Use this option if
- your application uses buttons, menus, texts and pixmaps with few
- colors. With this option, the application uses system global
- colors. This works fine for most applications under X11, but on
- Windows machines it may cause dithering of non-standard colors.
- \o QApplication::CustomColor.
- Use this option if your application needs a small number of custom
- colors. On X11, this option is the same as NormalColor. On Windows, Qt
- creates a Windows palette, and allocates colors to it on demand.
- \o QApplication::ManyColor.
- Use this option if your application is very color hungry
- (e.g. it requires thousands of colors).
- Under X11 the effect is:
+ Sets the color specification for the application to \a spec.
+
+ The color specification controls how the application allocates colors when
+ run on a display with a limited amount of colors, e.g. 8 bit / 256 color
+ displays.
+
+ The color specification must be set before you create the QApplication
+ object.
+
+ The options are:
\list
- \o For 256-color displays which have at best a 256 color true
- color visual, the default visual is used, and colors are
- allocated from a color cube. The color cube is the 6x6x6 (216
- color) "Web palette" (the red, green, and blue components
- always have one of the following values: 0x00, 0x33, 0x66,
- 0x99, 0xCC, or 0xFF), but the number of colors can be changed
- by the \e -ncols option. The user can force the application to
- use the true color visual with the \link
- QApplication::QApplication() -visual \endlink option.
- \o For 256-color displays which have a true color visual with more
- than 256 colors, use that visual. Silicon Graphics X servers
- have this feature, for example. They provide an 8 bit visual
- by default but can deliver true color when asked.
+ \o QApplication::NormalColor. This is the default color allocation
+ strategy. Use this option if your application uses buttons, menus,
+ texts and pixmaps with few colors. With this option, the
+ application uses system global colors. This works fine for most
+ applications under X11, but on Windows machines it may cause
+ dithering of non-standard colors.
+ \o QApplication::CustomColor. Use this option if your application
+ needs a small number of custom colors. On X11, this option is the
+ same as NormalColor. On Windows, Qt creates a Windows palette, and
+ allocates colors to it on demand.
+ \o QApplication::ManyColor. Use this option if your application is
+ very color hungry, e.g., it requires thousands of colors. \br
+ Under X11 the effect is:
+ \list
+ \o For 256-color displays which have at best a 256 color true
+ color visual, the default visual is used, and colors are
+ allocated from a color cube. The color cube is the 6x6x6
+ (216 color) "Web palette" (the red, green, and blue
+ components always have one of the following values: 0x00,
+ 0x33, 0x66, 0x99, 0xCC, or 0xFF), but the number of colors
+ can be changed by the \e -ncols option. The user can force
+ the application to use the true color visual with the
+ \l{QApplication::QApplication()}{-visual} option.
+ \o For 256-color displays which have a true color visual with
+ more than 256 colors, use that visual. Silicon Graphics X
+ servers this feature, for example. They provide an 8 bit
+ visual by default but can deliver true color when asked.
+ \endlist
+ On Windows, Qt creates a Windows palette, and fills it with a color
+ cube.
\endlist
- On Windows, Qt creates a Windows palette, and fills it with a color cube.
- \endlist
- Be aware that the CustomColor and ManyColor choices may lead to colormap
- flashing: The foreground application gets (most) of the available
- colors, while the background windows will look less attractive.
+ Be aware that the CustomColor and ManyColor choices may lead to colormap
+ flashing: The foreground application gets (most) of the available colors,
+ while the background windows will look less attractive.
- Example:
+ Example:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 2
@@ -1618,10 +1602,9 @@ void QApplication::setColorSpec(int spec)
\brief the minimum size that any GUI element that the user can interact
with should have
- For example, no button should be resized to be smaller than the
- global strut size. The strut size should be considered when
- reimplementing GUI controls that may be used on touch-screens or
- similar I/O devices.
+ For example, no button should be resized to be smaller than the global
+ strut size. The strut size should be considered when reimplementing GUI
+ controls that may be used on touch-screens or similar I/O devices.
Example:
@@ -1655,12 +1638,11 @@ QPalette QApplication::palette()
\fn QPalette QApplication::palette(const QWidget* widget)
\overload
- If a \a widget is passed, the default palette for the
- widget's class is returned. This may or may not be the application
- palette. In most cases there isn't a special palette for certain
- types of widgets, but one notable exception is the popup menu
- under Windows, if the user has defined a special background color
- for menus in the display settings.
+ If a \a widget is passed, the default palette for the widget's class is
+ returned. This may or may not be the application palette. In most cases
+ there is no special palette for certain types of widgets, but one notable
+ exception is the popup menu under Windows, if the user has defined a
+ special background color for menus in the display settings.
\sa setPalette(), QWidget::palette()
*/
@@ -1754,26 +1736,26 @@ void QApplicationPrivate::setPalette_helper(const QPalette &palette, const char*
}
/*!
- Changes the default application palette to \a palette.
+ Changes the default application palette to \a palette.
- If \a className is passed, the change applies only to widgets that
- inherit \a className (as reported by QObject::inherits()). If
- \a className is left 0, the change affects all widgets, thus overriding
- any previously set class specific palettes.
+ If \a className is passed, the change applies only to widgets that inherit
+ \a className (as reported by QObject::inherits()). If \a className is left
+ 0, the change affects all widgets, thus overriding any previously set class
+ specific palettes.
- The palette may be changed according to the current GUI style in
- QStyle::polish().
+ The palette may be changed according to the current GUI style in
+ QStyle::polish().
- \warning Do not use this function in conjunction with \l{Qt Style Sheets}.
- When using style sheets, the palette of a widget can be customized using the "color",
- "background-color", "selection-color", "selection-background-color" and
- "alternate-background-color".
+ \warning Do not use this function in conjunction with \l{Qt Style Sheets}.
+ When using style sheets, the palette of a widget can be customized using
+ the "color", "background-color", "selection-color",
+ "selection-background-color" and "alternate-background-color".
- Note that some styles do not use the palette for all drawing,
- for instance, if they make use of native theme engines. This is
- the case for the Windows XP, Windows Vista, and Mac OS X styles.
+ \note Some styles do not use the palette for all drawing, for instance, if
+ they make use of native theme engines. This is the case for the Windows XP,
+ Windows Vista, and Mac OS X styles.
- \sa QWidget::setPalette(), palette(), QStyle::polish()
+ \sa QWidget::setPalette(), palette(), QStyle::polish()
*/
void QApplication::setPalette(const QPalette &palette, const char* className)
@@ -1878,15 +1860,15 @@ QFont QApplication::font(const char *className)
/*!
- Changes the default application font to \a font. If \a className
- is passed, the change applies only to classes that inherit \a
- className (as reported by QObject::inherits()).
+ Changes the default application font to \a font. If \a className is passed,
+ the change applies only to classes that inherit \a className (as reported
+ by QObject::inherits()).
- On application start-up, the default font depends on the window
- system. It can vary depending on both the window system version and
- the locale. This function lets you override the default font; but
- overriding may be a bad idea because, for example, some locales need
- extra large fonts to support their special characters.
+ On application start-up, the default font depends on the window system. It
+ can vary depending on both the window system version and the locale. This
+ function lets you override the default font; but overriding may be a bad
+ idea because, for example, some locales need extra large fonts to support
+ their special characters.
\warning Do not use this function in conjunction with \l{Qt Style Sheets}.
The font of an application can be customized using the "font" style sheet
@@ -1988,11 +1970,10 @@ void QApplication::setWindowIcon(const QIcon &icon)
}
/*!
- Returns a list of the top-level widgets (windows) in the
- application.
+ Returns a list of the top-level widgets (windows) in the application.
- Note that some of the top-level widgets may be hidden, for
- example a tooltip if no tooltip is currently shown.
+ \note Some of the top-level widgets may be hidden, for example a tooltip if
+ no tooltip is currently shown.
Example:
@@ -2018,7 +1999,7 @@ QWidgetList QApplication::topLevelWidgets()
The list is empty (QList::isEmpty()) if there are no widgets.
- Note that some of the widgets may be hidden.
+ \note Some of the widgets may be hidden.
Example:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 5
@@ -2037,10 +2018,10 @@ QWidgetList QApplication::allWidgets()
}
/*!
- Returns the application widget that has the keyboard input focus, or
- 0 if no widget in this application has the focus.
+ Returns the application widget that has the keyboard input focus, or 0 if
+ no widget in this application has the focus.
- \sa QWidget::setFocus(), QWidget::hasFocus(), activeWindow(), focusChanged()
+ \sa QWidget::setFocus(), QWidget::hasFocus(), activeWindow(), focusChanged()
*/
QWidget *QApplication::focusWidget()
@@ -2121,12 +2102,12 @@ void QApplicationPrivate::setFocusWidget(QWidget *focus, Qt::FocusReason reason)
/*!
- Returns the application top-level window that has the keyboard input
- focus, or 0 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.
+ Returns the application top-level window that has the keyboard input focus,
+ or 0 if no application window has the focus. There might be an
+ activeWindow() even if there is no focusWidget(), for example if no widget
+ in that window accepts key events.
- \sa QWidget::setFocus(), QWidget::hasFocus(), focusWidget()
+ \sa QWidget::setFocus(), QWidget::hasFocus(), focusWidget()
*/
QWidget *QApplication::activeWindow()
@@ -2135,9 +2116,9 @@ QWidget *QApplication::activeWindow()
}
/*!
- Returns display (screen) font metrics for the application font.
+ Returns display (screen) font metrics for the application font.
- \sa font(), setFont(), QWidget::fontMetrics(), QPainter::fontMetrics()
+ \sa font(), setFont(), QWidget::fontMetrics(), QPainter::fontMetrics()
*/
QFontMetrics QApplication::fontMetrics()
@@ -2149,19 +2130,20 @@ QFontMetrics QApplication::fontMetrics()
/*!
Closes all top-level windows.
- This function is particularly useful for applications with many
- top-level windows. It could, for example, be connected to a
- \gui{Exit} entry in the \gui{File} menu:
+ This function is particularly useful for applications with many top-level
+ windows. It could, for example, be connected to a \gui{Exit} entry in the
+ \gui{File} menu:
\snippet examples/mainwindows/mdi/mainwindow.cpp 0
- The windows are closed in random order, until one window does not
- accept the close event. The application quits when the last window
- was successfully closed; this can be turned off by setting \l
- quitOnLastWindowClosed to false.
+ The windows are closed in random order, until one window does not accept
+ the close event. The application quits when the last window was
+ successfully closed; this can be turned off by setting
+ \l quitOnLastWindowClosed to false.
- \sa quitOnLastWindowClosed, lastWindowClosed() QWidget::close(), QWidget::closeEvent(), lastWindowClosed(),
- quit(), topLevelWidgets(), QWidget::isWindow()
+ \sa quitOnLastWindowClosed, lastWindowClosed(), QWidget::close(),
+ QWidget::closeEvent(), lastWindowClosed(), quit(), topLevelWidgets(),
+ QWidget::isWindow()
*/
void QApplication::closeAllWindows()
{
@@ -2184,11 +2166,11 @@ void QApplication::closeAllWindows()
}
/*!
- Displays a simple message box about Qt. The message includes the
- version number of Qt being used by the application.
+ Displays a simple message box about Qt. The message includes the version
+ number of Qt being used by the application.
- This is useful for inclusion in the \gui Help menu of an application,
- as shown in the \l{mainwindows/menus}{Menus} example.
+ This is useful for inclusion in the \gui Help menu of an application, as
+ shown in the \l{mainwindows/menus}{Menus} example.
This function is a convenience slot for QMessageBox::aboutQt().
*/
@@ -2209,22 +2191,20 @@ void QApplication::aboutQt()
/*!
\fn void QApplication::lastWindowClosed()
- This signal is emitted from QApplication::exec() when the last
- visible primary window (i.e. window with no parent) with the
- Qt::WA_QuitOnClose attribute set is closed.
+ This signal is emitted from QApplication::exec() when the last visible
+ primary window (i.e. window with no parent) with the Qt::WA_QuitOnClose
+ attribute set is closed.
By default,
\list
+ \o this attribute is set for all widgets except transient windows such
+ as splash screens, tool windows, and popup menus
- \i this attribute is set for all widgets except transient windows
- such as splash screens, tool windows, and popup menus
-
- \i QApplication implicitly quits when this signal is emitted.
-
+ \o QApplication implicitly quits when this signal is emitted.
\endlist
- This feature be turned off by setting \l quitOnLastWindowClosed to
+ This feature can be turned off by setting \l quitOnLastWindowClosed to
false.
\sa QWidget::close()
@@ -2234,15 +2214,15 @@ void QApplication::aboutQt()
\since 4.1
\fn void QApplication::focusChanged(QWidget *old, QWidget *now)
- This signal is emitted when the widget that has keyboard focus
- changed from \a old to \a now, i.e. because the user pressed the
- tab-key, clicked into a widget or changed the active window. Note
- that both \a old and \a now can be the null-pointer.
+ This signal is emitted when the widget that has keyboard focus changed from
+ \a old to \a now, i.e., because the user pressed the tab-key, clicked into
+ a widget or changed the active window. Both \a old and \a now can be the
+ null-pointer.
- The signal is emitted after both widget have been notified about
- the change through QFocusEvent.
+ The signal is emitted after both widget have been notified about the change
+ through QFocusEvent.
- \sa QWidget::setFocus() QWidget::clearFocus() Qt::FocusReason
+ \sa QWidget::setFocus(), QWidget::clearFocus(), Qt::FocusReason
*/
/*!
@@ -2251,10 +2231,10 @@ void QApplication::aboutQt()
This signal is emitted when application fonts are loaded or removed.
- \sa QFontDatabase::addApplicationFont()
- \sa QFontDatabase::addApplicationFontFromData()
- \sa QFontDatabase::removeAllApplicationFonts()
- \sa QFontDatabase::removeApplicationFont()
+ \sa QFontDatabase::addApplicationFont(),
+ QFontDatabase::addApplicationFontFromData(),
+ QFontDatabase::removeAllApplicationFonts(),
+ QFontDatabase::removeApplicationFont()
*/
#ifndef QT_NO_TRANSLATION
@@ -2351,18 +2331,17 @@ void QApplication::syncX() {} // do nothing
\fn void QApplication::setActiveWindow(QWidget* active)
Sets the active window to the \a active widget in response to a system
- event. The function is called from the platform specific event
- handlers.
+ event. The function is called from the platform specific event handlers.
- \warning This function does \e not set the keyboard focus to the
- active widget. Call QWidget::activateWindow() instead.
+ \warning This function does \e not set the keyboard focus to the active
+ widget. Call QWidget::activateWindow() instead.
- It sets the activeWindow() and focusWidget() attributes and sends
- proper \l{QEvent::WindowActivate}{WindowActivate}/\l{QEvent::WindowDeactivate}{WindowDeactivate}
- and \l{QEvent::FocusIn}{FocusIn}/\l{QEvent::FocusOut}{FocusOut} events
- to all appropriate widgets. The window will then be painted in
- active state (e.g. cursors in line edits will blink), and it will
- have tool tips enabled.
+ It sets the activeWindow() and focusWidget() attributes and sends proper
+ \l{QEvent::WindowActivate}{WindowActivate}/\l{QEvent::WindowDeactivate}
+ {WindowDeactivate} and \l{QEvent::FocusIn}{FocusIn}/\l{QEvent::FocusOut}
+ {FocusOut} events to all appropriate widgets. The window will then be
+ painted in active state (e.g. cursors in line edits will blink), and it
+ will have tool tips enabled.
\sa activeWindow(), QWidget::activateWindow()
*/
@@ -2508,11 +2487,11 @@ QWidget *QApplicationPrivate::focusNextPrevChild_helper(QWidget *toplevel, bool
}
/*!
- \fn void QApplicationPrivate::dispatchEnterLeave(QWidget* enter, QWidget* leave)
- \internal
+ \fn void QApplicationPrivate::dispatchEnterLeave(QWidget* enter, QWidget* leave)
+ \internal
- Creates the proper Enter/Leave event when widget \a enter is entered
- and widget \a leave is left.
+ Creates the proper Enter/Leave event when widget \a enter is entered and
+ widget \a leave is left.
*/
#if defined(Q_WS_WIN)
extern void qt_win_set_cursor(QWidget *, bool);
@@ -3029,11 +3008,11 @@ void QApplicationPrivate::sendSyntheticEnterLeave(QWidget *widget)
/*!
Returns the desktop widget (also called the root window).
- Note that the desktop may be composed of multiple screens, so it would be
- incorrect, for example, to attempt to \e center some widget in the
- desktop's geometry. QDesktopWidget has various functions for obtaining
- useful geometries upon the desktop, such as QDesktopWidget::screenGeometry()
- and QDesktopWidget::availableGeometry().
+ The desktop may be composed of multiple screens, so it would be incorrect,
+ for example, to attempt to \e center some widget in the desktop's geometry.
+ QDesktopWidget has various functions for obtaining useful geometries upon
+ the desktop, such as QDesktopWidget::screenGeometry() and
+ QDesktopWidget::availableGeometry().
On X11, it is also possible to draw on the desktop.
*/
@@ -3048,10 +3027,10 @@ QDesktopWidget *QApplication::desktop()
#ifndef QT_NO_CLIPBOARD
/*!
- Returns a pointer to the application global clipboard.
+ Returns a pointer to the application global clipboard.
- \note The QApplication object should already be constructed before
- accessing the clipboard.
+ \note The QApplication object should already be constructed before
+ accessing the clipboard.
*/
QClipboard *QApplication::clipboard()
{
@@ -3067,11 +3046,11 @@ QClipboard *QApplication::clipboard()
#endif // QT_NO_CLIPBOARD
/*!
- Sets whether Qt should use the system's standard colors, fonts,
- etc., to \a on. By default, this is true.
+ Sets whether Qt should use the system's standard colors, fonts, etc., to
+ \a on. By default, this is true.
- This function must be called before creating the QApplication
- object, like this:
+ This function must be called before creating the QApplication object, like
+ this:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 6
@@ -3083,8 +3062,8 @@ void QApplication::setDesktopSettingsAware(bool on)
}
/*!
- Returns true if Qt is set to use the system's standard colors,
- fonts, etc.; otherwise returns false. The default is true.
+ Returns true if Qt is set to use the system's standard colors, fonts, etc.;
+ otherwise returns false. The default is true.
\sa setDesktopSettingsAware()
*/
@@ -3094,17 +3073,17 @@ bool QApplication::desktopSettingsAware()
}
/*!
- Returns the current state of the modifier keys on the keyboard. The
- current state is updated sychronously as the event queue is emptied
- of events that will spontaneously change the keyboard state
- (QEvent::KeyPress and QEvent::KeyRelease events).
+ Returns the current state of the modifier keys on the keyboard. The current
+ state is updated sychronously as the event queue is emptied of events that
+ will spontaneously change the keyboard state (QEvent::KeyPress and
+ QEvent::KeyRelease events).
- It should be noted this may not reflect the actual keys held on the
- input device at the time of calling but rather the modifiers as
- last reported in one of the above events. If no keys are being held
- Qt::NoModifier is returned.
+ It should be noted this may not reflect the actual keys held on the input
+ device at the time of calling but rather the modifiers as last reported in
+ one of the above events. If no keys are being held Qt::NoModifier is
+ returned.
- \sa mouseButtons()
+ \sa mouseButtons()
*/
Qt::KeyboardModifiers QApplication::keyboardModifiers()
@@ -3113,17 +3092,17 @@ Qt::KeyboardModifiers QApplication::keyboardModifiers()
}
/*!
- Returns the current state of the buttons on the mouse. The current
- state is updated syncronously as the event queue is emptied of
- events that will spontaneously change the mouse state
- (QEvent::MouseButtonPress and QEvent::MouseButtonRelease events).
+ Returns the current state of the buttons on the mouse. The current state is
+ updated syncronously as the event queue is emptied of events that will
+ spontaneously change the mouse state (QEvent::MouseButtonPress and
+ QEvent::MouseButtonRelease events).
- It should be noted this may not reflect the actual buttons held on
- theinput device at the time of calling but rather the mouse buttons
- as last reported in one of the above events. If no mouse buttons are
- being held Qt::NoButton is returned.
+ It should be noted this may not reflect the actual buttons held on the
+ input device at the time of calling but rather the mouse buttons as last
+ reported in one of the above events. If no mouse buttons are being held
+ Qt::NoButton is returned.
- \sa keyboardModifiers()
+ \sa keyboardModifiers()
*/
Qt::MouseButtons QApplication::mouseButtons()
@@ -3132,43 +3111,40 @@ Qt::MouseButtons QApplication::mouseButtons()
}
/*!
- \fn bool QApplication::isSessionRestored() const
+ \fn bool QApplication::isSessionRestored() const
- Returns true if the application has been restored from an earlier
- \link session.html session\endlink; otherwise returns false.
+ Returns true if the application has been restored from an earlier
+ \l{Session Management}{session}; otherwise returns false.
- \sa sessionId(), commitData(), saveState()
+ \sa sessionId(), commitData(), saveState()
*/
/*!
- \fn QString QApplication::sessionId() const
+ \fn QString QApplication::sessionId() const
- Returns the current \link session.html session's\endlink identifier.
+ Returns the current \l{Session Management}{session's} identifier.
- If the application has been restored from an earlier session, this
- identifier is the same as it was in that previous session.
+ If the application has been restored from an earlier session, this
+ identifier is the same as it was in that previous session. The session
+ identifier is guaranteed to be unique both for different applications
+ and for different instances of the same application.
- The session identifier is guaranteed to be unique both for different
- applications and for different instances of the same application.
-
- \sa isSessionRestored(), sessionKey(), commitData(), saveState()
- */
+ \sa isSessionRestored(), sessionKey(), commitData(), saveState()
+*/
/*!
- \fn QString QApplication::sessionKey() const
+ \fn QString QApplication::sessionKey() const
- Returns the session key in the current \link session.html
- session\endlink.
+ Returns the session key in the current \l{Session Management}{session}.
- If the application has been restored from an earlier session, this
- key is the same as it was when the previous session ended.
+ If the application has been restored from an earlier session, this key is
+ the same as it was when the previous session ended.
- The session key changes with every call of commitData() or
- saveState().
+ The session key changes with every call of commitData() or saveState().
- \sa isSessionRestored(), sessionId(), commitData(), saveState()
- */
+ \sa isSessionRestored(), sessionId(), commitData(), saveState()
+*/
#ifndef QT_NO_SESSIONMANAGER
bool QApplication::isSessionRestored() const
{
@@ -3191,59 +3167,57 @@ QString QApplication::sessionKey() const
-
-
/*!
- \since 4.2
- \fn void QApplication::commitDataRequest(QSessionManager &manager)
+ \since 4.2
+ \fn void QApplication::commitDataRequest(QSessionManager &manager)
- This signal deals with \link session.html session
- management\endlink. It is emitted when the QSessionManager wants the
- application to commit all its data.
+ This signal deals with \l{Session Management}{session management}. It is
+ emitted when the QSessionManager wants the application to commit all its
+ data.
- Usually this means saving all open files, after getting
- permission from the user. Furthermore you may want to provide a means
- by which the user can cancel the shutdown.
+ Usually this means saving all open files, after getting permission from
+ the user. Furthermore you may want to provide a means by which the user
+ can cancel the shutdown.
- Note that you should not exit the application when called.
- Instead, the session manager may or may not do this afterwards,
- depending on the context.
+ You should not exit the application within this signal. Instead,
+ the session manager may or may not do this afterwards, depending on the
+ context.
- \warning Within this signal, no user interaction is possible, \e
- unless you ask the \a manager for explicit permission. See
- QSessionManager::allowsInteraction() and
- QSessionManager::allowsErrorInteraction() for details and example
- usage.
+ \warning Within this signal, no user interaction is possible, \e
+ unless you ask the \a manager for explicit permission. See
+ QSessionManager::allowsInteraction() and
+ QSessionManager::allowsErrorInteraction() for details and example
+ usage.
- Note: You should use Qt::DirectConnection when connecting to this signal.
+ \note You should use Qt::DirectConnection when connecting to this signal.
- \sa isSessionRestored(), sessionId(), saveState(), {Session Management}
+ \sa isSessionRestored(), sessionId(), saveState(), {Session Management}
*/
/*!
- This function deals with \link session.html session
- management\endlink. It is invoked when the QSessionManager wants the
- application to commit all its data.
+ This function deals with \l{Session Management}{session management}. It is
+ invoked when the QSessionManager wants the application to commit all its
+ data.
- Usually this means saving all open files, after getting
- permission from the user. Furthermore you may want to provide a means
- by which the user can cancel the shutdown.
+ Usually this means saving all open files, after getting permission from the
+ user. Furthermore you may want to provide a means by which the user can
+ cancel the shutdown.
- 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.
+ You should not exit the application within this function. Instead, the
+ session manager may or may not do this afterwards, depending on the
+ context.
- \warning Within this function, no user interaction is possible, \e
- unless you ask the \a manager for explicit permission. See
- QSessionManager::allowsInteraction() and
- QSessionManager::allowsErrorInteraction() for details and example
- usage.
+ \warning Within this function, no user interaction is possible, \e
+ unless you ask the \a manager for explicit permission. See
+ QSessionManager::allowsInteraction() and
+ QSessionManager::allowsErrorInteraction() for details and example
+ usage.
- The default implementation requests interaction and sends a close
- event to all visible top-level widgets. If any event was
- rejected, the shutdown is canceled.
+ The default implementation requests interaction and sends a close event to
+ all visible top-level widgets. If any event was rejected, the shutdown is
+ canceled.
- \sa isSessionRestored(), sessionId(), saveState(), {Session Management}
+ \sa isSessionRestored(), sessionId(), saveState(), {Session Management}
*/
#ifndef QT_NO_SESSIONMANAGER
void QApplication::commitData(QSessionManager& manager )
@@ -3269,58 +3243,54 @@ void QApplication::commitData(QSessionManager& manager )
}
/*!
- \since 4.2
- \fn void QApplication::saveStateRequest(QSessionManager &manager)
+ \since 4.2
+ \fn void QApplication::saveStateRequest(QSessionManager &manager)
- This signal deals with \link session.html session
- management\endlink. It is invoked when the
- \link QSessionManager session manager \endlink wants the application
- to preserve its state for a future session.
+ This signal deals with \l{Session Management}{session management}. It is
+ invoked when the \l{QSessionManager}{session manager} wants the application
+ to preserve its state for a future session.
- For example, a text editor would create a temporary file that
- includes the current contents of its edit buffers, the location of
- the cursor and other aspects of the current editing session.
+ For example, a text editor would create a temporary file that includes the
+ current contents of its edit buffers, the location of the cursor and other
+ aspects of the current editing session.
- Note that you should never exit the application within this
- signal. Instead, the session manager may or may not do this
- afterwards, depending on the context. Futhermore, most session
- managers will very likely request a saved state immediately after
- the application has been started. This permits the session manager
- to learn about the application's restart policy.
+ You should never exit the application within this signal. Instead, the
+ session manager may or may not do this afterwards, depending on the
+ context. Futhermore, most session managers will very likely request a saved
+ state immediately after the application has been started. This permits the
+ session manager to learn about the application's restart policy.
- \warning Within this function, no user interaction is possible, \e
- unless you ask the \a manager for explicit permission. See
- QSessionManager::allowsInteraction() and
- QSessionManager::allowsErrorInteraction() for details.
+ \warning Within this function, no user interaction is possible, \e
+ unless you ask the \a manager for explicit permission. See
+ QSessionManager::allowsInteraction() and
+ QSessionManager::allowsErrorInteraction() for details.
- Note:: You should use Qt::DirectConnection when connecting to this signal.
+ \note You should use Qt::DirectConnection when connecting to this signal.
- \sa isSessionRestored(), sessionId(), commitData(), {Session Management}
+ \sa isSessionRestored(), sessionId(), commitData(), {Session Management}
*/
/*!
- This function deals with \link session.html session
- management\endlink. It is invoked when the
- \link QSessionManager session manager \endlink wants the application
- to preserve its state for a future session.
+ This function deals with \l{Session Management}{session management}. It is
+ invoked when the \l{QSessionManager}{session manager} wants the application
+ to preserve its state for a future session.
- For example, a text editor would create a temporary file that
- includes the current contents of its edit buffers, the location of
- the cursor and other aspects of the current editing session.
+ For example, a text editor would create a temporary file that includes the
+ current contents of its edit buffers, the location of the cursor and other
+ aspects of the current editing session.
- Note that you should never exit the application within this
- function. Instead, the session manager may or may not do this
- afterwards, depending on the context. Futhermore, most session
- managers will very likely request a saved state immediately after
- the application has been started. This permits the session manager
- to learn about the application's restart policy.
+ You should never exit the application within this function. Instead, the
+ session manager may or may not do this afterwards, depending on the
+ context. Futhermore, most session managers will very likely request a saved
+ state immediately after the application has been started. This permits the
+ session manager to learn about the application's restart policy.
- \warning Within this function, no user interaction is possible, \e
- unless you ask the \a manager for explicit permission. See
- QSessionManager::allowsInteraction() and
- QSessionManager::allowsErrorInteraction() for details.
+ \warning Within this function, no user interaction is possible, \e
+ unless you ask the \a manager for explicit permission. See
+ QSessionManager::allowsInteraction() and
+ QSessionManager::allowsErrorInteraction() for details.
- \sa isSessionRestored(), sessionId(), commitData(), {Session Management}
+ \sa isSessionRestored(), sessionId(), commitData(), {Session Management}
*/
void QApplication::saveState(QSessionManager &manager)
@@ -3344,13 +3314,12 @@ void QApplication::setStartDragTime(int ms)
\brief the time in milliseconds that a mouse button must be held down
before a drag and drop operation will begin
- If you support drag and drop in your application, and want to start a
- drag and drop operation after the user has held down a mouse button for
- a certain amount of time, you should use this property's value as the
- delay.
+ If you support drag and drop in your application, and want to start a drag
+ and drop operation after the user has held down a mouse button for a
+ certain amount of time, you should use this property's value as the delay.
- Qt also uses this delay internally, e.g. in QTextEdit and QLineEdit,
- for starting a drag.
+ Qt also uses this delay internally, e.g. in QTextEdit and QLineEdit, for
+ starting a drag.
The default value is 500 ms.
@@ -3363,9 +3332,9 @@ int QApplication::startDragTime()
}
/*
- Sets the distance after which a drag should start to \a l pixels.
+ Sets the distance after which a drag should start to \a l pixels.
- \sa startDragDistance()
+ \sa startDragDistance()
*/
void QApplication::setStartDragDistance(int l)
@@ -3376,15 +3345,14 @@ void QApplication::setStartDragDistance(int l)
/*!
\property QApplication::startDragDistance
- If you support drag and drop in your application, and want to start a
- drag and drop operation after the user has moved the cursor a certain
- distance with a button held down, you should use this property's value
- as the minimum distance required.
+ If you support drag and drop in your application, and want to start a drag
+ and drop operation after the user has moved the cursor a certain distance
+ with a button held down, you should use this property's value as the
+ minimum distance required.
- For example, if the mouse position of the click is stored in \c
- startPos and the current position (e.g. in the mouse move event) is
- \c currentPos, you can find out if a drag should be started with code
- like this:
+ For example, if the mouse position of the click is stored in \c startPos
+ and the current position (e.g. in the mouse move event) is \c currentPos,
+ you can find out if a drag should be started with code like this:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 7
@@ -3430,14 +3398,14 @@ int QApplication::startDragDistance()
\sa layoutDirection(), isRightToLeft()
*/
-/*! \property QApplication::layoutDirection
-
- \brief the default layout direction for this application
+/*!
+ \property QApplication::layoutDirection
+ \brief the default layout direction for this application
- On system start-up, the default layout direction depends on the
- application's language.
+ On system start-up, the default layout direction depends on the
+ application's language.
- \sa QWidget::layoutDirection, isLeftToRight(), isRightToLeft()
+ \sa QWidget::layoutDirection, isLeftToRight(), isRightToLeft()
*/
void QApplication::setLayoutDirection(Qt::LayoutDirection direction)
@@ -3461,11 +3429,12 @@ Qt::LayoutDirection QApplication::layoutDirection()
}
-/*! \obsolete
+/*!
+ \obsolete
- Strips out vertical alignment flags and transforms an
- alignment \a align of Qt::AlignLeft into Qt::AlignLeft or
- Qt::AlignRight according to the language used.
+ Strips out vertical alignment flags and transforms an alignment \a align
+ of Qt::AlignLeft into Qt::AlignLeft or Qt::AlignRight according to the
+ language used.
*/
#ifdef QT3_SUPPORT
@@ -3481,8 +3450,8 @@ Qt::Alignment QApplication::horizontalAlignment(Qt::Alignment align)
Returns the active application override cursor.
- This function returns 0 if no application cursor has been defined
- (i.e. the internal cursor stack is empty).
+ This function returns 0 if no application cursor has been defined (i.e. the
+ internal cursor stack is empty).
\sa setOverrideCursor(), restoreOverrideCursor()
*/
@@ -3495,9 +3464,10 @@ QCursor *QApplication::overrideCursor()
/*!
Changes the currently active application override cursor to \a cursor.
- This function has no effect if setOverrideCursor() wasn't called.
+ This function has no effect if setOverrideCursor() was not called.
- \sa setOverrideCursor() overrideCursor() restoreOverrideCursor() QWidget::setCursor()
+ \sa setOverrideCursor(), overrideCursor(), restoreOverrideCursor(),
+ QWidget::setCursor()
*/
void QApplication::changeOverrideCursor(const QCursor &cursor)
{
@@ -3511,8 +3481,8 @@ void QApplication::changeOverrideCursor(const QCursor &cursor)
/*!
\fn void QApplication::setOverrideCursor(const QCursor &cursor, bool replace)
- Use changeOverrideCursor(\a cursor) (if \a replace is true)
- or setOverrideCursor(\a cursor) (if \a replace is false).
+ Use changeOverrideCursor(\a cursor) (if \a replace is true) or
+ setOverrideCursor(\a cursor) (if \a replace is false).
*/
/*!
@@ -3520,29 +3490,26 @@ void QApplication::changeOverrideCursor(const QCursor &cursor)
the value that was set to exit() (which is 0 if exit() is called via
quit()).
- 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.
+ 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.
+
+ 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 widgets call exec() to start a local event loop.
- Generally speaking, 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 widgets call
- exec() to start a local event loop.
-
- 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 using processEvents().
+ 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 using processEvents().
We recommend that you connect clean-up code to the
- \l{QCoreApplication::}{aboutToQuit()} signal, instead of putting it in
- your application's \c{main()} function because on some platforms the
- QApplication::exec() call may not return. For example, on Windows
- when the user logs off, the system terminates the process after Qt
- closes all top-level windows. Hence, there is no guarantee that the
- application will have time to exit its event loop and execute code at
- the end of the \c{main()} function after the QApplication::exec()
- call.
+ \l{QCoreApplication::}{aboutToQuit()} signal, instead of putting it in your
+ application's \c{main()} function because on some platforms the
+ QApplication::exec() call may not return. For example, on Windows when the
+ user logs off, the system terminates the process after Qt closes all
+ top-level windows. Hence, there is no guarantee that the application will
+ have time to exit its event loop and execute code at the end of the
+ \c{main()} function after the QApplication::exec() call.
\sa quitOnLastWindowClosed, quit(), exit(), processEvents(),
QCoreApplication::exec()
@@ -4090,101 +4057,98 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e)
/*!
- \class QSessionManager
- \brief The QSessionManager class provides access to the session manager.
-
- \ingroup application
- \ingroup environment
-
- A session manager in a desktop environment (in which Qt GUI
- applications live) keeps track of a session, which is a group of
- running applications, each of which has a particular state. The
- state of an application contains (most notably) the documents the
- application has open and the position and size of its windows.
-
- The session manager is used to save the session, e.g. when the
- machine is shut down, and to restore a session, e.g. when the
- machine is started up. We recommend that you use QSettings to save
- an individual application's settings, e.g. window positions,
- recently used files, etc. When the application is restarted by the
- session manager, you can restore the settings.
-
- QSessionManager provides an interface between the application
- and the session manager so that the program can work well with the
- session manager. In Qt, session management requests for action are
- handled by the two virtual functions QApplication::commitData()
- and QApplication::saveState(). Both provide a reference to a
- session manager object as argument, to allow the application to
- communicate with the session manager. The session manager can only
- be accessed through these functions.
-
- No user interaction is possible \e unless the application gets
- explicit permission from the session manager. You ask for permission
- by calling allowsInteraction() or, if it's really urgent,
- allowsErrorInteraction(). Qt does not enforce this, but the session
- manager may.
-
- You can try to abort the shutdown process by calling cancel(). The
- default commitData() function does this if some top-level window
- rejected its closeEvent().
-
- For sophisticated session managers provided on Unix/X11, QSessionManager
- offers further possibilities to fine-tune an application's session
- management behavior: setRestartCommand(), setDiscardCommand(),
- setRestartHint(), setProperty(), requestPhase2(). See the respective
- function descriptions for further details.
-
- \sa QApplication, {Session Management}
+ \class QSessionManager
+ \brief The QSessionManager class provides access to the session manager.
+
+ \ingroup application
+ \ingroup environment
+
+ A session manager in a desktop environment (in which Qt GUI applications
+ live) keeps track of a session, which is a group of running applications,
+ each of which has a particular state. The state of an application contains
+ (most notably) the documents the application has open and the position and
+ size of its windows.
+
+ The session manager is used to save the session, e.g., when the machine is
+ shut down, and to restore a session, e.g., when the machine is started up.
+ We recommend that you use QSettings to save an application's settings,
+ for example, window positions, recently used files, etc. When the
+ application is restarted by the session manager, you can restore the
+ settings.
+
+ QSessionManager provides an interface between the application and the
+ session manager so that the program can work well with the session manager.
+ In Qt, session management requests for action are handled by the two
+ virtual functions QApplication::commitData() and QApplication::saveState().
+ Both provide a reference to a session manager object as argument, to allow
+ the application to communicate with the session manager. The session
+ manager can only be accessed through these functions.
+
+ No user interaction is possible \e unless the application gets explicit
+ permission from the session manager. You ask for permission by calling
+ allowsInteraction() or, if it is really urgent, allowsErrorInteraction().
+ Qt does not enforce this, but the session manager may.
+
+ You can try to abort the shutdown process by calling cancel(). The default
+ commitData() function does this if some top-level window rejected its
+ closeEvent().
+
+ For sophisticated session managers provided on Unix/X11, QSessionManager
+ offers further possibilities to fine-tune an application's session
+ management behavior: setRestartCommand(), setDiscardCommand(),
+ setRestartHint(), setProperty(), requestPhase2(). See the respective
+ function descriptions for further details.
+
+ \sa QApplication, {Session Management}
*/
/*! \enum QSessionManager::RestartHint
- This enum type defines the circumstances under which this
- application wants to be restarted by the session manager. The
- current values are
+ This enum type defines the circumstances under which this application wants
+ to be restarted by the session manager. The current values are:
- \value RestartIfRunning if the application is still running when
- the session is shut down, it wants to be restarted at the start of
- the next session.
+ \value RestartIfRunning If the application is still running when the
+ session is shut down, it wants to be restarted
+ at the start of the next session.
- \value RestartAnyway the application wants to be started at the
- start of the next session, no matter what. (This is useful for
- utilities that run just after startup and then quit.)
+ \value RestartAnyway The application wants to be started at the
+ start of the next session, no matter what.
+ (This is useful for utilities that run just
+ after startup and then quit.)
- \value RestartImmediately the application wants to be started
- immediately whenever it is not running.
+ \value RestartImmediately The application wants to be started immediately
+ whenever it is not running.
- \value RestartNever the application does not want to be restarted
- automatically.
+ \value RestartNever The application does not want to be restarted
+ automatically.
- The default hint is \c RestartIfRunning.
+ The default hint is \c RestartIfRunning.
*/
/*!
- \fn QString QSessionManager::sessionId() const
+ \fn QString QSessionManager::sessionId() const
- Returns the identifier of the current session.
+ Returns the identifier of the current session.
- If the application has been restored from an earlier session, this
- identifier is the same as it was in that earlier session.
+ If the application has been restored from an earlier session, this
+ identifier is the same as it was in the earlier session.
- \sa sessionKey(), QApplication::sessionId()
- */
+ \sa sessionKey(), QApplication::sessionId()
+*/
/*!
- \fn QString QSessionManager::sessionKey() const
+ \fn QString QSessionManager::sessionKey() const
- Returns the session key in the current session.
+ Returns the session key in the current session.
- If the application has been restored from an earlier session, this
- key is the same as it was when the previous session ended.
+ If the application has been restored from an earlier session, this key is
+ the same as it was when the previous session ended.
- The session key changes with every call of commitData() or
- saveState().
+ The session key changes with every call of commitData() or saveState().
- \sa sessionId(), QApplication::sessionKey()
- */
+ \sa sessionId(), QApplication::sessionKey()
+*/
/*!
\fn void* QSessionManager::handle() const
@@ -4193,120 +4157,116 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e)
*/
/*!
- \fn bool QSessionManager::allowsInteraction()
+ \fn bool QSessionManager::allowsInteraction()
- Asks the session manager for permission to interact with the
- user. Returns true if interaction is permitted; otherwise
- returns false.
+ Asks the session manager for permission to interact with the user. Returns
+ true if interaction is permitted; otherwise returns false.
- The rationale behind this mechanism is to make it possible to
- synchronize user interaction during a shutdown. Advanced session
- managers may ask all applications simultaneously to commit their
- data, resulting in a much faster shutdown.
+ The rationale behind this mechanism is to make it possible to synchronize
+ user interaction during a shutdown. Advanced session managers may ask all
+ applications simultaneously to commit their data, resulting in a much
+ faster shutdown.
- When the interaction is completed we strongly recommend releasing the
- user interaction semaphore with a call to release(). This way, other
- applications may get the chance to interact with the user while your
- application is still busy saving data. (The semaphore is implicitly
- released when the application exits.)
+ When the interaction is completed we strongly recommend releasing the user
+ interaction semaphore with a call to release(). This way, other
+ applications may get the chance to interact with the user while your
+ application is still busy saving data. (The semaphore is implicitly
+ released when the application exits.)
- If the user decides to cancel the shutdown process during the
- interaction phase, you must tell the session manager that this has
- happened by calling cancel().
+ If the user decides to cancel the shutdown process during the interaction
+ phase, you must tell the session manager that this has happened by calling
+ cancel().
- Here's an example of how an application's QApplication::commitData()
- might be implemented:
+ Here's an example of how an application's QApplication::commitData() might
+ be implemented:
- \snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 8
+ \snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 8
- If an error occurred within the application while saving its data,
- you may want to try allowsErrorInteraction() instead.
+ If an error occurred within the application while saving its data, you may
+ want to try allowsErrorInteraction() instead.
- \sa QApplication::commitData(), release(), cancel()
+ \sa QApplication::commitData(), release(), cancel()
*/
/*!
- \fn bool QSessionManager::allowsErrorInteraction()
+ \fn bool QSessionManager::allowsErrorInteraction()
- Returns true if error interaction is permitted; otherwise returns false.
+ Returns true if error interaction is permitted; otherwise returns false.
- This is similar to allowsInteraction(), but also enables the application
- to tell the user about any errors that occur. Session managers
- may give error interaction requests higher priority, which means that it
- is more likely that an error interaction is permitted. However, you are
- still not guaranteed that the session manager will allow interaction.
+ This is similar to allowsInteraction(), but also enables the application to
+ tell the user about any errors that occur. Session managers may give error
+ interaction requests higher priority, which means that it is more likely
+ that an error interaction is permitted. However, you are still not
+ guaranteed that the session manager will allow interaction.
- \sa allowsInteraction(), release(), cancel()
+ \sa allowsInteraction(), release(), cancel()
*/
/*!
- \fn void QSessionManager::release()
+ \fn void QSessionManager::release()
- Releases the session manager's interaction semaphore after an
- interaction phase.
+ Releases the session manager's interaction semaphore after an interaction
+ phase.
- \sa allowsInteraction(), allowsErrorInteraction()
+ \sa allowsInteraction(), allowsErrorInteraction()
*/
/*!
- \fn void QSessionManager::cancel()
-
- Tells the session manager to cancel the shutdown process. Applications
- should not call this function without first asking the user.
+ \fn void QSessionManager::cancel()
- \sa allowsInteraction(), allowsErrorInteraction()
+ Tells the session manager to cancel the shutdown process. Applications
+ should not call this function without asking the user first.
+ \sa allowsInteraction(), allowsErrorInteraction()
*/
/*!
- \fn void QSessionManager::setRestartHint(RestartHint hint)
+ \fn void QSessionManager::setRestartHint(RestartHint hint)
- Sets the application's restart hint to \a hint. On application
- startup the hint is set to \c RestartIfRunning.
+ Sets the application's restart hint to \a hint. On application startup, the
+ hint is set to \c RestartIfRunning.
- Note that these flags are only hints, a session manager may or may
- not respect them.
+ \note These flags are only hints, a session manager may or may not respect
+ them.
- We recommend setting the restart hint in QApplication::saveState()
- because most session managers perform a checkpoint shortly after an
- application's startup.
+ We recommend setting the restart hint in QApplication::saveState() because
+ most session managers perform a checkpoint shortly after an application's
+ startup.
- \sa restartHint()
+ \sa restartHint()
*/
/*!
- \fn QSessionManager::RestartHint QSessionManager::restartHint() const
+ \fn QSessionManager::RestartHint QSessionManager::restartHint() const
- Returns the application's current restart hint. The default is
- \c RestartIfRunning.
+ Returns the application's current restart hint. The default is
+ \c RestartIfRunning.
- \sa setRestartHint()
+ \sa setRestartHint()
*/
/*!
- \fn void QSessionManager::setRestartCommand(const QStringList& command)
+ \fn void QSessionManager::setRestartCommand(const QStringList& command)
- If the session manager is capable of restoring sessions it will
- execute \a command in order to restore the application. The command
- defaults to
+ If the session manager is capable of restoring sessions it will execute
+ \a command in order to restore the application. The command defaults to
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 9
- The \c -session option is mandatory; otherwise QApplication cannot
- tell whether it has been restored or what the current session
- identifier is. See QApplication::isSessionRestored() and
- QApplication::sessionId() for details.
+ The \c -session option is mandatory; otherwise QApplication cannot tell
+ whether it has been restored or what the current session identifier is.
+ See QApplication::isSessionRestored() and QApplication::sessionId() for
+ details.
- If your application is very simple, it may be possible to store the
- entire application state in additional command line options. This
- is usually a very bad idea because command lines are often limited
- to a few hundred bytes. Instead, use QSettings, or temporary files
- or a database for this purpose. By marking the data with the unique
- sessionId(), you will be able to restore the application in a future
- session.
+ If your application is very simple, it may be possible to store the entire
+ application state in additional command line options. This is usually a
+ very bad idea because command lines are often limited to a few hundred
+ bytes. Instead, use QSettings, temporary files, or a database for this
+ purpose. By marking the data with the unique sessionId(), you will be able
+ to restore the application in a future session.
- \sa restartCommand(), setDiscardCommand(), setRestartHint()
+ \sa restartCommand(), setDiscardCommand(), setRestartHint()
*/
/*!
@@ -4314,8 +4274,7 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e)
Returns the currently set restart command.
- To iterate over the list, you can use the \l foreach
- pseudo-keyword:
+ To iterate over the list, you can use the \l foreach pseudo-keyword:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 10
@@ -4323,11 +4282,11 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e)
*/
/*!
- \fn void QSessionManager::setDiscardCommand(const QStringList& list)
+ \fn void QSessionManager::setDiscardCommand(const QStringList& list)
- Sets the discard command to the given \a list.
+ Sets the discard command to the given \a list.
- \sa discardCommand(), setRestartCommand()
+ \sa discardCommand(), setRestartCommand()
*/
@@ -4336,8 +4295,7 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e)
Returns the currently set discard command.
- To iterate over the list, you can use the \l foreach
- pseudo-keyword:
+ To iterate over the list, you can use the \l foreach pseudo-keyword:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 11
@@ -4345,53 +4303,51 @@ bool QApplicationPrivate::notify_helper(QObject *receiver, QEvent * e)
*/
/*!
- \fn void QSessionManager::setManagerProperty(const QString &name, const QString &value)
- \overload
+ \fn void QSessionManager::setManagerProperty(const QString &name, const QString &value)
+ \overload
- Low-level write access to the application's identification and state
- records are kept in the session manager.
+ Low-level write access to the application's identification and state
+ records are kept in the session manager.
- The property called \a name has its value set to the string \a value.
+ The property called \a name has its value set to the string \a value.
*/
/*!
- \fn void QSessionManager::setManagerProperty(const QString& name,
- const QStringList& value)
+ \fn void QSessionManager::setManagerProperty(const QString& name,
+ const QStringList& value)
- Low-level write access to the application's identification and state
- record are kept in the session manager.
+ Low-level write access to the application's identification and state record
+ are kept in the session manager.
- The property called \a name has its value set to the string list \a value.
+ The property called \a name has its value set to the string list \a value.
*/
/*!
- \fn bool QSessionManager::isPhase2() const
+ \fn bool QSessionManager::isPhase2() const
- Returns true if the session manager is currently performing a second
- session management phase; otherwise returns false.
+ Returns true if the session manager is currently performing a second
+ session management phase; otherwise returns false.
- \sa requestPhase2()
+ \sa requestPhase2()
*/
/*!
- \fn void QSessionManager::requestPhase2()
+ \fn void QSessionManager::requestPhase2()
- Requests a second session management phase for the application. The
- application may then return immediately from the
- QApplication::commitData() or QApplication::saveState() function,
- and they will be called again once most or all other applications have
- finished their session management.
+ Requests a second session management phase for the application. The
+ application may then return immediately from the QApplication::commitData()
+ or QApplication::saveState() function, and they will be called again once
+ most or all other applications have finished their session management.
- The two phases are useful for applications such as the X11 window manager
- that need to store information about another application's windows
- and therefore have to wait until these applications have completed their
- respective session management tasks.
+ The two phases are useful for applications such as the X11 window manager
+ that need to store information about another application's windows and
+ therefore have to wait until these applications have completed their
+ respective session management tasks.
- Note that if another application has requested a second phase it
- may get called before, simultaneously with, or after your
- application's second phase.
+ \note If another application has requested a second phase it may get called
+ before, simultaneously with, or after your application's second phase.
- \sa isPhase2()
+ \sa isPhase2()
*/
/*****************************************************************************
@@ -4584,15 +4540,14 @@ void QSessionManager::requestPhase2()
/*!
\fn bool QApplication::hasGlobalMouseTracking()
- This feature does not exist anymore. This function
- always returns true in Qt 4.
+ This feature does not exist anymore. This function always returns true
+ in Qt 4.
*/
/*!
\fn void QApplication::setGlobalMouseTracking(bool dummy)
- This function does nothing in Qt 4. The \a dummy parameter
- is ignored.
+ This function does nothing in Qt 4. The \a dummy parameter is ignored.
*/
/*!
@@ -4630,15 +4585,14 @@ void QSessionManager::requestPhase2()
/*!
\fn const QColor &QApplication::winStyleHighlightColor()
- Use qApp->palette().color(QPalette::Active, QPalette::Highlight)
- instead.
+ Use qApp->palette().color(QPalette::Active, QPalette::Highlight) instead.
*/
/*!
\fn QWidget *QApplication::widgetAt(int x, int y, bool child)
- Use the two-argument widgetAt() overload to get the child widget.
- To get the top-level widget do this:
+ Use the two-argument widgetAt() overload to get the child widget. To get
+ the top-level widget do this:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 12
*/
@@ -4646,8 +4600,8 @@ void QSessionManager::requestPhase2()
/*!
\fn QWidget *QApplication::widgetAt(const QPoint &point, bool child)
- Use the single-argument widgetAt() overload to get the child widget.
- To get the top-level widget do this:
+ Use the single-argument widgetAt() overload to get the child widget. To get
+ the top-level widget do this:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication.cpp 13
*/
@@ -4719,10 +4673,9 @@ void QApplicationPrivate::emitLastWindowClosed()
Sets whether Qt should use focus navigation suitable for use with a
minimal keypad.
- If \a enable is true, Qt::Key_Up and Qt::Key_Down are used to
- change focus.
+ If \a enable is true, Qt::Key_Up and Qt::Key_Down are used to change focus.
- This feature is only available in Qt for Embedded Linux.
+ This feature is available in Qt for Embedded Linux only.
\sa keypadNavigationEnabled()
*/
@@ -4735,7 +4688,8 @@ void QApplication::setKeypadNavigationEnabled(bool enable)
Returns true if Qt is set to use keypad navigation; otherwise returns
false. The default is false.
- This feature is only available in Qt for Embedded Linux.
+ This feature is available in Qt for Embedded Linux only.
+
\sa setKeypadNavigationEnabled()
*/
bool QApplication::keypadNavigationEnabled()
@@ -4758,12 +4712,12 @@ bool QApplication::keypadNavigationEnabled()
On Mac OS X, this works more at the application level and will cause the
application icon to bounce in the dock.
- On Windows this causes the window's taskbar entry to flash for a time. If \a
- msec is zero, the flashing will stop and the taskbar entry will turn a
+ On Windows this causes the window's taskbar entry to flash for a time. If
+ \a msec is zero, the flashing will stop and the taskbar entry will turn a
different color (currently orange).
- On X11, this will cause the window to be marked as "demands attention",
- the window must not be hidden (i.e. not have hide() called on it, but be
+ On X11, this will cause the window to be marked as "demands attention", the
+ window must not be hidden (i.e. not have hide() called on it, but be
visible in some sort of way) in order for this to work.
*/
@@ -4771,18 +4725,16 @@ bool QApplication::keypadNavigationEnabled()
\property QApplication::cursorFlashTime
\brief the text cursor's flash (blink) time in milliseconds
- The flash time is the time required to display, invert and
- restore the caret display. Usually the text cursor is displayed
- for half the cursor flash time, then hidden for the same amount
- of time, but this may vary.
+ The flash time is the time required to display, invert and restore the
+ caret display. Usually the text cursor is displayed for half the cursor
+ flash time, then hidden for the same amount of time, but this may vary.
- The default value on X11 is 1000 milliseconds. On Windows, the
- control panel value is used. Widgets should not cache this value
- since it may be changed at any time by the user changing the
- global desktop settings.
+ The default value on X11 is 1000 milliseconds. On Windows, the control
+ panel value is used. Widgets should not cache this value since it may be
+ changed at any time by the user changing the global desktop settings.
- Note that on Microsoft Windows, setting this property sets the
- cursor flash time for all applications.
+ \note On Microsoft Windows, setting this property sets the cursor flash
+ time for all applications.
*/
/*!
@@ -4790,11 +4742,11 @@ bool QApplication::keypadNavigationEnabled()
\brief the time limit in milliseconds that distinguishes a double click from two
consecutive mouse clicks
- The default value on X11 is 400 milliseconds. On Windows and Mac
- OS X, the operating system's value is used.
+ The default value on X11 is 400 milliseconds. On Windows and Mac OS X, the
+ operating system's value is used.
- On Microsoft Windows, calling this function sets the
- double click interval for all applications.
+ On Microsoft Windows, calling this function sets the double click interval
+ for all applications.
*/
/*!
@@ -4812,15 +4764,13 @@ bool QApplication::keypadNavigationEnabled()
\brief the number of lines to scroll a widget, when the
mouse wheel is rotated.
- If the value exceeds the widget's number of visible lines, the
- widget should interpret the scroll operation as a single \e{page
- up} or \e{page down}. If the widget is an \l{QAbstractItemView}
- {item view class}, then the result of scrolling one \e line
- depends on the setting of the widget's
- \l{QAbstractItemView::verticalScrollMode()} {scroll mode}. Scroll
- one \e line can mean \l{QAbstractItemView::ScrollPerItem} {scroll
- one item} or \l{QAbstractItemView::ScrollPerPixel} {scroll one
- pixel}.
+ If the value exceeds the widget's number of visible lines, the widget
+ should interpret the scroll operation as a single \e{page up} or
+ \e{page down}. If the widget is an \l{QAbstractItemView}{item view class},
+ then the result of scrolling one \e line depends on the setting of the
+ widget's \l{QAbstractItemView::verticalScrollMode()}{scroll mode}. Scroll
+ one \e line can mean \l{QAbstractItemView::ScrollPerItem}{scroll one item}
+ or \l{QAbstractItemView::ScrollPerPixel}{scroll one pixel}.
By default, this property has a value of 3.
*/
@@ -4828,11 +4778,11 @@ bool QApplication::keypadNavigationEnabled()
/*!
\fn void QApplication::setEffectEnabled(Qt::UIEffect effect, bool enable)
- Enables the UI effect \a effect if \a enable is true, otherwise
- the effect will not be used.
+ Enables the UI effect \a effect if \a enable is true, otherwise the effect
+ will not be used.
- Note: All effects are disabled on screens running at less than
- 16-bit color depth.
+ \note All effects are disabled on screens running at less than 16-bit color
+ depth.
\sa isEffectEnabled(), Qt::UIEffect, setDesktopSettingsAware()
*/
@@ -4842,11 +4792,11 @@ bool QApplication::keypadNavigationEnabled()
Returns true if \a effect is enabled; otherwise returns false.
- By default, Qt will try to use the desktop settings. Call
- setDesktopSettingsAware(false) to prevent this.
+ By default, Qt will try to use the desktop settings. To prevent this, call
+ setDesktopSettingsAware(false).
- Note: All effects are disabled on screens running at less than
- 16-bit color depth.
+ \note All effects are disabled on screens running at less than 16-bit color
+ depth.
\sa setEffectEnabled(), Qt::UIEffect
*/
@@ -4854,8 +4804,7 @@ bool QApplication::keypadNavigationEnabled()
/*!
\fn QWidget *QApplication::mainWidget()
- Returns the main application widget, or 0 if there is no main
- widget.
+ Returns the main application widget, or 0 if there is no main widget.
*/
/*!
@@ -4863,19 +4812,17 @@ bool QApplication::keypadNavigationEnabled()
Sets the application's main widget to \a mainWidget.
- In most respects the main widget is like any other widget, except
- that if it is closed, the application exits. Note that
- QApplication does \e not take ownership of the \a mainWidget, so
- if you create your main widget on the heap you must delete it
- yourself.
+ In most respects the main widget is like any other widget, except that if
+ it is closed, the application exits. QApplication does \e not take
+ ownership of the \a mainWidget, so if you create your main widget on the
+ heap you must delete it yourself.
- You need not have a main widget; connecting lastWindowClosed() to
- quit() is an alternative.
+ You need not have a main widget; connecting lastWindowClosed() to quit()
+ is an alternative.
- For X11, this function also resizes and moves the main widget
- according to the \e -geometry command-line option, so you should
- set the default geometry (using \l QWidget::setGeometry()) before
- calling setMainWidget().
+ For X11, this function also resizes and moves the main widget according
+ to the \e -geometry command-line option, so you should set the default
+ geometry (using \l QWidget::setGeometry()) before calling setMainWidget().
\sa mainWidget(), exec(), quit()
*/
@@ -4883,8 +4830,8 @@ bool QApplication::keypadNavigationEnabled()
/*!
\fn void QApplication::beep()
- Sounds the bell, using the default volume and sound. The function
- is \e not available in Qt for Embedded Linux.
+ Sounds the bell, using the default volume and sound. The function is \e not
+ available in Qt for Embedded Linux.
*/
/*!
@@ -4892,26 +4839,25 @@ bool QApplication::keypadNavigationEnabled()
Sets the application override cursor to \a cursor.
- Application override cursors are intended for showing the user
- that the application is in a special state, for example during an
- operation that might take some time.
+ Application override cursors are intended for showing the user that the
+ application is in a special state, for example during an operation that
+ might take some time.
- This cursor will be displayed in all the application's widgets
- until restoreOverrideCursor() or another setOverrideCursor() is
- called.
+ This cursor will be displayed in all the application's widgets until
+ restoreOverrideCursor() or another setOverrideCursor() is called.
- Application cursors are stored on an internal stack.
- setOverrideCursor() pushes the cursor onto the stack, and
- restoreOverrideCursor() pops the active cursor off the
- stack. changeOverrideCursor() changes the curently active
- application override cursor. Every setOverrideCursor() must
+ Application cursors are stored on an internal stack. setOverrideCursor()
+ pushes the cursor onto the stack, and restoreOverrideCursor() pops the
+ active cursor off the stack. changeOverrideCursor() changes the curently
+ active application override cursor. Every setOverrideCursor() must
eventually be followed by a corresponding restoreOverrideCursor(),
otherwise the stack will never be emptied.
Example:
\snippet doc/src/snippets/code/src_gui_kernel_qapplication_x11.cpp 0
- \sa overrideCursor() restoreOverrideCursor() changeOverrideCursor() QWidget::setCursor()
+ \sa overrideCursor(), restoreOverrideCursor(), changeOverrideCursor(),
+ QWidget::setCursor()
*/
/*!
@@ -4920,9 +4866,8 @@ bool QApplication::keypadNavigationEnabled()
Undoes the last setOverrideCursor().
If setOverrideCursor() has been called twice, calling
- restoreOverrideCursor() will activate the first cursor set.
- Calling this function a second time restores the original widgets'
- cursors.
+ restoreOverrideCursor() will activate the first cursor set. Calling this
+ function a second time restores the original widgets' cursors.
\sa setOverrideCursor(), overrideCursor()
*/
@@ -4932,9 +4877,9 @@ bool QApplication::keypadNavigationEnabled()
\relates QApplication
A global pointer referring to the unique application object. It is
- equivalent to the pointer returned by the
- QCoreApplication::instance() function except that, in GUI applications,
- it is a pointer to a QApplication instance.
+ equivalent to the pointer returned by the QCoreApplication::instance()
+ function except that, in GUI applications, it is a pointer to a
+ QApplication instance.
Only one application object can be created.
@@ -4946,8 +4891,8 @@ bool QApplication::keypadNavigationEnabled()
// ************************************************************************
/*!
- This function replaces the QInputContext instance used by the
- application with \a inputContext.
+ This function replaces the QInputContext instance used by the application
+ with \a inputContext.
\sa inputContext()
*/