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::modality
416 bool QWindow::isModal() const
419 return d->modality != Qt::NonModal;
422 /*! \property QWindow::modality
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::modality() const
439 void QWindow::setModality(Qt::WindowModality modality)
442 if (d->modality == modality)
444 d->modality = modality;
445 emit modalityChanged(modality);
448 /*! \fn void QWindow::modalityChanged(Qt::WindowModality modality)
450 This signal is emitted when the Qwindow::modality property changes to \a modality.
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 \property QWindow::flags
514 \brief the window flags of the window
516 The window flags control the window's appearance in the windowing system,
517 whether it's a dialog, popup, or a regular window, and whether it should
518 have a title bar, etc.
520 The actual window flags might differ from the flags set with setFlags()
521 if the requested flags could not be fulfilled.
523 void QWindow::setFlags(Qt::WindowFlags flags)
526 if (d->platformWindow)
527 d->platformWindow->setWindowFlags(flags);
528 d->windowFlags = flags;
531 Qt::WindowFlags QWindow::flags() const
534 return d->windowFlags;
538 Returns the type of the window.
540 This returns the part of the window flags that represents
541 whether the window is a dialog, tooltip, popup, regular window, etc.
543 \sa flags(), setFlags()
545 Qt::WindowType QWindow::type() const
548 return static_cast<Qt::WindowType>(int(d->windowFlags & Qt::WindowType_Mask));
552 \property QWindow::title
553 \brief the window's title in the windowing system
555 The window title might appear in the title area of the window decorations,
556 depending on the windowing system and the window flags. It might also
557 be used by the windowing system to identify the window in other contexts,
558 such as in the task switcher.
562 void QWindow::setTitle(const QString &title)
565 d->windowTitle = title;
566 if (d->platformWindow)
567 d->platformWindow->setWindowTitle(title);
570 QString QWindow::title() const
573 return d->windowTitle;
577 \brief set the file name this window is representing.
579 The windowing system might use \a filePath to display the
580 path of the document this window is representing in the tile bar.
583 void QWindow::setFilePath(const QString &filePath)
586 d->windowFilePath = filePath;
587 if (d->platformWindow)
588 d->platformWindow->setWindowFilePath(filePath);
592 \brief the file name this window is representing.
596 QString QWindow::filePath() const
599 return d->windowFilePath;
603 \brief set the window's \a icon in the windowing system
605 The window icon might be used by the windowing system for example to
606 decorate the window, and/or in the task switcher.
608 void QWindow::setIcon(const QIcon &icon)
611 d->windowIcon = icon;
612 if (d->platformWindow)
613 d->platformWindow->setWindowIcon(icon);
617 \brief set the window's icon in the windowing system
621 QIcon QWindow::icon() const
624 return d->windowIcon;
628 Raise the window in the windowing system.
630 Requests that the window be raised to appear above other windows.
632 void QWindow::raise()
635 if (d->platformWindow)
636 d->platformWindow->raise();
640 Lower the window in the windowing system.
642 Requests that the window be lowered to appear below other windows.
644 void QWindow::lower()
647 if (d->platformWindow)
648 d->platformWindow->lower();
652 Sets the window's opacity in the windowing system to \a level.
654 If the windowing system supports window opacity, this can be used to fade the
655 window in and out, or to make it semitransparent.
657 A value of 1.0 or above is treated as fully opaque, whereas a value of 0.0 or below
658 is treated as fully transparent. Values inbetween represent varying levels of
659 translucency between the two extremes.
661 void QWindow::setOpacity(qreal level)
664 if (d->platformWindow) {
665 d->platformWindow->setOpacity(level);
670 Requests the window to be activated, i.e. receive keyboard focus.
672 \sa isActive(), QGuiApplication::focusWindow()
674 void QWindow::requestActivate()
677 if (d->platformWindow)
678 d->platformWindow->requestActivateWindow();
682 Returns if this window is exposed in the windowing system.
684 When the window is not exposed, it is shown by the application
685 but it is still not showing in the windowing system, so the application
686 should minimize rendering and other graphical activities.
688 An exposeEvent() is sent every time this value changes.
692 bool QWindow::isExposed() const
699 Returns true if the window should appear active from a style perspective.
701 This is the case for the window that has input focus as well as windows
702 that are in the same parent / transient parent chain as the focus window.
704 To get the window that currently has focus, use QGuiApplication::focusWindow().
706 bool QWindow::isActive() const
709 if (!d->platformWindow)
712 QWindow *focus = QGuiApplication::focusWindow();
714 // Means the whole application lost the focus
721 if (!parent() && !transientParent()) {
722 return isAncestorOf(focus);
724 return (parent() && parent()->isActive()) || (transientParent() && transientParent()->isActive());
729 \property QWindow::contentOrientation
730 \brief the orientation of the window's contents
732 This is a hint to the window manager in case it needs to display
733 additional content like popups, dialogs, status bars, or similar
734 in relation to the window.
736 The recommended orientation is QScreen::orientation() but
737 an application doesn't have to support all possible orientations,
738 and thus can opt to ignore the current screen orientation.
740 The difference between the window and the content orientation
741 determines how much to rotate the content by. QScreen::angleBetween(),
742 QScreen::transformBetween(), and QScreen::mapBetween() can be used
743 to compute the necessary transform.
745 The default value is Qt::PrimaryOrientation
747 \sa requestOrientation(), QScreen::orientation()
749 void QWindow::reportContentOrientationChange(Qt::ScreenOrientation orientation)
752 if (d->contentOrientation == orientation)
754 if (!d->platformWindow)
756 Q_ASSERT(d->platformWindow);
757 d->contentOrientation = orientation;
758 d->platformWindow->handleContentOrientationChange(orientation);
759 emit contentOrientationChanged(orientation);
762 Qt::ScreenOrientation QWindow::contentOrientation() const
765 return d->contentOrientation;
769 Requests the given window \a orientation.
771 The window \a orientation specifies how the window should be rotated
772 by the window manager in order to be displayed. Input events will
773 be correctly mapped to the given \a orientation.
775 The return value is false if the system doesn't support the given
776 \a orientation (for example when requesting a portrait orientation
777 on a device that only handles landscape buffers, typically a desktop
780 If the return value is false, call \l orientation() to get the actual
781 supported orientation.
783 \sa orientation(), reportContentOrientationChange(), QScreen::orientation()
785 bool QWindow::requestOrientation(Qt::ScreenOrientation orientation)
788 if (!d->platformWindow)
790 Q_ASSERT(d->platformWindow);
791 d->windowOrientation = d->platformWindow->requestWindowOrientation(orientation);
792 return d->windowOrientation == orientation;
796 Returns the actual window orientation.
798 The default value is Qt::PrimaryOrientation.
800 \sa requestOrientation()
802 Qt::ScreenOrientation QWindow::orientation() const
805 return d->windowOrientation;
809 \brief set the screen-occupation state of the window
811 The window \a state represents whether the window appears in the
812 windowing system as maximized, minimized, fullscreen, or normal.
814 The enum value Qt::WindowActive is not an accepted parameter.
816 \sa showNormal(), showFullScreen(), showMinimized(), showMaximized()
818 void QWindow::setWindowState(Qt::WindowState state)
820 if (state == Qt::WindowActive) {
821 qWarning() << "QWindow::setWindowState does not accept Qt::WindowActive";
826 if (d->platformWindow)
827 d->platformWindow->setWindowState(state);
828 d->windowState = state;
829 emit windowStateChanged(d->windowState);
833 \brief the screen-occupation state of the window
837 Qt::WindowState QWindow::windowState() const
840 return d->windowState;
844 \fn QWindow::windowStateChanged(Qt::WindowState windowState)
846 This signal is emitted when the \a windowState changes, either
847 by being set explicitly with setWindowState(), or automatically when
848 the user clicks one of the titlebar buttons or by other means.
852 Sets the transient \a parent
854 This is a hint to the window manager that this window is a dialog or pop-up
855 on behalf of the given window.
857 \sa transientParent(), parent()
859 void QWindow::setTransientParent(QWindow *parent)
862 d->transientParent = parent;
864 QGuiApplicationPrivate::updateBlockedStatus(this);
868 Returns the transient parent of the window.
870 \sa setTransientParent(), parent()
872 QWindow *QWindow::transientParent() const
875 return d->transientParent.data();
879 \enum QWindow::AncestorMode
881 This enum is used to control whether or not transient parents
882 should be considered ancestors.
884 \value ExcludeTransients Transient parents are not considered ancestors.
885 \value IncludeTransients Transient parents are considered ancestors.
889 Returns true if the window is an ancestor of the given \a child. If \a mode
890 is IncludeTransients, then transient parents are also considered ancestors.
892 bool QWindow::isAncestorOf(const QWindow *child, AncestorMode mode) const
894 if (child->parent() == this || (mode == IncludeTransients && child->transientParent() == this))
897 return (child->parent() && isAncestorOf(child->parent(), mode))
898 || (mode == IncludeTransients && child->transientParent() && isAncestorOf(child->transientParent(), mode));
902 Returns the minimum size of the window.
906 QSize QWindow::minimumSize() const
909 return d->minimumSize;
913 Returns the maximum size of the window.
917 QSize QWindow::maximumSize() const
920 return d->maximumSize;
924 Returns the base size of the window.
928 QSize QWindow::baseSize() const
935 Returns the size increment of the window.
937 \sa setSizeIncrement()
939 QSize QWindow::sizeIncrement() const
942 return d->sizeIncrement;
946 Sets the minimum size of the window.
948 This is a hint to the window manager to prevent resizing below the specified \a size.
950 \sa setMaximumSize(), minimumSize()
952 void QWindow::setMinimumSize(const QSize &size)
955 QSize adjustedSize = QSize(qBound(0, size.width(), QWINDOWSIZE_MAX), qBound(0, size.height(), QWINDOWSIZE_MAX));
956 if (d->minimumSize == adjustedSize)
958 QSize oldSize = d->minimumSize;
959 d->minimumSize = adjustedSize;
960 if (d->platformWindow && isTopLevel())
961 d->platformWindow->propagateSizeHints();
962 if (d->minimumSize.width() != oldSize.width())
963 emit minimumWidthChanged(d->minimumSize.width());
964 if (d->minimumSize.height() != oldSize.height())
965 emit minimumHeightChanged(d->minimumSize.height());
968 void QWindow::setMinimumWidth(int w)
970 setMinimumSize(QSize(w, minimumHeight()));
973 void QWindow::setMinimumHeight(int h)
975 setMinimumSize(QSize(minimumWidth(), h));
979 Sets the maximum size of the window.
981 This is a hint to the window manager to prevent resizing above the specified \a size.
983 \sa setMinimumSize(), maximumSize()
985 void QWindow::setMaximumSize(const QSize &size)
988 QSize adjustedSize = QSize(qBound(0, size.width(), QWINDOWSIZE_MAX), qBound(0, size.height(), QWINDOWSIZE_MAX));
989 if (d->maximumSize == adjustedSize)
991 QSize oldSize = d->maximumSize;
992 d->maximumSize = adjustedSize;
993 if (d->platformWindow && isTopLevel())
994 d->platformWindow->propagateSizeHints();
995 if (d->maximumSize.width() != oldSize.width())
996 emit maximumWidthChanged(d->maximumSize.width());
997 if (d->maximumSize.height() != oldSize.height())
998 emit maximumHeightChanged(d->maximumSize.height());
1001 void QWindow::setMaximumWidth(int w)
1003 setMaximumSize(QSize(w, maximumHeight()));
1006 void QWindow::setMaximumHeight(int h)
1008 setMaximumSize(QSize(maximumWidth(), h));
1012 Sets the base \a size of the window.
1014 The base size is used to calculate a proper window size if the
1015 window defines sizeIncrement().
1017 \sa setMinimumSize(), setMaximumSize(), setSizeIncrement(), baseSize()
1019 void QWindow::setBaseSize(const QSize &size)
1022 if (d->baseSize == size)
1025 if (d->platformWindow && isTopLevel())
1026 d->platformWindow->propagateSizeHints();
1030 Sets the size increment (\a size) of the window.
1032 When the user resizes the window, the size will move in steps of
1033 sizeIncrement().width() pixels horizontally and
1034 sizeIncrement().height() pixels vertically, with baseSize() as the
1037 By default, this property contains a size with zero width and height.
1039 The windowing system might not support size increments.
1041 \sa setBaseSize(), setMinimumSize(), setMaximumSize()
1043 void QWindow::setSizeIncrement(const QSize &size)
1046 if (d->sizeIncrement == size)
1048 d->sizeIncrement = size;
1049 if (d->platformWindow && isTopLevel())
1050 d->platformWindow->propagateSizeHints();
1054 \fn void QWindow::setGeometry(int posx, int posy, int w, int h)
1056 Sets the geometry of the window, excluding its window frame, to a
1057 rectangle constructed from \a posx, \a posy, \a w and \a h.
1062 void QWindow::setGeometry(const QRect &rect)
1065 if (rect == geometry())
1067 QRect oldRect = geometry();
1069 d->positionPolicy = QWindowPrivate::WindowFrameExclusive;
1070 if (d->platformWindow) {
1071 d->platformWindow->setGeometry(rect);
1076 if (rect.x() != oldRect.x())
1077 emit xChanged(rect.x());
1078 if (rect.y() != oldRect.y())
1079 emit yChanged(rect.y());
1080 if (rect.width() != oldRect.width())
1081 emit widthChanged(rect.width());
1082 if (rect.height() != oldRect.height())
1083 emit heightChanged(rect.height());
1087 \property QWindow::x
1088 \brief the x position of the window's geometry
1092 \property QWindow::y
1093 \brief the y position of the window's geometry
1097 \property QWindow::width
1098 \brief the width of the window's geometry
1102 \property QWindow::height
1103 \brief the height of the window's geometry
1107 \property QWindow::minimumWidth
1108 \brief the minimum width of the window's geometry
1112 \property QWindow::minimumHeight
1113 \brief the minimum height of the window's geometry
1117 \property QWindow::maximumWidth
1118 \brief the maximum width of the window's geometry
1122 \property QWindow::maximumHeight
1123 \brief the maximum height of the window's geometry
1127 Returns the geometry of the window, excluding its window frame.
1129 \sa frameMargins(), frameGeometry()
1131 QRect QWindow::geometry() const
1134 if (d->platformWindow)
1135 return d->platformWindow->geometry();
1140 Returns the window frame margins surrounding the window.
1142 \sa geometry(), frameGeometry()
1144 QMargins QWindow::frameMargins() const
1147 if (d->platformWindow)
1148 return d->platformWindow->frameMargins();
1153 Returns the geometry of the window, including its window frame.
1155 \sa geometry(), frameMargins()
1157 QRect QWindow::frameGeometry() const
1160 if (d->platformWindow) {
1161 QMargins m = frameMargins();
1162 return d->platformWindow->geometry().adjusted(-m.left(), -m.top(), m.right(), m.bottom());
1168 Returns the top left position of the window, including its window frame.
1170 This returns the same value as frameGeometry().topLeft().
1172 \sa geometry(), frameGeometry()
1174 QPoint QWindow::framePos() const
1177 if (d->platformWindow) {
1178 QMargins margins = frameMargins();
1179 return d->platformWindow->geometry().topLeft() - QPoint(margins.left(), margins.top());
1181 return d->geometry.topLeft();
1185 Sets the upper left position of the window (\a point) including its window frame.
1187 \sa setGeometry(), frameGeometry()
1189 void QWindow::setFramePos(const QPoint &point)
1192 d->positionPolicy = QWindowPrivate::WindowFrameInclusive;
1193 if (d->platformWindow) {
1194 d->platformWindow->setGeometry(QRect(point, size()));
1196 d->geometry.setTopLeft(point);
1201 \property QWindow::pos
1202 \brief the position of the window on the desktop
1208 \property QWindow::size
1209 \brief the size of the window excluding any window frame
1215 \property QWindow::geometry
1216 \brief the geometry of the window excluding any window frame
1218 To make sure the window is visible, make sure the geometry is within
1219 the virtual geometry of its screen.
1221 See the \l{Window Geometry} documentation for an overview of geometry
1222 issues with windows.
1224 By default, this property contains a value that depends on the user's
1225 platform and screen geometry.
1230 void QWindow::resize(const QSize &newSize)
1233 if (d->platformWindow) {
1234 d->platformWindow->setGeometry(QRect(pos(), newSize));
1236 d->geometry.setSize(newSize);
1241 Releases the native platform resources associated with this window.
1245 void QWindow::destroy()
1248 QObjectList childrenWindows = children();
1249 for (int i = 0; i < childrenWindows.size(); i++) {
1250 QObject *object = childrenWindows.at(i);
1251 if (object->isWindowType()) {
1252 QWindow *w = static_cast<QWindow*>(object);
1253 QGuiApplicationPrivate::window_list.removeAll(w);
1258 delete d->platformWindow;
1259 d->resizeEventPending = true;
1260 d->receivedExpose = false;
1262 d->platformWindow = 0;
1266 Returns the platform window corresponding to the window.
1270 QPlatformWindow *QWindow::handle() const
1273 return d->platformWindow;
1277 Returns the platform surface corresponding to the window.
1281 QPlatformSurface *QWindow::surfaceHandle() const
1284 return d->platformWindow;
1288 Set whether keyboard grab should be enabled or not (\a grab).
1290 If the return value is true, the window receives all key events until
1291 setKeyboardGrabEnabled(false) is called; other windows get no key events at
1292 all. Mouse events are not affected. Use setMouseGrabEnabled() if you want
1295 \sa setMouseGrabEnabled()
1297 bool QWindow::setKeyboardGrabEnabled(bool grab)
1300 if (d->platformWindow)
1301 return d->platformWindow->setKeyboardGrabEnabled(grab);
1306 Sets whether mouse grab should be enabled or not (\a grab).
1308 If the return value is true, the window receives all mouse events until setMouseGrabEnabled(false) is
1309 called; other windows get no mouse events at all. Keyboard events are not affected.
1310 Use setKeyboardGrabEnabled() if you want to grab that.
1312 \sa setKeyboardGrabEnabled()
1314 bool QWindow::setMouseGrabEnabled(bool grab)
1317 if (d->platformWindow)
1318 return d->platformWindow->setMouseGrabEnabled(grab);
1323 Returns the screen on which the window is shown.
1325 The value returned will not change when the window is moved
1326 between virtual screens (as returned by QScreen::virtualSiblings()).
1328 \sa setScreen(), QScreen::virtualSiblings()
1330 QScreen *QWindow::screen() const
1337 Sets the screen on which the window should be shown.
1339 If the window has been created, it will be recreated on the \a newScreen.
1341 Note that if the screen is part of a virtual desktop of multiple screens,
1342 the window can appear on any of the screens returned by QScreen::virtualSiblings().
1344 \sa screen(), QScreen::virtualSiblings()
1346 void QWindow::setScreen(QScreen *newScreen)
1350 newScreen = QGuiApplication::primaryScreen();
1351 if (newScreen != screen()) {
1352 const bool wasCreated = d->platformWindow != 0;
1356 disconnect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
1357 d->screen = newScreen;
1359 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
1363 emit screenChanged(newScreen);
1367 void QWindow::screenDestroyed(QObject *object)
1370 if (object == static_cast<QObject *>(d->screen))
1375 \fn QWindow::screenChanged(QScreen *screen)
1377 This signal is emitted when a window's \a screen changes, either
1378 by being set explicitly with setScreen(), or automatically when
1379 the window's screen is removed.
1383 Returns the accessibility interface for the object that the window represents
1387 QAccessibleInterface *QWindow::accessibleRoot() const
1393 \fn QWindow::focusObjectChanged(QObject *focusObject)
1395 This signal is emitted when final receiver of events tied to focus is
1396 changed to \a focusObject.
1402 Returns the QObject that will be the final receiver of events tied focus, such
1405 QObject *QWindow::focusObject() const
1407 return const_cast<QWindow *>(this);
1413 This equivalent to calling showFullScreen() or showNormal(), depending
1414 on whether the platform defaults to windows being fullscreen or not.
1416 \sa showFullScreen(), showNormal(), hide(), QStyleHints::showIsFullScreen()
1418 void QWindow::show()
1420 if (qApp->styleHints()->showIsFullScreen())
1429 Equivalent to calling setVisible(false).
1431 \sa show(), setVisible()
1433 void QWindow::hide()
1439 Shows the window as minimized.
1441 Equivalent to calling setWindowState(Qt::WindowMinimized) and then
1444 \sa setWindowState(), setVisible()
1446 void QWindow::showMinimized()
1448 setWindowState(Qt::WindowMinimized);
1453 Shows the window as maximized.
1455 Equivalent to calling setWindowState(Qt::WindowMaximized) and then
1458 \sa setWindowState(), setVisible()
1460 void QWindow::showMaximized()
1462 setWindowState(Qt::WindowMaximized);
1467 Shows the window as fullscreen.
1469 Equivalent to calling setWindowState(Qt::WindowFullScreen) and then
1472 \sa setWindowState(), setVisible()
1474 void QWindow::showFullScreen()
1476 setWindowState(Qt::WindowFullScreen);
1482 Shows the window as normal, i.e. neither maximized, minimized, nor fullscreen.
1484 Equivalent to calling setWindowState(Qt::WindowNoState) and then
1487 \sa setWindowState(), setVisible()
1489 void QWindow::showNormal()
1491 setWindowState(Qt::WindowNoState);
1498 This closes the window, effectively calling destroy(), and potentially
1499 quitting the application. Returns true on success, false if it has a parent
1500 window (in which case the top level window should be closed instead).
1502 \sa destroy(), QGuiApplication::quitOnLastWindowClosed()
1504 bool QWindow::close()
1508 // Do not close non top level windows
1512 if (QGuiApplicationPrivate::focus_window == this)
1513 QGuiApplicationPrivate::focus_window = 0;
1514 if (QGuiApplicationPrivate::currentMouseWindow == this)
1515 QGuiApplicationPrivate::currentMouseWindow = 0;
1517 QGuiApplicationPrivate::window_list.removeAll(this);
1519 d->maybeQuitOnLastWindowClosed();
1524 The expose event (\a ev) is sent by the window system whenever the window's
1525 exposure on screen changes.
1527 The application can start rendering into the window with QBackingStore
1528 and QOpenGLContext as soon as it gets an exposeEvent() such that
1529 isExposed() is true.
1531 If the window is moved off screen, is made totally obscured by another
1532 window, iconified or similar, this function might be called and the
1533 value of isExposed() might change to false. When this happens,
1534 an application should stop its rendering as it is no longer visible
1537 A resize event will always be sent before the expose event the first time
1542 void QWindow::exposeEvent(QExposeEvent *ev)
1548 Override this to handle mouse events (\a ev).
1550 void QWindow::moveEvent(QMoveEvent *ev)
1556 Override this to handle resize events (\a ev).
1558 The resize event is called whenever the window is resized in the windowing system,
1559 either directly through the windowing system acknowledging a setGeometry() or resize() request,
1560 or indirectly through the user resizing the window manually.
1562 void QWindow::resizeEvent(QResizeEvent *ev)
1568 Override this to handle show events (\a ev).
1570 The function is called when the window has requested becoming visible.
1572 If the window is successfully shown by the windowing system, this will
1573 be followed by a resize and an expose event.
1575 void QWindow::showEvent(QShowEvent *ev)
1581 Override this to handle hide events (\a ev).
1583 The function is called when the window has requested being hidden in the
1586 void QWindow::hideEvent(QHideEvent *ev)
1592 Override this to handle any event (\a ev) sent to the window.
1593 Return \c true if the event was recognized and processed.
1595 Remember to call the base class version if you wish for mouse events,
1596 key events, resize events, etc to be dispatched as usual.
1598 bool QWindow::event(QEvent *ev)
1600 switch (ev->type()) {
1601 case QEvent::MouseMove:
1602 mouseMoveEvent(static_cast<QMouseEvent*>(ev));
1605 case QEvent::MouseButtonPress:
1606 mousePressEvent(static_cast<QMouseEvent*>(ev));
1609 case QEvent::MouseButtonRelease:
1610 mouseReleaseEvent(static_cast<QMouseEvent*>(ev));
1613 case QEvent::MouseButtonDblClick:
1614 mouseDoubleClickEvent(static_cast<QMouseEvent*>(ev));
1617 case QEvent::TouchBegin:
1618 case QEvent::TouchUpdate:
1619 case QEvent::TouchEnd:
1620 case QEvent::TouchCancel:
1621 touchEvent(static_cast<QTouchEvent *>(ev));
1625 moveEvent(static_cast<QMoveEvent*>(ev));
1628 case QEvent::Resize:
1629 resizeEvent(static_cast<QResizeEvent*>(ev));
1632 case QEvent::KeyPress:
1633 keyPressEvent(static_cast<QKeyEvent *>(ev));
1636 case QEvent::KeyRelease:
1637 keyReleaseEvent(static_cast<QKeyEvent *>(ev));
1640 case QEvent::FocusIn: {
1641 focusInEvent(static_cast<QFocusEvent *>(ev));
1642 #ifndef QT_NO_ACCESSIBILITY
1643 QAccessible::State state;
1644 state.active = true;
1645 QAccessibleStateChangeEvent event(this, state);
1646 QAccessible::updateAccessibility(&event);
1650 case QEvent::FocusOut: {
1651 focusOutEvent(static_cast<QFocusEvent *>(ev));
1652 #ifndef QT_NO_ACCESSIBILITY
1653 QAccessible::State state;
1654 state.active = true;
1655 QAccessibleStateChangeEvent event(this, state);
1656 QAccessible::updateAccessibility(&event);
1660 #ifndef QT_NO_WHEELEVENT
1662 wheelEvent(static_cast<QWheelEvent*>(ev));
1666 case QEvent::Close: {
1668 bool wasVisible = isVisible();
1671 d->maybeQuitOnLastWindowClosed();
1674 case QEvent::Expose:
1675 exposeEvent(static_cast<QExposeEvent *>(ev));
1679 showEvent(static_cast<QShowEvent *>(ev));
1683 hideEvent(static_cast<QHideEvent *>(ev));
1686 case QEvent::WindowStateChange: {
1688 emit windowStateChanged(d->windowState);
1691 #ifndef QT_NO_TABLETEVENT
1692 case QEvent::TabletPress:
1693 case QEvent::TabletMove:
1694 case QEvent::TabletRelease:
1695 tabletEvent(static_cast<QTabletEvent *>(ev));
1700 return QObject::event(ev);
1706 Override this to handle key press events (\a ev).
1708 \sa keyReleaseEvent()
1710 void QWindow::keyPressEvent(QKeyEvent *ev)
1716 Override this to handle key release events (\a ev).
1720 void QWindow::keyReleaseEvent(QKeyEvent *ev)
1726 Override this to handle focus in events (\a ev).
1728 Focus in events are sent when the window receives keyboard focus.
1732 void QWindow::focusInEvent(QFocusEvent *ev)
1738 Override this to handle focus out events (\a ev).
1740 Focus out events are sent when the window loses keyboard focus.
1744 void QWindow::focusOutEvent(QFocusEvent *ev)
1750 Override this to handle mouse press events (\a ev).
1752 \sa mouseReleaseEvent()
1754 void QWindow::mousePressEvent(QMouseEvent *ev)
1760 Override this to handle mouse release events (\a ev).
1762 \sa mousePressEvent()
1764 void QWindow::mouseReleaseEvent(QMouseEvent *ev)
1770 Override this to handle mouse double click events (\a ev).
1772 \sa mousePressEvent(), QStyleHints::mouseDoubleClickInterval()
1774 void QWindow::mouseDoubleClickEvent(QMouseEvent *ev)
1780 Override this to handle mouse move events (\a ev).
1782 void QWindow::mouseMoveEvent(QMouseEvent *ev)
1787 #ifndef QT_NO_WHEELEVENT
1789 Override this to handle mouse wheel or other wheel events (\a ev).
1791 void QWindow::wheelEvent(QWheelEvent *ev)
1795 #endif //QT_NO_WHEELEVENT
1798 Override this to handle touch events (\a ev).
1800 void QWindow::touchEvent(QTouchEvent *ev)
1805 #ifndef QT_NO_TABLETEVENT
1807 Override this to handle tablet press, move, and release events (\a ev).
1809 Proximity enter and leave events are not sent to windows, they are
1810 delivered to the application instance.
1812 void QWindow::tabletEvent(QTabletEvent *ev)
1819 Override this to handle platform dependent events.
1820 Will be given \a eventType, \a message and \a result.
1822 This might make your application non-portable.
1824 Should return true only if the event was handled.
1826 bool QWindow::nativeEvent(const QByteArray &eventType, void *message, long *result)
1828 Q_UNUSED(eventType);
1835 \fn QPoint QWindow::mapToGlobal(const QPoint &pos) const
1837 Translates the window coordinate \a pos to global screen
1838 coordinates. For example, \c{mapToGlobal(QPoint(0,0))} would give
1839 the global coordinates of the top-left pixel of the window.
1843 QPoint QWindow::mapToGlobal(const QPoint &pos) const
1846 if (d->platformWindow && d->platformWindow->isEmbedded(0))
1847 return d->platformWindow->mapToGlobal(pos);
1849 return pos + d_func()->globalPosition();
1854 \fn QPoint QWindow::mapFromGlobal(const QPoint &pos) const
1856 Translates the global screen coordinate \a pos to window
1861 QPoint QWindow::mapFromGlobal(const QPoint &pos) const
1864 if (d->platformWindow && d->platformWindow->isEmbedded(0))
1865 return d->platformWindow->mapFromGlobal(pos);
1867 return pos - d_func()->globalPosition();
1871 Q_GUI_EXPORT QWindowPrivate *qt_window_private(QWindow *window)
1873 return window->d_func();
1876 void QWindowPrivate::maybeQuitOnLastWindowClosed()
1880 // Attempt to close the application only if this has WA_QuitOnClose set and a non-visible parent
1881 bool quitOnClose = QGuiApplication::quitOnLastWindowClosed() && !q->parent();
1884 QWindowList list = QGuiApplication::topLevelWindows();
1885 bool lastWindowClosed = true;
1886 for (int i = 0; i < list.size(); ++i) {
1887 QWindow *w = list.at(i);
1888 if (!w->isVisible() || w->transientParent())
1890 lastWindowClosed = false;
1893 if (lastWindowClosed) {
1894 QGuiApplicationPrivate::emitLastWindowClosed();
1895 QCoreApplicationPrivate *applicationPrivate = static_cast<QCoreApplicationPrivate*>(QObjectPrivate::get(QCoreApplication::instance()));
1896 applicationPrivate->maybeQuit();
1902 #ifndef QT_NO_CURSOR
1904 \brief set the cursor shape for this window
1906 The mouse \a cursor will assume this shape when it is over this
1907 window, unless an override cursor is set.
1908 See the \l{Qt::CursorShape}{list of predefined cursor objects} for a
1909 range of useful shapes.
1911 By default, the cursor has the Qt::ArrowCursor shape.
1913 Some underlying window implementations will reset the cursor if it
1914 leaves a window even if the mouse is grabbed. If you want to have
1915 a cursor set for all windows, even when outside the window, consider
1916 QGuiApplication::setOverrideCursor().
1918 \sa QGuiApplication::setOverrideCursor()
1920 void QWindow::setCursor(const QCursor &cursor)
1924 // Only attempt to set cursor and emit signal if there is an actual platform cursor
1925 if (d->screen->handle()->cursor()) {
1927 QEvent event(QEvent::CursorChange);
1928 QGuiApplication::sendEvent(this, &event);
1933 \brief Restores the default arrow cursor for this window.
1935 void QWindow::unsetCursor()
1937 setCursor(Qt::ArrowCursor);
1941 \brief the cursor shape for this window
1943 \sa setCursor(), unsetCursor()
1945 QCursor QWindow::cursor() const
1951 void QWindowPrivate::applyCursor()
1954 if (platformWindow) {
1955 if (QPlatformCursor *platformCursor = screen->handle()->cursor()) {
1956 QCursor *oc = QGuiApplication::overrideCursor();
1957 QCursor c = oc ? *oc : cursor;
1958 platformCursor->changeCursor(&c, q);
1962 #endif // QT_NO_CURSOR