1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtGui module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
40 ****************************************************************************/
44 #include <qpa/qplatformwindow.h>
45 #include <qpa/qplatformintegration.h>
46 #include "qsurfaceformat.h"
48 #include <qpa/qplatformopenglcontext.h>
49 #include "qopenglcontext.h"
53 #include "qwindow_p.h"
54 #include "qguiapplication_p.h"
55 #ifndef QT_NO_ACCESSIBILITY
56 # include "qaccessible.h"
59 #include <private/qevent_p.h>
61 #include <QtCore/QDebug>
63 #include <QStyleHints>
64 #include <qpa/qplatformcursor.h>
72 \brief The QWindow class represents a window in the underlying windowing system.
74 A window that is supplied a parent becomes a native child window of
77 An application will typically use QWidget or QQuickView for its UI, and not
78 QWindow directly. Still, it is possible to render directly to a QWindow
79 with QBackingStore or QOpenGLContext, when wanting to keep dependencies to
80 a minimum or when wanting to use OpenGL directly. The
81 \l{gui/rasterwindow}{Raster Window} and \l{gui/openglwindow}{OpenGL Window}
82 examples are useful reference examples for how to render to a QWindow using
85 \section1 Resource management
87 Windows can potentially use a lot of memory. A usual measurement is
88 width times height times color depth. A window might also include multiple
89 buffers to support double and triple buffering, as well as depth and stencil
90 buffers. To release a window's memory resources, call the destroy() function.
92 \section1 Window and content orientation
94 QWindow has reportContentOrientationChange() and
95 requestWindowOrientation() that can be used to specify the
96 layout of the window contents in relation to the screen. The
97 window orientation determines the actual buffer layout of the
98 window, and the windowing system uses this value to rotate the
99 window before it ends up on the display, and to ensure that input
100 coordinates are in the correct coordinate space relative to the
103 On the other hand, the content orientation is simply a hint to the
104 windowing system about which orientation the window contents are in.
105 It's useful when you wish to keep the same buffer layout, but rotate
106 the contents instead, especially when doing rotation animations
107 between different orientations. The windowing system might use this
108 value to determine the layout of system popups or dialogs.
110 \section1 Visibility and Windowing system exposure.
112 By default, the window is not visible, and you must call setVisible(true),
113 or show() or similar to make it visible. To make a window hidden again,
114 call setVisible(false) or hide(). The visible property describes the state
115 the application wants the window to be in. Depending on the underlying
116 system, a visible window might still not be shown on the screen. It could,
117 for instance, be covered by other opaque windows or moved outside the
118 physical area of the screen. On windowing systems that have exposure
119 notifications, the isExposed() accessor describes whether the window should
120 be treated as directly visible on screen. The exposeEvent() function is
121 called whenever the windows exposure in the windowing system changes. On
122 windowing systems that do not make this information visible to the
123 application, isExposed() will simply return the same value as isVisible().
127 There are two Qt APIs that can be used to render content into a window,
128 QBackingStore for rendering with a QPainter and flushing the contents
129 to a window with type QSurface::RasterSurface, and QOpenGLContext for
130 rendering with OpenGL to a window with type QSurface::OpenGLSurface.
132 The application can start rendering as soon as isExposed() returns true,
133 and can keep rendering until it isExposed() returns false. To find out when
134 isExposed() changes, reimplement exposeEvent(). The window will always get
135 a resize event before the first expose event.
139 Creates a window as a top level on the \a targetScreen.
141 The window is not shown until setVisible(true), show(), or similar is called.
145 QWindow::QWindow(QScreen *targetScreen)
146 : QObject(*new QWindowPrivate(), 0)
147 , QSurface(QSurface::Window)
150 d->screen = targetScreen;
152 d->screen = QGuiApplication::primaryScreen();
154 //if your applications aborts here, then chances are your creating a QWindow before the
155 //screen list is populated.
158 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
159 QGuiApplicationPrivate::window_list.prepend(this);
163 Creates a window as a child of the given \a parent window.
165 The window will be embedded inside the parent window, its coordinates
166 relative to the parent.
168 The screen is inherited from the parent.
172 QWindow::QWindow(QWindow *parent)
173 : QObject(*new QWindowPrivate(), parent)
174 , QSurface(QSurface::Window)
177 d->parentWindow = parent;
179 d->screen = parent->screen();
181 d->screen = QGuiApplication::primaryScreen();
182 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
183 QGuiApplicationPrivate::window_list.prepend(this);
187 Creates a window as a child of the given \a parent window with the \a dd
188 private implementation.
190 The window will be embedded inside the parent window, its coordinates
191 relative to the parent.
193 The screen is inherited from the parent.
198 QWindow::QWindow(QWindowPrivate &dd, QWindow *parent)
199 : QObject(dd, parent)
200 , QSurface(QSurface::Window)
203 d->parentWindow = parent;
205 d->screen = parent->screen();
207 d->screen = QGuiApplication::primaryScreen();
208 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
209 QGuiApplicationPrivate::window_list.prepend(this);
217 if (QGuiApplicationPrivate::focus_window == this)
218 QGuiApplicationPrivate::focus_window = 0;
219 if (QGuiApplicationPrivate::currentMouseWindow == this)
220 QGuiApplicationPrivate::currentMouseWindow = 0;
221 QGuiApplicationPrivate::window_list.removeAll(this);
226 Set the \a surfaceType of the window.
228 Specifies whether the window is meant for raster rendering with
229 QBackingStore, or OpenGL rendering with QOpenGLContext.
231 The surfaceType will be used when the native surface is created
232 in the create() function. Calling this function after the native
233 surface has been created requires calling destroy() and create()
234 to release the old native surface and create a new one.
236 \sa QBackingStore, QOpenGLContext, create(), destroy()
238 void QWindow::setSurfaceType(SurfaceType surfaceType)
241 d->surfaceType = surfaceType;
245 Returns the surface type of the window.
249 QWindow::SurfaceType QWindow::surfaceType() const
252 return d->surfaceType;
256 \property QWindow::visible
257 \brief whether the window is visible or not
259 This property controls the visibility of the window in the windowing system.
261 By default, the window is not visible, you must call setVisible(true), or
262 show() or similar to make it visible.
266 void QWindow::setVisible(bool visible)
270 if (d->visible == visible)
272 d->visible = visible;
273 emit visibleChanged(visible);
275 if (!d->platformWindow)
279 // remove posted quit events when showing a new window
280 QCoreApplication::removePostedEvents(qApp, QEvent::Quit);
282 QShowEvent showEvent;
283 QGuiApplication::sendEvent(this, &showEvent);
288 QGuiApplicationPrivate::showModalWindow(this);
290 QGuiApplicationPrivate::hideModalWindow(this);
297 d->platformWindow->setVisible(visible);
300 QHideEvent hideEvent;
301 QGuiApplication::sendEvent(this, &hideEvent);
305 bool QWindow::isVisible() const
313 Allocates the platform resources associated with the window.
315 It is at this point that the surface format set using setFormat() gets resolved
316 into an actual native surface. However, the window remains hidden until setVisible() is called.
318 Note that it is not usually necessary to call this function directly, as it will be implicitly
319 called by show(), setVisible(), and other functions that require access to the platform
322 Call destroy() to free the platform resources if necessary.
326 void QWindow::create()
329 if (!d->platformWindow) {
330 d->platformWindow = QGuiApplicationPrivate::platformIntegration()->createPlatformWindow(this);
331 QObjectList childObjects = children();
332 for (int i = 0; i < childObjects.size(); i ++) {
333 QObject *object = childObjects.at(i);
334 if(object->isWindowType()) {
335 QWindow *window = static_cast<QWindow *>(object);
336 if (window->d_func()->platformWindow)
337 window->d_func()->platformWindow->setParent(d->platformWindow);
344 Returns the window's platform id.
346 For platforms where this id might be useful, the value returned
347 will uniquely represent the window inside the corresponding screen.
351 WId QWindow::winId() const
354 if(!d->platformWindow)
355 const_cast<QWindow *>(this)->create();
357 WId id = d->platformWindow->winId();
358 // See the QPlatformWindow::winId() documentation
359 Q_ASSERT(id != WId(0));
364 Returns the parent window, if any.
366 A window without a parent is known as a top level window.
368 QWindow *QWindow::parent() const
371 return d->parentWindow;
375 Sets the \a parent Window. This will lead to the windowing system managing
376 the clip of the window, so it will be clipped to the \a parent window.
378 Setting \a parent to be 0 will make the window become a top level window.
381 void QWindow::setParent(QWindow *parent)
385 QObject::setParent(parent);
387 if (d->platformWindow) {
388 if (parent && parent->d_func()->platformWindow) {
389 d->platformWindow->setParent(parent->d_func()->platformWindow);
391 d->platformWindow->setParent(0);
395 d->parentWindow = parent;
397 QGuiApplicationPrivate::updateBlockedStatus(this);
401 Returns whether the window is top level, i.e. has no parent window.
403 bool QWindow::isTopLevel() const
406 return d->parentWindow == 0;
410 Returns whether the window is modal.
412 A modal window prevents other windows from getting any input.
414 \sa QWindow::windowModality
416 bool QWindow::isModal() const
419 return d->modality != Qt::NonModal;
422 /*! \property QWindow::windowModality
423 \brief the modality of the window
425 A modal window prevents other windows from receiving input events. Qt
426 supports two types of modality: Qt::WindowModal and Qt::ApplicationModal.
428 By default, this property is Qt::NonModal
430 \sa Qt::WindowModality
433 Qt::WindowModality QWindow::windowModality() const
439 void QWindow::setWindowModality(Qt::WindowModality modality)
442 if (d->modality == modality)
444 d->modality = modality;
445 emit windowModalityChanged(modality);
448 /*! \fn void QWindow::windowModalityChanged(Qt::WindowModality windowModality)
450 This signal is emitted when the Qwindow::windowModality property changes to \a windowModality.
454 Sets the window's surface \a format.
456 The format determines properties such as color depth, alpha, depth and
457 stencil buffer size, etc. For example, to give a window a transparent
458 background (provided that the window system supports compositing, and
459 provided that other content in the window does not make it opaque again):
462 QSurfaceFormat format;
463 format.setAlphaBufferSize(8);
464 window.setFormat(format);
467 The surface format will be resolved in the create() function. Calling
468 this function after create() has been called will not re-resolve the
469 surface format of the native surface.
471 \sa create(), destroy()
473 void QWindow::setFormat(const QSurfaceFormat &format)
476 d->requestedFormat = format;
480 Returns the requested surfaceformat of this window.
482 If the requested format was not supported by the platform implementation,
483 the requestedFormat will differ from the actual window format.
485 This is the value set with setFormat().
487 \sa setFormat(), format()
489 QSurfaceFormat QWindow::requestedFormat() const
492 return d->requestedFormat;
496 Returns the actual format of this window.
498 After the window has been created, this function will return the actual surface format
499 of the window. It might differ from the requested format if the requested format could
500 not be fulfilled by the platform.
502 \sa create(), requestedFormat()
504 QSurfaceFormat QWindow::format() const
507 if (d->platformWindow)
508 return d->platformWindow->format();
509 return d->requestedFormat;
513 Sets the window flags of the window to \a flags.
515 The window flags control the window's appearance in the windowing system,
516 whether it's a dialog, popup, or a regular window, and whether it should
517 have a title bar, etc.
521 void QWindow::setWindowFlags(Qt::WindowFlags flags)
524 if (d->platformWindow)
525 d->platformWindow->setWindowFlags(flags);
526 d->windowFlags = flags;
530 Returns the window flags of the window.
532 This might differ from the flags set with setWindowFlags() if the
533 requested flags could not be fulfilled.
537 Qt::WindowFlags QWindow::windowFlags() const
540 return d->windowFlags;
544 Returns the type of the window.
546 This returns the part of the window flags that represents
547 whether the window is a dialog, tooltip, popup, regular window, etc.
549 \sa windowFlags(), setWindowFlags()
551 Qt::WindowType QWindow::windowType() const
554 return static_cast<Qt::WindowType>(int(d->windowFlags & Qt::WindowType_Mask));
558 \property QWindow::windowTitle
559 \brief the window's title in the windowing system
561 The window title might appear in the title area of the window decorations,
562 depending on the windowing system and the window flags. It might also
563 be used by the windowing system to identify the window in other contexts,
564 such as in the task switcher.
568 void QWindow::setWindowTitle(const QString &title)
571 d->windowTitle = title;
572 if (d->platformWindow)
573 d->platformWindow->setWindowTitle(title);
576 QString QWindow::windowTitle() const
579 return d->windowTitle;
583 \property QWindow::windowFilePath
584 \brief the file name this window is representing.
586 This property might be used by the windowing system to display the file
587 path of the document this window is representing in the tile bar.
589 void QWindow::setWindowFilePath(const QString &filePath)
592 d->windowFilePath = filePath;
593 if (d->platformWindow)
594 d->platformWindow->setWindowFilePath(filePath);
597 QString QWindow::windowFilePath() const
600 return d->windowFilePath;
604 \property QWindow::windowIcon
605 \brief the window's icon in the windowing system
607 The window icon might be used by the windowing system for example to
608 decorate the window, and/or in the task switcher.
610 void QWindow::setWindowIcon(const QIcon &icon)
613 d->windowIcon = icon;
614 if (d->platformWindow)
615 d->platformWindow->setWindowIcon(icon);
618 QIcon QWindow::windowIcon() const
621 return d->windowIcon;
625 Raise the window in the windowing system.
627 Requests that the window be raised to appear above other windows.
629 void QWindow::raise()
632 if (d->platformWindow)
633 d->platformWindow->raise();
637 Lower the window in the windowing system.
639 Requests that the window be lowered to appear below other windows.
641 void QWindow::lower()
644 if (d->platformWindow)
645 d->platformWindow->lower();
649 Sets the window's opacity in the windowing system to \a level.
651 If the windowing system supports window opacity, this can be used to fade the
652 window in and out, or to make it semitransparent.
654 A value of 1.0 or above is treated as fully opaque, whereas a value of 0.0 or below
655 is treated as fully transparent. Values inbetween represent varying levels of
656 translucency between the two extremes.
658 void QWindow::setOpacity(qreal level)
661 if (d->platformWindow) {
662 d->platformWindow->setOpacity(level);
667 Requests the window to be activated, i.e. receive keyboard focus.
669 \sa isActive(), QGuiApplication::focusWindow()
671 void QWindow::requestActivateWindow()
674 if (d->platformWindow)
675 d->platformWindow->requestActivateWindow();
679 Returns if this window is exposed in the windowing system.
681 When the window is not exposed, it is shown by the application
682 but it is still not showing in the windowing system, so the application
683 should minimize rendering and other graphical activities.
685 An exposeEvent() is sent every time this value changes.
689 bool QWindow::isExposed() const
696 Returns true if the window should appear active from a style perspective.
698 This is the case for the window that has input focus as well as windows
699 that are in the same parent / transient parent chain as the focus window.
701 To get the window that currently has focus, use QGuiApplication::focusWindow().
703 bool QWindow::isActive() const
706 if (!d->platformWindow)
709 QWindow *focus = QGuiApplication::focusWindow();
711 // Means the whole application lost the focus
718 if (!parent() && !transientParent()) {
719 return isAncestorOf(focus);
721 return (parent() && parent()->isActive()) || (transientParent() && transientParent()->isActive());
726 \property QWindow::contentOrientation
727 \brief the orientation of the window's contents
729 This is a hint to the window manager in case it needs to display
730 additional content like popups, dialogs, status bars, or similar
731 in relation to the window.
733 The recommended orientation is QScreen::orientation() but
734 an application doesn't have to support all possible orientations,
735 and thus can opt to ignore the current screen orientation.
737 The difference between the window and the content orientation
738 determines how much to rotate the content by. QScreen::angleBetween(),
739 QScreen::transformBetween(), and QScreen::mapBetween() can be used
740 to compute the necessary transform.
742 The default value is Qt::PrimaryOrientation
744 \sa requestWindowOrientation(), QScreen::orientation()
746 void QWindow::reportContentOrientationChange(Qt::ScreenOrientation orientation)
749 if (d->contentOrientation == orientation)
751 if (!d->platformWindow)
753 Q_ASSERT(d->platformWindow);
754 d->contentOrientation = orientation;
755 d->platformWindow->handleContentOrientationChange(orientation);
756 emit contentOrientationChanged(orientation);
759 Qt::ScreenOrientation QWindow::contentOrientation() const
762 return d->contentOrientation;
766 Requests the given window \a orientation.
768 The window \a orientation specifies how the window should be rotated
769 by the window manager in order to be displayed. Input events will
770 be correctly mapped to the given \a orientation.
772 The return value is false if the system doesn't support the given
773 \a orientation (for example when requesting a portrait orientation
774 on a device that only handles landscape buffers, typically a desktop
777 If the return value is false, call windowOrientation() to get the actual
778 supported orientation.
780 \sa windowOrientation(), reportContentOrientationChange(), QScreen::orientation()
782 bool QWindow::requestWindowOrientation(Qt::ScreenOrientation orientation)
785 if (!d->platformWindow)
787 Q_ASSERT(d->platformWindow);
788 d->windowOrientation = d->platformWindow->requestWindowOrientation(orientation);
789 return d->windowOrientation == orientation;
793 Returns the actual window orientation.
795 The default value is Qt::PrimaryOrientation.
797 \sa requestWindowOrientation()
799 Qt::ScreenOrientation QWindow::windowOrientation() const
802 return d->windowOrientation;
806 Returns the window state.
810 Qt::WindowState QWindow::windowState() const
813 return d->windowState;
817 Sets the desired window \a state.
819 The window state represents whether the window appears in the
820 windowing system as maximized, minimized, fullscreen, or normal.
822 The enum value Qt::WindowActive is not an accepted parameter.
824 \sa windowState(), showNormal(), showFullScreen(), showMinimized(), showMaximized()
826 void QWindow::setWindowState(Qt::WindowState state)
828 if (state == Qt::WindowActive) {
829 qWarning() << "QWindow::setWindowState does not accept Qt::WindowActive";
834 if (d->platformWindow)
835 d->platformWindow->setWindowState(state);
836 d->windowState = state;
840 Sets the transient \a parent
842 This is a hint to the window manager that this window is a dialog or pop-up
843 on behalf of the given window.
845 \sa transientParent(), parent()
847 void QWindow::setTransientParent(QWindow *parent)
850 d->transientParent = parent;
852 QGuiApplicationPrivate::updateBlockedStatus(this);
856 Returns the transient parent of the window.
858 \sa setTransientParent(), parent()
860 QWindow *QWindow::transientParent() const
863 return d->transientParent.data();
867 \enum QWindow::AncestorMode
869 This enum is used to control whether or not transient parents
870 should be considered ancestors.
872 \value ExcludeTransients Transient parents are not considered ancestors.
873 \value IncludeTransients Transient parents are considered ancestors.
877 Returns true if the window is an ancestor of the given \a child. If \a mode
878 is IncludeTransients, then transient parents are also considered ancestors.
880 bool QWindow::isAncestorOf(const QWindow *child, AncestorMode mode) const
882 if (child->parent() == this || (mode == IncludeTransients && child->transientParent() == this))
885 return (child->parent() && isAncestorOf(child->parent(), mode))
886 || (mode == IncludeTransients && child->transientParent() && isAncestorOf(child->transientParent(), mode));
890 Returns the minimum size of the window.
894 QSize QWindow::minimumSize() const
897 return d->minimumSize;
901 Returns the maximum size of the window.
905 QSize QWindow::maximumSize() const
908 return d->maximumSize;
912 Returns the base size of the window.
916 QSize QWindow::baseSize() const
923 Returns the size increment of the window.
925 \sa setSizeIncrement()
927 QSize QWindow::sizeIncrement() const
930 return d->sizeIncrement;
934 Sets the minimum size of the window.
936 This is a hint to the window manager to prevent resizing below the specified \a size.
938 \sa setMaximumSize(), minimumSize()
940 void QWindow::setMinimumSize(const QSize &size)
943 QSize adjustedSize = QSize(qBound(0, size.width(), QWINDOWSIZE_MAX), qBound(0, size.height(), QWINDOWSIZE_MAX));
944 if (d->minimumSize == adjustedSize)
946 QSize oldSize = d->minimumSize;
947 d->minimumSize = adjustedSize;
948 if (d->platformWindow && isTopLevel())
949 d->platformWindow->propagateSizeHints();
950 if (d->minimumSize.width() != oldSize.width())
951 emit minimumWidthChanged(d->minimumSize.width());
952 if (d->minimumSize.height() != oldSize.height())
953 emit minimumHeightChanged(d->minimumSize.height());
956 void QWindow::setMinimumWidth(int w)
958 setMinimumSize(QSize(w, minimumHeight()));
961 void QWindow::setMinimumHeight(int h)
963 setMinimumSize(QSize(minimumWidth(), h));
967 Sets the maximum size of the window.
969 This is a hint to the window manager to prevent resizing above the specified \a size.
971 \sa setMinimumSize(), maximumSize()
973 void QWindow::setMaximumSize(const QSize &size)
976 QSize adjustedSize = QSize(qBound(0, size.width(), QWINDOWSIZE_MAX), qBound(0, size.height(), QWINDOWSIZE_MAX));
977 if (d->maximumSize == adjustedSize)
979 QSize oldSize = d->maximumSize;
980 d->maximumSize = adjustedSize;
981 if (d->platformWindow && isTopLevel())
982 d->platformWindow->propagateSizeHints();
983 if (d->maximumSize.width() != oldSize.width())
984 emit maximumWidthChanged(d->maximumSize.width());
985 if (d->maximumSize.height() != oldSize.height())
986 emit maximumHeightChanged(d->maximumSize.height());
989 void QWindow::setMaximumWidth(int w)
991 setMaximumSize(QSize(w, maximumHeight()));
994 void QWindow::setMaximumHeight(int h)
996 setMaximumSize(QSize(maximumWidth(), h));
1000 Sets the base \a size of the window.
1002 The base size is used to calculate a proper window size if the
1003 window defines sizeIncrement().
1005 \sa setMinimumSize(), setMaximumSize(), setSizeIncrement(), baseSize()
1007 void QWindow::setBaseSize(const QSize &size)
1010 if (d->baseSize == size)
1013 if (d->platformWindow && isTopLevel())
1014 d->platformWindow->propagateSizeHints();
1018 Sets the size increment (\a size) of the window.
1020 When the user resizes the window, the size will move in steps of
1021 sizeIncrement().width() pixels horizontally and
1022 sizeIncrement().height() pixels vertically, with baseSize() as the
1025 By default, this property contains a size with zero width and height.
1027 The windowing system might not support size increments.
1029 \sa setBaseSize(), setMinimumSize(), setMaximumSize()
1031 void QWindow::setSizeIncrement(const QSize &size)
1034 if (d->sizeIncrement == size)
1036 d->sizeIncrement = size;
1037 if (d->platformWindow && isTopLevel())
1038 d->platformWindow->propagateSizeHints();
1042 \fn void QWindow::setGeometry(int posx, int posy, int w, int h)
1044 Sets the geometry of the window, excluding its window frame, to a
1045 rectangle constructed from \a posx, \a posy, \a w and \a h.
1050 void QWindow::setGeometry(const QRect &rect)
1053 if (rect == geometry())
1055 QRect oldRect = geometry();
1057 d->positionPolicy = QWindowPrivate::WindowFrameExclusive;
1058 if (d->platformWindow) {
1059 d->platformWindow->setGeometry(rect);
1064 if (rect.x() != oldRect.x())
1065 emit xChanged(rect.x());
1066 if (rect.y() != oldRect.y())
1067 emit yChanged(rect.y());
1068 if (rect.width() != oldRect.width())
1069 emit widthChanged(rect.width());
1070 if (rect.height() != oldRect.height())
1071 emit heightChanged(rect.height());
1075 \property QWindow::x
1076 \brief the x position of the window's geometry
1080 \property QWindow::y
1081 \brief the y position of the window's geometry
1085 \property QWindow::width
1086 \brief the width of the window's geometry
1090 \property QWindow::height
1091 \brief the height of the window's geometry
1095 \property QWindow::minimumWidth
1096 \brief the minimum width of the window's geometry
1100 \property QWindow::minimumHeight
1101 \brief the minimum height of the window's geometry
1105 \property QWindow::maximumWidth
1106 \brief the maximum width of the window's geometry
1110 \property QWindow::maximumHeight
1111 \brief the maximum height of the window's geometry
1115 Returns the geometry of the window, excluding its window frame.
1117 \sa frameMargins(), frameGeometry()
1119 QRect QWindow::geometry() const
1122 if (d->platformWindow)
1123 return d->platformWindow->geometry();
1128 Returns the window frame margins surrounding the window.
1130 \sa geometry(), frameGeometry()
1132 QMargins QWindow::frameMargins() const
1135 if (d->platformWindow)
1136 return d->platformWindow->frameMargins();
1141 Returns the geometry of the window, including its window frame.
1143 \sa geometry(), frameMargins()
1145 QRect QWindow::frameGeometry() const
1148 if (d->platformWindow) {
1149 QMargins m = frameMargins();
1150 return d->platformWindow->geometry().adjusted(-m.left(), -m.top(), m.right(), m.bottom());
1156 Returns the top left position of the window, including its window frame.
1158 This returns the same value as frameGeometry().topLeft().
1160 \sa geometry(), frameGeometry()
1162 QPoint QWindow::framePos() const
1165 if (d->platformWindow) {
1166 QMargins margins = frameMargins();
1167 return d->platformWindow->geometry().topLeft() - QPoint(margins.left(), margins.top());
1169 return d->geometry.topLeft();
1173 Sets the upper left position of the window (\a point) including its window frame.
1175 \sa setGeometry(), frameGeometry()
1177 void QWindow::setFramePos(const QPoint &point)
1180 d->positionPolicy = QWindowPrivate::WindowFrameInclusive;
1181 if (d->platformWindow) {
1182 d->platformWindow->setGeometry(QRect(point, size()));
1184 d->geometry.setTopLeft(point);
1189 \property QWindow::pos
1190 \brief the position of the window on the desktop
1196 \property QWindow::size
1197 \brief the size of the window excluding any window frame
1203 \property QWindow::geometry
1204 \brief the geometry of the window excluding any window frame
1206 To make sure the window is visible, make sure the geometry is within
1207 the virtual geometry of its screen.
1209 See the \l{Window Geometry} documentation for an overview of geometry
1210 issues with windows.
1212 By default, this property contains a value that depends on the user's
1213 platform and screen geometry.
1218 void QWindow::resize(const QSize &newSize)
1221 if (d->platformWindow) {
1222 d->platformWindow->setGeometry(QRect(pos(), newSize));
1224 d->geometry.setSize(newSize);
1229 Releases the native platform resources associated with this window.
1233 void QWindow::destroy()
1236 QObjectList childrenWindows = children();
1237 for (int i = 0; i < childrenWindows.size(); i++) {
1238 QObject *object = childrenWindows.at(i);
1239 if (object->isWindowType()) {
1240 QWindow *w = static_cast<QWindow*>(object);
1241 QGuiApplicationPrivate::window_list.removeAll(w);
1246 delete d->platformWindow;
1247 d->resizeEventPending = true;
1248 d->receivedExpose = false;
1250 d->platformWindow = 0;
1254 Returns the platform window corresponding to the window.
1258 QPlatformWindow *QWindow::handle() const
1261 return d->platformWindow;
1265 Returns the platform surface corresponding to the window.
1269 QPlatformSurface *QWindow::surfaceHandle() const
1272 return d->platformWindow;
1276 Set whether keyboard grab should be enabled or not (\a grab).
1278 If the return value is true, the window receives all key events until
1279 setKeyboardGrabEnabled(false) is called; other windows get no key events at
1280 all. Mouse events are not affected. Use setMouseGrabEnabled() if you want
1283 \sa setMouseGrabEnabled()
1285 bool QWindow::setKeyboardGrabEnabled(bool grab)
1288 if (d->platformWindow)
1289 return d->platformWindow->setKeyboardGrabEnabled(grab);
1294 Sets whether mouse grab should be enabled or not (\a grab).
1296 If the return value is true, the window receives all mouse events until setMouseGrabEnabled(false) is
1297 called; other windows get no mouse events at all. Keyboard events are not affected.
1298 Use setKeyboardGrabEnabled() if you want to grab that.
1300 \sa setKeyboardGrabEnabled()
1302 bool QWindow::setMouseGrabEnabled(bool grab)
1305 if (d->platformWindow)
1306 return d->platformWindow->setMouseGrabEnabled(grab);
1311 Returns the screen on which the window is shown.
1313 The value returned will not change when the window is moved
1314 between virtual screens (as returned by QScreen::virtualSiblings()).
1316 \sa setScreen(), QScreen::virtualSiblings()
1318 QScreen *QWindow::screen() const
1325 Sets the screen on which the window should be shown.
1327 If the window has been created, it will be recreated on the \a newScreen.
1329 Note that if the screen is part of a virtual desktop of multiple screens,
1330 the window can appear on any of the screens returned by QScreen::virtualSiblings().
1332 \sa screen(), QScreen::virtualSiblings()
1334 void QWindow::setScreen(QScreen *newScreen)
1338 newScreen = QGuiApplication::primaryScreen();
1339 if (newScreen != screen()) {
1340 const bool wasCreated = d->platformWindow != 0;
1344 disconnect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
1345 d->screen = newScreen;
1347 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
1351 emit screenChanged(newScreen);
1355 void QWindow::screenDestroyed(QObject *object)
1358 if (object == static_cast<QObject *>(d->screen))
1363 \fn QWindow::screenChanged(QScreen *screen)
1365 This signal is emitted when a window's \a screen changes, either
1366 by being set explicitly with setScreen(), or automatically when
1367 the window's screen is removed.
1371 Returns the accessibility interface for the object that the window represents
1375 QAccessibleInterface *QWindow::accessibleRoot() const
1381 \fn QWindow::focusObjectChanged(QObject *focusObject)
1383 This signal is emitted when final receiver of events tied to focus is
1384 changed to \a focusObject.
1390 Returns the QObject that will be the final receiver of events tied focus, such
1393 QObject *QWindow::focusObject() const
1395 return const_cast<QWindow *>(this);
1401 This equivalent to calling showFullScreen() or showNormal(), depending
1402 on whether the platform defaults to windows being fullscreen or not.
1404 \sa showFullScreen(), showNormal(), hide(), QStyleHints::showIsFullScreen()
1406 void QWindow::show()
1408 if (qApp->styleHints()->showIsFullScreen())
1417 Equivalent to calling setVisible(false).
1419 \sa show(), setVisible()
1421 void QWindow::hide()
1427 Shows the window as minimized.
1429 Equivalent to calling setWindowState(Qt::WindowMinimized) and then
1432 \sa setWindowState(), setVisible()
1434 void QWindow::showMinimized()
1436 setWindowState(Qt::WindowMinimized);
1441 Shows the window as maximized.
1443 Equivalent to calling setWindowState(Qt::WindowMaximized) and then
1446 \sa setWindowState(), setVisible()
1448 void QWindow::showMaximized()
1450 setWindowState(Qt::WindowMaximized);
1455 Shows the window as fullscreen.
1457 Equivalent to calling setWindowState(Qt::WindowFullScreen) and then
1460 \sa setWindowState(), setVisible()
1462 void QWindow::showFullScreen()
1464 setWindowState(Qt::WindowFullScreen);
1466 requestActivateWindow();
1470 Shows the window as normal, i.e. neither maximized, minimized, nor fullscreen.
1472 Equivalent to calling setWindowState(Qt::WindowNoState) and then
1475 \sa setWindowState(), setVisible()
1477 void QWindow::showNormal()
1479 setWindowState(Qt::WindowNoState);
1486 This closes the window, effectively calling destroy(), and potentially
1487 quitting the application. Returns true on success, false if it has a parent
1488 window (in which case the top level window should be closed instead).
1490 \sa destroy(), QGuiApplication::quitOnLastWindowClosed()
1492 bool QWindow::close()
1496 // Do not close non top level windows
1500 if (QGuiApplicationPrivate::focus_window == this)
1501 QGuiApplicationPrivate::focus_window = 0;
1502 if (QGuiApplicationPrivate::currentMouseWindow == this)
1503 QGuiApplicationPrivate::currentMouseWindow = 0;
1505 QGuiApplicationPrivate::window_list.removeAll(this);
1507 d->maybeQuitOnLastWindowClosed();
1512 The expose event (\a ev) is sent by the window system whenever the window's
1513 exposure on screen changes.
1515 The application can start rendering into the window with QBackingStore
1516 and QOpenGLContext as soon as it gets an exposeEvent() such that
1517 isExposed() is true.
1519 If the window is moved off screen, is made totally obscured by another
1520 window, iconified or similar, this function might be called and the
1521 value of isExposed() might change to false. When this happens,
1522 an application should stop its rendering as it is no longer visible
1525 A resize event will always be sent before the expose event the first time
1530 void QWindow::exposeEvent(QExposeEvent *ev)
1536 Override this to handle mouse events (\a ev).
1538 void QWindow::moveEvent(QMoveEvent *ev)
1544 Override this to handle resize events (\a ev).
1546 The resize event is called whenever the window is resized in the windowing system,
1547 either directly through the windowing system acknowledging a setGeometry() or resize() request,
1548 or indirectly through the user resizing the window manually.
1550 void QWindow::resizeEvent(QResizeEvent *ev)
1556 Override this to handle show events (\a ev).
1558 The function is called when the window has requested becoming visible.
1560 If the window is successfully shown by the windowing system, this will
1561 be followed by a resize and an expose event.
1563 void QWindow::showEvent(QShowEvent *ev)
1569 Override this to handle hide events (\a ev).
1571 The function is called when the window has requested being hidden in the
1574 void QWindow::hideEvent(QHideEvent *ev)
1580 Override this to handle any event (\a ev) sent to the window.
1581 Return \c true if the event was recognized and processed.
1583 Remember to call the base class version if you wish for mouse events,
1584 key events, resize events, etc to be dispatched as usual.
1586 bool QWindow::event(QEvent *ev)
1588 switch (ev->type()) {
1589 case QEvent::MouseMove:
1590 mouseMoveEvent(static_cast<QMouseEvent*>(ev));
1593 case QEvent::MouseButtonPress:
1594 mousePressEvent(static_cast<QMouseEvent*>(ev));
1597 case QEvent::MouseButtonRelease:
1598 mouseReleaseEvent(static_cast<QMouseEvent*>(ev));
1601 case QEvent::MouseButtonDblClick:
1602 mouseDoubleClickEvent(static_cast<QMouseEvent*>(ev));
1605 case QEvent::TouchBegin:
1606 case QEvent::TouchUpdate:
1607 case QEvent::TouchEnd:
1608 case QEvent::TouchCancel:
1609 touchEvent(static_cast<QTouchEvent *>(ev));
1613 moveEvent(static_cast<QMoveEvent*>(ev));
1616 case QEvent::Resize:
1617 resizeEvent(static_cast<QResizeEvent*>(ev));
1620 case QEvent::KeyPress:
1621 keyPressEvent(static_cast<QKeyEvent *>(ev));
1624 case QEvent::KeyRelease:
1625 keyReleaseEvent(static_cast<QKeyEvent *>(ev));
1628 case QEvent::FocusIn: {
1629 focusInEvent(static_cast<QFocusEvent *>(ev));
1630 #ifndef QT_NO_ACCESSIBILITY
1631 QAccessible::State state;
1632 state.active = true;
1633 QAccessibleStateChangeEvent event(this, state);
1634 QAccessible::updateAccessibility(&event);
1638 case QEvent::FocusOut: {
1639 focusOutEvent(static_cast<QFocusEvent *>(ev));
1640 #ifndef QT_NO_ACCESSIBILITY
1641 QAccessible::State state;
1642 state.active = true;
1643 QAccessibleStateChangeEvent event(this, state);
1644 QAccessible::updateAccessibility(&event);
1648 #ifndef QT_NO_WHEELEVENT
1650 wheelEvent(static_cast<QWheelEvent*>(ev));
1654 case QEvent::Close: {
1656 bool wasVisible = isVisible();
1659 d->maybeQuitOnLastWindowClosed();
1662 case QEvent::Expose:
1663 exposeEvent(static_cast<QExposeEvent *>(ev));
1667 showEvent(static_cast<QShowEvent *>(ev));
1671 hideEvent(static_cast<QHideEvent *>(ev));
1674 #ifndef QT_NO_TABLETEVENT
1675 case QEvent::TabletPress:
1676 case QEvent::TabletMove:
1677 case QEvent::TabletRelease:
1678 tabletEvent(static_cast<QTabletEvent *>(ev));
1683 return QObject::event(ev);
1689 Override this to handle key press events (\a ev).
1691 \sa keyReleaseEvent()
1693 void QWindow::keyPressEvent(QKeyEvent *ev)
1699 Override this to handle key release events (\a ev).
1703 void QWindow::keyReleaseEvent(QKeyEvent *ev)
1709 Override this to handle focus in events (\a ev).
1711 Focus in events are sent when the window receives keyboard focus.
1715 void QWindow::focusInEvent(QFocusEvent *ev)
1721 Override this to handle focus out events (\a ev).
1723 Focus out events are sent when the window loses keyboard focus.
1727 void QWindow::focusOutEvent(QFocusEvent *ev)
1733 Override this to handle mouse press events (\a ev).
1735 \sa mouseReleaseEvent()
1737 void QWindow::mousePressEvent(QMouseEvent *ev)
1743 Override this to handle mouse release events (\a ev).
1745 \sa mousePressEvent()
1747 void QWindow::mouseReleaseEvent(QMouseEvent *ev)
1753 Override this to handle mouse double click events (\a ev).
1755 \sa mousePressEvent(), QStyleHints::mouseDoubleClickInterval()
1757 void QWindow::mouseDoubleClickEvent(QMouseEvent *ev)
1763 Override this to handle mouse move events (\a ev).
1765 void QWindow::mouseMoveEvent(QMouseEvent *ev)
1770 #ifndef QT_NO_WHEELEVENT
1772 Override this to handle mouse wheel or other wheel events (\a ev).
1774 void QWindow::wheelEvent(QWheelEvent *ev)
1778 #endif //QT_NO_WHEELEVENT
1781 Override this to handle touch events (\a ev).
1783 void QWindow::touchEvent(QTouchEvent *ev)
1788 #ifndef QT_NO_TABLETEVENT
1790 Override this to handle tablet press, move, and release events (\a ev).
1792 Proximity enter and leave events are not sent to windows, they are
1793 delivered to the application instance.
1795 void QWindow::tabletEvent(QTabletEvent *ev)
1802 Override this to handle platform dependent events.
1803 Will be given \a eventType, \a message and \a result.
1805 This might make your application non-portable.
1807 Should return true only if the event was handled.
1809 bool QWindow::nativeEvent(const QByteArray &eventType, void *message, long *result)
1811 Q_UNUSED(eventType);
1818 \fn QPoint QWindow::mapToGlobal(const QPoint &pos) const
1820 Translates the window coordinate \a pos to global screen
1821 coordinates. For example, \c{mapToGlobal(QPoint(0,0))} would give
1822 the global coordinates of the top-left pixel of the window.
1826 QPoint QWindow::mapToGlobal(const QPoint &pos) const
1829 if (d->platformWindow && d->platformWindow->isEmbedded(0))
1830 return d->platformWindow->mapToGlobal(pos);
1832 return pos + d_func()->globalPosition();
1837 \fn QPoint QWindow::mapFromGlobal(const QPoint &pos) const
1839 Translates the global screen coordinate \a pos to window
1844 QPoint QWindow::mapFromGlobal(const QPoint &pos) const
1847 if (d->platformWindow && d->platformWindow->isEmbedded(0))
1848 return d->platformWindow->mapFromGlobal(pos);
1850 return pos - d_func()->globalPosition();
1854 Q_GUI_EXPORT QWindowPrivate *qt_window_private(QWindow *window)
1856 return window->d_func();
1859 void QWindowPrivate::maybeQuitOnLastWindowClosed()
1863 // Attempt to close the application only if this has WA_QuitOnClose set and a non-visible parent
1864 bool quitOnClose = QGuiApplication::quitOnLastWindowClosed() && !q->parent();
1867 QWindowList list = QGuiApplication::topLevelWindows();
1868 bool lastWindowClosed = true;
1869 for (int i = 0; i < list.size(); ++i) {
1870 QWindow *w = list.at(i);
1871 if (!w->isVisible() || w->transientParent())
1873 lastWindowClosed = false;
1876 if (lastWindowClosed) {
1877 QGuiApplicationPrivate::emitLastWindowClosed();
1878 QCoreApplicationPrivate *applicationPrivate = static_cast<QCoreApplicationPrivate*>(QObjectPrivate::get(QCoreApplication::instance()));
1879 applicationPrivate->maybeQuit();
1886 \property QWindow::cursor
1887 \brief the cursor shape for this window
1889 The mouse cursor will assume this shape when it is over this
1890 window, unless an override cursor is set.
1891 See the \l{Qt::CursorShape}{list of predefined cursor objects} for a
1892 range of useful shapes.
1894 By default, this property contains a cursor with the Qt::ArrowCursor
1897 Some underlying window implementations will reset the cursor if it
1898 leaves a window even if the mouse is grabbed. If you want to have
1899 a cursor set for all windows, even when outside the window, consider
1900 QGuiApplication::setOverrideCursor().
1902 \sa QGuiApplication::setOverrideCursor()
1905 #ifndef QT_NO_CURSOR
1906 QCursor QWindow::cursor() const
1912 void QWindow::setCursor(const QCursor &cursor)
1916 // Only attempt to set cursor and emit signal if there is an actual platform cursor
1917 if (d->screen->handle()->cursor()) {
1919 QEvent event(QEvent::CursorChange);
1920 QGuiApplication::sendEvent(this, &event);
1925 \brief Restores the default arrow cursor for this window.
1927 void QWindow::unsetCursor()
1929 setCursor(Qt::ArrowCursor);
1932 void QWindowPrivate::applyCursor()
1935 if (platformWindow) {
1936 if (QPlatformCursor *platformCursor = screen->handle()->cursor()) {
1937 QCursor *oc = QGuiApplication::overrideCursor();
1938 QCursor c = oc ? *oc : cursor;
1939 platformCursor->changeCursor(&c, q);