From 9d173c92183c30144e8bd4f115b2cd93c3da0d40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Samuel=20R=C3=B8dal?= Date: Mon, 20 Feb 2012 14:11:29 +0100 Subject: 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 Reviewed-by: Laszlo Agocs --- src/gui/kernel/qguiapplication.cpp | 236 +++++++++++++++++++++++++++++++++++-- 1 file changed, 224 insertions(+), 12 deletions(-) (limited to 'src/gui') 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 QGuiApplication::screens() { return QGuiApplicationPrivate::screen_list; } +/*! + Returns the top level window at the given position, if any. +*/ QWindow *QGuiApplication::topLevelAt(const QPoint &pos) { QList 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(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(d)->inputMethod = new QInputMethod(); - return d->inputMethod; -} - QInputPanel *QGuiApplication::inputPanel() const { return inputMethod(); -- cgit v1.2.3