summaryrefslogtreecommitdiffstats
path: root/src/gui
diff options
context:
space:
mode:
authorSamuel Rødal <samuel.rodal@nokia.com>2012-02-20 14:11:29 +0100
committerQt by Nokia <qt-info@nokia.com>2012-02-22 13:58:39 +0100
commit9d173c92183c30144e8bd4f115b2cd93c3da0d40 (patch)
treedca8fc4d685017907ab7c72340cfc061baf7d76d /src/gui
parent5d49ca960c942465adf0644ee382b91c35dfb650 (diff)
Updated QApplication / QGuiApplication to match Qt 5 reality.
Removed obsolete Q_WS_X11/WIN/MAC stuff as well. Change-Id: I8b65a0348a8cb170f3f060023fc6d9d982949b7e Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com> Reviewed-by: Laszlo Agocs <laszlo.p.agocs@nokia.com>
Diffstat (limited to 'src/gui')
-rw-r--r--src/gui/kernel/qguiapplication.cpp236
1 files changed, 224 insertions, 12 deletions
diff --git a/src/gui/kernel/qguiapplication.cpp b/src/gui/kernel/qguiapplication.cpp
index 7cb3d4b488..17208643ef 100644
--- a/src/gui/kernel/qguiapplication.cpp
+++ b/src/gui/kernel/qguiapplication.cpp
@@ -145,6 +145,141 @@ static bool qt_detectRTLLanguage()
}
+/*!
+ \class QGuiApplication
+ \brief The QGuiApplication class manages the GUI application's control
+ flow and main settings.
+
+ \inmodule QtGui
+
+ QGuiApplication 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. In addition, QGuiApplication handles
+ most of the system-wide and application-wide settings.
+
+ For any GUI application using Qt, there is precisely \bold one QGuiApplication
+ 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 QGuiApplication object is accessible through the instance() function, which
+ returns a pointer equivalent to the global \l qApp pointer.
+
+ QGuiApplication's main areas of responsibility are:
+ \list
+ \o It initializes the application with the user's desktop settings,
+ such as palette(), font() and styleHints(). 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. You can send your own events to windows by
+ using sendEvent() and postEvent().
+
+ \o It parses common command line arguments and sets its internal
+ state accordingly. See the \l{QGuiApplication::QGuiApplication()}
+ {constructor documentation} below for more details.
+
+ \o It provides localization of strings that are visible to the
+ user via translate().
+
+ \o It provides some magical objects like the clipboard().
+
+ \o It knows about the application's windows. You can ask which
+ window is at a certain position using topLevelAt(), get a list of
+ topLevelWindows(), etc.
+
+ \o It manages the application's mouse cursor handling, see
+ setOverrideCursor()
+ \endlist
+
+ Since the QGuiApplication object does so much initialization, it \e{must} be
+ created before any other objects related to the user interface are created.
+ QGuiApplication also deals with common command line arguments. Hence, 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(),
+ styleHints(),
+ palette(),
+ setPalette(),
+ font(),
+ setFont().
+
+ \row
+ \o Event handling
+ \o exec(),
+ processEvents(),
+ exit(),
+ quit().
+ sendEvent(),
+ postEvent(),
+ sendPostedEvents(),
+ removePostedEvents(),
+ hasPendingEvents(),
+ notify().
+
+ \row
+ \o Windows
+ \o allWindows(),
+ topLevelWindows(),
+ focusWindow(),
+ clipboard(),
+ topLevelAt().
+
+ \row
+ \o Advanced cursor handling
+ \o overrideCursor(),
+ setOverrideCursor(),
+ restoreOverrideCursor().
+
+ \row
+ \o Miscellaneous
+ \o startingUp(),
+ closingDown(),
+ type().
+ \endtable
+
+ \sa QCoreApplication, QAbstractEventDispatcher, QEventLoop
+*/
+
+/*!
+ 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 QGuiApplication 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 pixmaps, bitmaps etc.).
+
+ \note \a argc and \a argv might be changed as Qt removes command line
+ arguments that it recognizes.
+
+ All Qt programs automatically support the following command line options:
+ \list
+ \o -reverse, sets the application's layout direction to
+ Qt::RightToLeft
+ \o -qmljsdebugger=, activates the QML/JS debugger with a specified port.
+ The value must be of format port:1234[,block], where block is optional
+ and will make the application wait until a debugger connects to it.
+ \endlist
+
+ \sa arguments()
+*/
QGuiApplication::QGuiApplication(int &argc, char **argv, int flags)
: QCoreApplication(*new QGuiApplicationPrivate(argc, argv, flags))
{
@@ -159,6 +294,9 @@ QGuiApplication::QGuiApplication(QGuiApplicationPrivate &p)
d_func()->init();
}
+/*!
+ Destructs the application.
+*/
QGuiApplication::~QGuiApplication()
{
Q_D(QGuiApplication);
@@ -194,6 +332,10 @@ QGuiApplicationPrivate::QGuiApplicationPrivate(int &argc, char **argv, int flags
application_type = QCoreApplication::GuiClient;
}
+/*!
+ Returns the QWindow that receives events tied to focus,
+ such as key events.
+*/
QWindow *QGuiApplication::focusWindow()
{
return QGuiApplicationPrivate::focus_window;
@@ -208,7 +350,7 @@ QWindow *QGuiApplication::focusWindow()
/*!
Returns the QObject in currently active window that will be final receiver of events
- tied focus, such as key events.
+ tied to focus, such as key events.
*/
QObject *QGuiApplication::focusObject()
{
@@ -249,6 +391,11 @@ QWindowList QGuiApplication::topLevelWindows()
return topLevelWindows;
}
+/*!
+ Returns the primary (or default) screen of the application.
+
+ This will be the screen where QWindows are shown, unless otherwise specified.
+*/
QScreen *QGuiApplication::primaryScreen()
{
if (QGuiApplicationPrivate::screen_list.isEmpty())
@@ -256,11 +403,18 @@ QScreen *QGuiApplication::primaryScreen()
return QGuiApplicationPrivate::screen_list.at(0);
}
+/*!
+ Returns a list of all the screens associated with the
+ windowing system the application is connected to.
+*/
QList<QScreen *> QGuiApplication::screens()
{
return QGuiApplicationPrivate::screen_list;
}
+/*!
+ Returns the top level window at the given position, if any.
+*/
QWindow *QGuiApplication::topLevelAt(const QPoint &pos)
{
QList<QScreen *> screens = QGuiApplication::screens();
@@ -557,27 +711,62 @@ static QClipboard *clipboard();
#endif
#endif
+/*!
+ Returns the currently held keyboard modifiers.
+*/
Qt::KeyboardModifiers QGuiApplication::keyboardModifiers()
{
return QGuiApplicationPrivate::modifier_buttons;
}
+/*!
+ Returns the currently held mouse buttons.
+*/
Qt::MouseButtons QGuiApplication::mouseButtons()
{
return QGuiApplicationPrivate::mouse_buttons;
}
+/*!
+ Returns the platform's native interface, for platform specific
+ functionality.
+*/
QPlatformNativeInterface *QGuiApplication::platformNativeInterface()
{
QPlatformIntegration *pi = QGuiApplicationPrivate::platformIntegration();
return pi->nativeInterface();
}
+/*!
+ Enters the main event loop and waits until exit() is called, and then
+ returns 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.
+
+ Generally, no user interaction can take place before calling exec().
+
+ To make your application perform idle processing, e.g., 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. This is because, on some platforms, the
+ QApplication::exec() call may not return.
+
+ \sa quitOnLastWindowClosed, quit(), exit(), processEvents(),
+ QCoreApplication::exec()
+*/
int QGuiApplication::exec()
{
return QCoreApplication::exec();
}
+/*! \reimp
+*/
bool QGuiApplication::notify(QObject *object, QEvent *event)
{
#ifndef QT_NO_SHORTCUT
@@ -595,6 +784,8 @@ bool QGuiApplication::notify(QObject *object, QEvent *event)
return QCoreApplication::notify(object, event);
}
+/*! \reimp
+*/
bool QGuiApplication::event(QEvent *e)
{
if(e->type() == QEvent::LanguageChange) {
@@ -603,6 +794,9 @@ bool QGuiApplication::event(QEvent *e)
return QCoreApplication::event(e);
}
+/*!
+ \internal
+*/
bool QGuiApplication::compressEvent(QEvent *event, QObject *receiver, QPostEventList *postedEvents)
{
return QCoreApplication::compressEvent(event, receiver, postedEvents);
@@ -1364,6 +1558,9 @@ Qt::DropAction QGuiApplicationPrivate::processDrop(QWindow *w, QMimeData *dropDa
}
#ifndef QT_NO_CLIPBOARD
+/*!
+ Returns the object for interacting with the clipboard.
+*/
QClipboard * QGuiApplication::clipboard()
{
if (QGuiApplicationPrivate::qt_clipboard == 0) {
@@ -1378,9 +1575,9 @@ QClipboard * QGuiApplication::clipboard()
#endif
/*!
- Returns the application palette.
+ Returns the default application palette.
- \sa setPalette(), QWidget::palette()
+ \sa setPalette()
*/
QPalette QGuiApplication::palette()
{
@@ -1392,6 +1589,11 @@ QPalette QGuiApplication::palette()
return *QGuiApplicationPrivate::app_pal;
}
+/*!
+ Changes the default application palette to \a palette.
+
+ \sa palette()
+*/
void QGuiApplication::setPalette(const QPalette &pal)
{
if (QGuiApplicationPrivate::app_pal && pal.isCopyOf(*QGuiApplicationPrivate::app_pal))
@@ -1402,6 +1604,11 @@ void QGuiApplication::setPalette(const QPalette &pal)
*QGuiApplicationPrivate::app_pal = pal;
}
+/*!
+ Returns the default application font.
+
+ \sa setFont()
+*/
QFont QGuiApplication::font()
{
QMutexLocker locker(&applicationFontMutex);
@@ -1411,6 +1618,11 @@ QFont QGuiApplication::font()
return *QGuiApplicationPrivate::app_font;
}
+/*!
+ Changes the default application font to \a font.
+
+ \sa font()
+*/
void QGuiApplication::setFont(const QFont &font)
{
QMutexLocker locker(&applicationFontMutex);
@@ -1631,7 +1843,7 @@ void QGuiApplication::restoreOverrideCursor()
/*!
\since 5.0
- returns the style hints.
+ Returns the application's style hints.
The style hints encapsulate a set of platform dependent properties
such as double click intervals, full width selection and others.
@@ -1675,6 +1887,14 @@ bool QGuiApplication::desktopSettingsAware()
return QGuiApplicationPrivate::obey_desktop_settings;
}
+QInputMethod *QGuiApplication::inputMethod() const
+{
+ Q_D(const QGuiApplication);
+ if (!d->inputMethod)
+ const_cast<QGuiApplicationPrivate *>(d)->inputMethod = new QInputMethod();
+ return d->inputMethod;
+}
+
/*!
\since 5.0
@@ -1686,14 +1906,6 @@ bool QGuiApplication::desktopSettingsAware()
\sa QInputPanel
*/
-QInputMethod *QGuiApplication::inputMethod() const
-{
- Q_D(const QGuiApplication);
- if (!d->inputMethod)
- const_cast<QGuiApplicationPrivate *>(d)->inputMethod = new QInputMethod();
- return d->inputMethod;
-}
-
QInputPanel *QGuiApplication::inputPanel() const
{
return inputMethod();