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 Content orientation
94 QWindow has reportContentOrientationChange() that can be used to specify
95 the layout of the window contents in relation to the screen. The content
96 orientation is simply a hint to the windowing system about which
97 orientation the window contents are in. It's useful when you wish to keep
98 the same window size, but rotate the contents instead, especially when
99 doing rotation animations between different orientations. The windowing
100 system might use this value to determine the layout of system popups or
103 \section1 Visibility and Windowing system exposure.
105 By default, the window is not visible, and you must call setVisible(true),
106 or show() or similar to make it visible. To make a window hidden again,
107 call setVisible(false) or hide(). The visible property describes the state
108 the application wants the window to be in. Depending on the underlying
109 system, a visible window might still not be shown on the screen. It could,
110 for instance, be covered by other opaque windows or moved outside the
111 physical area of the screen. On windowing systems that have exposure
112 notifications, the isExposed() accessor describes whether the window should
113 be treated as directly visible on screen. The exposeEvent() function is
114 called whenever the windows exposure in the windowing system changes. On
115 windowing systems that do not make this information visible to the
116 application, isExposed() will simply return the same value as isVisible().
120 There are two Qt APIs that can be used to render content into a window,
121 QBackingStore for rendering with a QPainter and flushing the contents
122 to a window with type QSurface::RasterSurface, and QOpenGLContext for
123 rendering with OpenGL to a window with type QSurface::OpenGLSurface.
125 The application can start rendering as soon as isExposed() returns true,
126 and can keep rendering until it isExposed() returns false. To find out when
127 isExposed() changes, reimplement exposeEvent(). The window will always get
128 a resize event before the first expose event.
132 Creates a window as a top level on the \a targetScreen.
134 The window is not shown until setVisible(true), show(), or similar is called.
138 QWindow::QWindow(QScreen *targetScreen)
139 : QObject(*new QWindowPrivate(), 0)
140 , QSurface(QSurface::Window)
143 d->screen = targetScreen;
145 d->screen = QGuiApplication::primaryScreen();
147 //if your applications aborts here, then chances are your creating a QWindow before the
148 //screen list is populated.
151 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
152 QGuiApplicationPrivate::window_list.prepend(this);
156 Creates a window as a child of the given \a parent window.
158 The window will be embedded inside the parent window, its coordinates
159 relative to the parent.
161 The screen is inherited from the parent.
165 QWindow::QWindow(QWindow *parent)
166 : QObject(*new QWindowPrivate(), parent)
167 , QSurface(QSurface::Window)
170 d->parentWindow = parent;
172 d->screen = parent->screen();
174 d->screen = QGuiApplication::primaryScreen();
175 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
176 QGuiApplicationPrivate::window_list.prepend(this);
180 Creates a window as a child of the given \a parent window with the \a dd
181 private implementation.
183 The window will be embedded inside the parent window, its coordinates
184 relative to the parent.
186 The screen is inherited from the parent.
191 QWindow::QWindow(QWindowPrivate &dd, QWindow *parent)
192 : QObject(dd, parent)
193 , QSurface(QSurface::Window)
196 d->parentWindow = parent;
198 d->screen = parent->screen();
200 d->screen = QGuiApplication::primaryScreen();
201 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
202 QGuiApplicationPrivate::window_list.prepend(this);
210 if (QGuiApplicationPrivate::focus_window == this)
211 QGuiApplicationPrivate::focus_window = 0;
212 if (QGuiApplicationPrivate::currentMouseWindow == this)
213 QGuiApplicationPrivate::currentMouseWindow = 0;
214 QGuiApplicationPrivate::window_list.removeAll(this);
219 Set the \a surfaceType of the window.
221 Specifies whether the window is meant for raster rendering with
222 QBackingStore, or OpenGL rendering with QOpenGLContext.
224 The surfaceType will be used when the native surface is created
225 in the create() function. Calling this function after the native
226 surface has been created requires calling destroy() and create()
227 to release the old native surface and create a new one.
229 \sa QBackingStore, QOpenGLContext, create(), destroy()
231 void QWindow::setSurfaceType(SurfaceType surfaceType)
234 d->surfaceType = surfaceType;
238 Returns the surface type of the window.
242 QWindow::SurfaceType QWindow::surfaceType() const
245 return d->surfaceType;
249 \property QWindow::visible
250 \brief whether the window is visible or not
252 This property controls the visibility of the window in the windowing system.
254 By default, the window is not visible, you must call setVisible(true), or
255 show() or similar to make it visible.
259 void QWindow::setVisible(bool visible)
263 if (d->visible == visible)
265 d->visible = visible;
266 emit visibleChanged(visible);
268 if (!d->platformWindow)
272 // remove posted quit events when showing a new window
273 QCoreApplication::removePostedEvents(qApp, QEvent::Quit);
275 QShowEvent showEvent;
276 QGuiApplication::sendEvent(this, &showEvent);
281 QGuiApplicationPrivate::showModalWindow(this);
283 QGuiApplicationPrivate::hideModalWindow(this);
290 d->platformWindow->setVisible(visible);
293 QHideEvent hideEvent;
294 QGuiApplication::sendEvent(this, &hideEvent);
298 bool QWindow::isVisible() const
306 Allocates the platform resources associated with the window.
308 It is at this point that the surface format set using setFormat() gets resolved
309 into an actual native surface. However, the window remains hidden until setVisible() is called.
311 Note that it is not usually necessary to call this function directly, as it will be implicitly
312 called by show(), setVisible(), and other functions that require access to the platform
315 Call destroy() to free the platform resources if necessary.
319 void QWindow::create()
322 if (!d->platformWindow) {
323 d->platformWindow = QGuiApplicationPrivate::platformIntegration()->createPlatformWindow(this);
324 QObjectList childObjects = children();
325 for (int i = 0; i < childObjects.size(); i ++) {
326 QObject *object = childObjects.at(i);
327 if(object->isWindowType()) {
328 QWindow *window = static_cast<QWindow *>(object);
329 if (window->d_func()->platformWindow)
330 window->d_func()->platformWindow->setParent(d->platformWindow);
337 Returns the window's platform id.
339 For platforms where this id might be useful, the value returned
340 will uniquely represent the window inside the corresponding screen.
344 WId QWindow::winId() const
347 if(!d->platformWindow)
348 const_cast<QWindow *>(this)->create();
350 WId id = d->platformWindow->winId();
351 // See the QPlatformWindow::winId() documentation
352 Q_ASSERT(id != WId(0));
357 Returns the parent window, if any.
359 A window without a parent is known as a top level window.
361 QWindow *QWindow::parent() const
364 return d->parentWindow;
368 Sets the \a parent Window. This will lead to the windowing system managing
369 the clip of the window, so it will be clipped to the \a parent window.
371 Setting \a parent to be 0 will make the window become a top level window.
374 void QWindow::setParent(QWindow *parent)
378 QObject::setParent(parent);
380 if (d->platformWindow) {
381 if (parent && parent->d_func()->platformWindow) {
382 d->platformWindow->setParent(parent->d_func()->platformWindow);
384 d->platformWindow->setParent(0);
388 d->parentWindow = parent;
390 QGuiApplicationPrivate::updateBlockedStatus(this);
394 Returns whether the window is top level, i.e. has no parent window.
396 bool QWindow::isTopLevel() const
399 return d->parentWindow == 0;
403 Returns whether the window is modal.
405 A modal window prevents other windows from getting any input.
407 \sa QWindow::modality
409 bool QWindow::isModal() const
412 return d->modality != Qt::NonModal;
415 /*! \property QWindow::modality
416 \brief the modality of the window
418 A modal window prevents other windows from receiving input events. Qt
419 supports two types of modality: Qt::WindowModal and Qt::ApplicationModal.
421 By default, this property is Qt::NonModal
423 \sa Qt::WindowModality
426 Qt::WindowModality QWindow::modality() const
432 void QWindow::setModality(Qt::WindowModality modality)
435 if (d->modality == modality)
437 d->modality = modality;
438 emit modalityChanged(modality);
441 /*! \fn void QWindow::modalityChanged(Qt::WindowModality modality)
443 This signal is emitted when the Qwindow::modality property changes to \a modality.
447 Sets the window's surface \a format.
449 The format determines properties such as color depth, alpha, depth and
450 stencil buffer size, etc. For example, to give a window a transparent
451 background (provided that the window system supports compositing, and
452 provided that other content in the window does not make it opaque again):
455 QSurfaceFormat format;
456 format.setAlphaBufferSize(8);
457 window.setFormat(format);
460 The surface format will be resolved in the create() function. Calling
461 this function after create() has been called will not re-resolve the
462 surface format of the native surface.
464 \sa create(), destroy()
466 void QWindow::setFormat(const QSurfaceFormat &format)
469 d->requestedFormat = format;
473 Returns the requested surfaceformat of this window.
475 If the requested format was not supported by the platform implementation,
476 the requestedFormat will differ from the actual window format.
478 This is the value set with setFormat().
480 \sa setFormat(), format()
482 QSurfaceFormat QWindow::requestedFormat() const
485 return d->requestedFormat;
489 Returns the actual format of this window.
491 After the window has been created, this function will return the actual surface format
492 of the window. It might differ from the requested format if the requested format could
493 not be fulfilled by the platform.
495 \sa create(), requestedFormat()
497 QSurfaceFormat QWindow::format() const
500 if (d->platformWindow)
501 return d->platformWindow->format();
502 return d->requestedFormat;
506 \property QWindow::flags
507 \brief the window flags of the window
509 The window flags control the window's appearance in the windowing system,
510 whether it's a dialog, popup, or a regular window, and whether it should
511 have a title bar, etc.
513 The actual window flags might differ from the flags set with setFlags()
514 if the requested flags could not be fulfilled.
516 void QWindow::setFlags(Qt::WindowFlags flags)
519 if (d->platformWindow)
520 d->platformWindow->setWindowFlags(flags);
521 d->windowFlags = flags;
524 Qt::WindowFlags QWindow::flags() const
527 return d->windowFlags;
531 Returns the type of the window.
533 This returns the part of the window flags that represents
534 whether the window is a dialog, tooltip, popup, regular window, etc.
536 \sa flags(), setFlags()
538 Qt::WindowType QWindow::type() const
541 return static_cast<Qt::WindowType>(int(d->windowFlags & Qt::WindowType_Mask));
545 \property QWindow::title
546 \brief the window's title in the windowing system
548 The window title might appear in the title area of the window decorations,
549 depending on the windowing system and the window flags. It might also
550 be used by the windowing system to identify the window in other contexts,
551 such as in the task switcher.
555 void QWindow::setTitle(const QString &title)
558 d->windowTitle = title;
559 if (d->platformWindow)
560 d->platformWindow->setWindowTitle(title);
563 QString QWindow::title() const
566 return d->windowTitle;
570 \brief set the file name this window is representing.
572 The windowing system might use \a filePath to display the
573 path of the document this window is representing in the tile bar.
576 void QWindow::setFilePath(const QString &filePath)
579 d->windowFilePath = filePath;
580 if (d->platformWindow)
581 d->platformWindow->setWindowFilePath(filePath);
585 \brief the file name this window is representing.
589 QString QWindow::filePath() const
592 return d->windowFilePath;
596 \brief set the window's \a icon in the windowing system
598 The window icon might be used by the windowing system for example to
599 decorate the window, and/or in the task switcher.
601 void QWindow::setIcon(const QIcon &icon)
604 d->windowIcon = icon;
605 if (d->platformWindow)
606 d->platformWindow->setWindowIcon(icon);
610 \brief set the window's icon in the windowing system
614 QIcon QWindow::icon() const
617 return d->windowIcon;
621 Raise the window in the windowing system.
623 Requests that the window be raised to appear above other windows.
625 void QWindow::raise()
628 if (d->platformWindow)
629 d->platformWindow->raise();
633 Lower the window in the windowing system.
635 Requests that the window be lowered to appear below other windows.
637 void QWindow::lower()
640 if (d->platformWindow)
641 d->platformWindow->lower();
645 Sets the window's opacity in the windowing system to \a level.
647 If the windowing system supports window opacity, this can be used to fade the
648 window in and out, or to make it semitransparent.
650 A value of 1.0 or above is treated as fully opaque, whereas a value of 0.0 or below
651 is treated as fully transparent. Values inbetween represent varying levels of
652 translucency between the two extremes.
654 void QWindow::setOpacity(qreal level)
657 if (d->platformWindow) {
658 d->platformWindow->setOpacity(level);
663 Requests the window to be activated, i.e. receive keyboard focus.
665 \sa isActive(), QGuiApplication::focusWindow()
667 void QWindow::requestActivate()
670 if (d->platformWindow)
671 d->platformWindow->requestActivateWindow();
675 Returns if this window is exposed in the windowing system.
677 When the window is not exposed, it is shown by the application
678 but it is still not showing in the windowing system, so the application
679 should minimize rendering and other graphical activities.
681 An exposeEvent() is sent every time this value changes.
685 bool QWindow::isExposed() const
692 Returns true if the window should appear active from a style perspective.
694 This is the case for the window that has input focus as well as windows
695 that are in the same parent / transient parent chain as the focus window.
697 To get the window that currently has focus, use QGuiApplication::focusWindow().
699 bool QWindow::isActive() const
702 if (!d->platformWindow)
705 QWindow *focus = QGuiApplication::focusWindow();
707 // Means the whole application lost the focus
714 if (!parent() && !transientParent()) {
715 return isAncestorOf(focus);
717 return (parent() && parent()->isActive()) || (transientParent() && transientParent()->isActive());
722 \property QWindow::contentOrientation
723 \brief the orientation of the window's contents
725 This is a hint to the window manager in case it needs to display
726 additional content like popups, dialogs, status bars, or similar
727 in relation to the window.
729 The recommended orientation is QScreen::orientation() but
730 an application doesn't have to support all possible orientations,
731 and thus can opt to ignore the current screen orientation.
733 The difference between the window and the content orientation
734 determines how much to rotate the content by. QScreen::angleBetween(),
735 QScreen::transformBetween(), and QScreen::mapBetween() can be used
736 to compute the necessary transform.
738 The default value is Qt::PrimaryOrientation
740 void QWindow::reportContentOrientationChange(Qt::ScreenOrientation orientation)
743 if (d->contentOrientation == orientation)
745 if (!d->platformWindow)
747 Q_ASSERT(d->platformWindow);
748 d->contentOrientation = orientation;
749 d->platformWindow->handleContentOrientationChange(orientation);
750 emit contentOrientationChanged(orientation);
753 Qt::ScreenOrientation QWindow::contentOrientation() const
756 return d->contentOrientation;
760 Returns the ratio between physical pixels and device-independent pixels
761 for the window. This value is dependent on the screen the window is on,
762 and may change when the window is moved.
764 Common values are 1.0 on normal displays and 2.0 on Apple "retina" displays.
766 \sa QWindow::devicePixelRatio();
767 \sa QGuiApplicaiton::devicePixelRatio();
769 qreal QWindow::devicePixelRatio() const
772 if (!d->platformWindow)
774 return d->platformWindow->devicePixelRatio();
778 \brief set the screen-occupation state of the window
780 The window \a state represents whether the window appears in the
781 windowing system as maximized, minimized, fullscreen, or normal.
783 The enum value Qt::WindowActive is not an accepted parameter.
785 \sa showNormal(), showFullScreen(), showMinimized(), showMaximized()
787 void QWindow::setWindowState(Qt::WindowState state)
789 if (state == Qt::WindowActive) {
790 qWarning() << "QWindow::setWindowState does not accept Qt::WindowActive";
795 if (d->platformWindow)
796 d->platformWindow->setWindowState(state);
797 d->windowState = state;
798 emit windowStateChanged(d->windowState);
802 \brief the screen-occupation state of the window
806 Qt::WindowState QWindow::windowState() const
809 return d->windowState;
813 \fn QWindow::windowStateChanged(Qt::WindowState windowState)
815 This signal is emitted when the \a windowState changes, either
816 by being set explicitly with setWindowState(), or automatically when
817 the user clicks one of the titlebar buttons or by other means.
821 Sets the transient \a parent
823 This is a hint to the window manager that this window is a dialog or pop-up
824 on behalf of the given window.
826 \sa transientParent(), parent()
828 void QWindow::setTransientParent(QWindow *parent)
831 d->transientParent = parent;
833 QGuiApplicationPrivate::updateBlockedStatus(this);
837 Returns the transient parent of the window.
839 \sa setTransientParent(), parent()
841 QWindow *QWindow::transientParent() const
844 return d->transientParent.data();
848 \enum QWindow::AncestorMode
850 This enum is used to control whether or not transient parents
851 should be considered ancestors.
853 \value ExcludeTransients Transient parents are not considered ancestors.
854 \value IncludeTransients Transient parents are considered ancestors.
858 Returns true if the window is an ancestor of the given \a child. If \a mode
859 is IncludeTransients, then transient parents are also considered ancestors.
861 bool QWindow::isAncestorOf(const QWindow *child, AncestorMode mode) const
863 if (child->parent() == this || (mode == IncludeTransients && child->transientParent() == this))
866 return (child->parent() && isAncestorOf(child->parent(), mode))
867 || (mode == IncludeTransients && child->transientParent() && isAncestorOf(child->transientParent(), mode));
871 Returns the minimum size of the window.
875 QSize QWindow::minimumSize() const
878 return d->minimumSize;
882 Returns the maximum size of the window.
886 QSize QWindow::maximumSize() const
889 return d->maximumSize;
893 Returns the base size of the window.
897 QSize QWindow::baseSize() const
904 Returns the size increment of the window.
906 \sa setSizeIncrement()
908 QSize QWindow::sizeIncrement() const
911 return d->sizeIncrement;
915 Sets the minimum size of the window.
917 This is a hint to the window manager to prevent resizing below the specified \a size.
919 \sa setMaximumSize(), minimumSize()
921 void QWindow::setMinimumSize(const QSize &size)
924 QSize adjustedSize = QSize(qBound(0, size.width(), QWINDOWSIZE_MAX), qBound(0, size.height(), QWINDOWSIZE_MAX));
925 if (d->minimumSize == adjustedSize)
927 QSize oldSize = d->minimumSize;
928 d->minimumSize = adjustedSize;
929 if (d->platformWindow && isTopLevel())
930 d->platformWindow->propagateSizeHints();
931 if (d->minimumSize.width() != oldSize.width())
932 emit minimumWidthChanged(d->minimumSize.width());
933 if (d->minimumSize.height() != oldSize.height())
934 emit minimumHeightChanged(d->minimumSize.height());
939 \brief the x position of the window's geometry
941 void QWindow::setX(int arg)
944 setGeometry(QRect(arg, y(), width(), height()));
949 \brief the y position of the window's geometry
951 void QWindow::setY(int arg)
954 setGeometry(QRect(x(), arg, width(), height()));
958 \property QWindow::width
959 \brief the width of the window's geometry
961 void QWindow::setWidth(int arg)
964 setGeometry(QRect(x(), y(), arg, height()));
968 \property QWindow::height
969 \brief the height of the window's geometry
971 void QWindow::setHeight(int arg)
974 setGeometry(QRect(x(), y(), width(), arg));
978 \property QWindow::minimumWidth
979 \brief the minimum width of the window's geometry
981 void QWindow::setMinimumWidth(int w)
983 setMinimumSize(QSize(w, minimumHeight()));
987 \property QWindow::minimumHeight
988 \brief the minimum height of the window's geometry
990 void QWindow::setMinimumHeight(int h)
992 setMinimumSize(QSize(minimumWidth(), h));
996 Sets the maximum size of the window.
998 This is a hint to the window manager to prevent resizing above the specified \a size.
1000 \sa setMinimumSize(), maximumSize()
1002 void QWindow::setMaximumSize(const QSize &size)
1005 QSize adjustedSize = QSize(qBound(0, size.width(), QWINDOWSIZE_MAX), qBound(0, size.height(), QWINDOWSIZE_MAX));
1006 if (d->maximumSize == adjustedSize)
1008 QSize oldSize = d->maximumSize;
1009 d->maximumSize = adjustedSize;
1010 if (d->platformWindow && isTopLevel())
1011 d->platformWindow->propagateSizeHints();
1012 if (d->maximumSize.width() != oldSize.width())
1013 emit maximumWidthChanged(d->maximumSize.width());
1014 if (d->maximumSize.height() != oldSize.height())
1015 emit maximumHeightChanged(d->maximumSize.height());
1019 \property QWindow::maximumWidth
1020 \brief the maximum width of the window's geometry
1022 void QWindow::setMaximumWidth(int w)
1024 setMaximumSize(QSize(w, maximumHeight()));
1028 \property QWindow::maximumHeight
1029 \brief the maximum height of the window's geometry
1031 void QWindow::setMaximumHeight(int h)
1033 setMaximumSize(QSize(maximumWidth(), h));
1037 Sets the base \a size of the window.
1039 The base size is used to calculate a proper window size if the
1040 window defines sizeIncrement().
1042 \sa setMinimumSize(), setMaximumSize(), setSizeIncrement(), baseSize()
1044 void QWindow::setBaseSize(const QSize &size)
1047 if (d->baseSize == size)
1050 if (d->platformWindow && isTopLevel())
1051 d->platformWindow->propagateSizeHints();
1055 Sets the size increment (\a size) of the window.
1057 When the user resizes the window, the size will move in steps of
1058 sizeIncrement().width() pixels horizontally and
1059 sizeIncrement().height() pixels vertically, with baseSize() as the
1062 By default, this property contains a size with zero width and height.
1064 The windowing system might not support size increments.
1066 \sa setBaseSize(), setMinimumSize(), setMaximumSize()
1068 void QWindow::setSizeIncrement(const QSize &size)
1071 if (d->sizeIncrement == size)
1073 d->sizeIncrement = size;
1074 if (d->platformWindow && isTopLevel())
1075 d->platformWindow->propagateSizeHints();
1079 Sets the geometry of the window, excluding its window frame, to a
1080 rectangle constructed from \a posx, \a posy, \a w and \a h.
1084 void QWindow::setGeometry(int posx, int posy, int w, int h)
1086 setGeometry(QRect(posx, posy, w, h));
1090 \brief Sets the geometry of the window, excluding its window frame, to \a rect.
1094 void QWindow::setGeometry(const QRect &rect)
1097 if (rect == geometry())
1099 QRect oldRect = geometry();
1101 d->positionPolicy = QWindowPrivate::WindowFrameExclusive;
1102 if (d->platformWindow) {
1103 d->platformWindow->setGeometry(rect);
1108 if (rect.x() != oldRect.x())
1109 emit xChanged(rect.x());
1110 if (rect.y() != oldRect.y())
1111 emit yChanged(rect.y());
1112 if (rect.width() != oldRect.width())
1113 emit widthChanged(rect.width());
1114 if (rect.height() != oldRect.height())
1115 emit heightChanged(rect.height());
1119 Returns the geometry of the window, excluding its window frame.
1121 \sa frameMargins(), frameGeometry()
1123 QRect QWindow::geometry() const
1126 if (d->platformWindow)
1127 return d->platformWindow->geometry();
1132 Returns the window frame margins surrounding the window.
1134 \sa geometry(), frameGeometry()
1136 QMargins QWindow::frameMargins() const
1139 if (d->platformWindow)
1140 return d->platformWindow->frameMargins();
1145 Returns the geometry of the window, including its window frame.
1147 \sa geometry(), frameMargins()
1149 QRect QWindow::frameGeometry() const
1152 if (d->platformWindow) {
1153 QMargins m = frameMargins();
1154 return d->platformWindow->geometry().adjusted(-m.left(), -m.top(), m.right(), m.bottom());
1160 Returns the top left position of the window, including its window frame.
1162 This returns the same value as frameGeometry().topLeft().
1164 \sa geometry(), frameGeometry()
1166 QPoint QWindow::framePosition() const
1169 if (d->platformWindow) {
1170 QMargins margins = frameMargins();
1171 return d->platformWindow->geometry().topLeft() - QPoint(margins.left(), margins.top());
1173 return d->geometry.topLeft();
1177 Sets the upper left position of the window (\a point) including its window frame.
1179 \sa setGeometry(), frameGeometry()
1181 void QWindow::setFramePosition(const QPoint &point)
1184 d->positionPolicy = QWindowPrivate::WindowFrameInclusive;
1185 if (d->platformWindow) {
1186 d->platformWindow->setGeometry(QRect(point, size()));
1188 d->geometry.setTopLeft(point);
1193 \brief set the position of the window on the desktop to \a pt
1197 void QWindow::setPosition(const QPoint &pt)
1199 setGeometry(QRect(pt, size()));
1203 \brief set the position of the window on the desktop to \a posx, \a posy
1207 void QWindow::setPosition(int posx, int posy)
1209 setPosition(QPoint(posx, posy));
1213 \fn QPoint QWindow::position() const
1214 \brief get the position of the window on the desktop excluding any window frame
1220 \fn QSize QWindow::size() const
1221 \brief get the size of the window excluding any window frame
1227 set the size of the window, excluding any window frame, to a QSize
1228 constructed from width \a w and height \a h
1230 \sa size(), geometry()
1232 void QWindow::resize(int w, int h)
1234 resize(QSize(w, h));
1238 \brief set the size of the window, excluding any window frame, to \a newSize
1240 \sa size(), geometry()
1242 void QWindow::resize(const QSize &newSize)
1245 if (d->platformWindow) {
1246 d->platformWindow->setGeometry(QRect(position(), newSize));
1248 d->geometry.setSize(newSize);
1253 Releases the native platform resources associated with this window.
1257 void QWindow::destroy()
1260 QObjectList childrenWindows = children();
1261 for (int i = 0; i < childrenWindows.size(); i++) {
1262 QObject *object = childrenWindows.at(i);
1263 if (object->isWindowType()) {
1264 QWindow *w = static_cast<QWindow*>(object);
1265 QGuiApplicationPrivate::window_list.removeAll(w);
1270 delete d->platformWindow;
1271 d->resizeEventPending = true;
1272 d->receivedExpose = false;
1274 d->platformWindow = 0;
1278 Returns the platform window corresponding to the window.
1282 QPlatformWindow *QWindow::handle() const
1285 return d->platformWindow;
1289 Returns the platform surface corresponding to the window.
1293 QPlatformSurface *QWindow::surfaceHandle() const
1296 return d->platformWindow;
1300 Set whether keyboard grab should be enabled or not (\a grab).
1302 If the return value is true, the window receives all key events until
1303 setKeyboardGrabEnabled(false) is called; other windows get no key events at
1304 all. Mouse events are not affected. Use setMouseGrabEnabled() if you want
1307 \sa setMouseGrabEnabled()
1309 bool QWindow::setKeyboardGrabEnabled(bool grab)
1312 if (grab && QGuiApplicationPrivate::noGrab)
1314 if (d->platformWindow)
1315 return d->platformWindow->setKeyboardGrabEnabled(grab);
1320 Sets whether mouse grab should be enabled or not (\a grab).
1322 If the return value is true, the window receives all mouse events until setMouseGrabEnabled(false) is
1323 called; other windows get no mouse events at all. Keyboard events are not affected.
1324 Use setKeyboardGrabEnabled() if you want to grab that.
1326 \sa setKeyboardGrabEnabled()
1328 bool QWindow::setMouseGrabEnabled(bool grab)
1331 if (grab && QGuiApplicationPrivate::noGrab)
1333 if (d->platformWindow)
1334 return d->platformWindow->setMouseGrabEnabled(grab);
1339 Returns the screen on which the window is shown.
1341 The value returned will not change when the window is moved
1342 between virtual screens (as returned by QScreen::virtualSiblings()).
1344 \sa setScreen(), QScreen::virtualSiblings()
1346 QScreen *QWindow::screen() const
1353 Sets the screen on which the window should be shown.
1355 If the window has been created, it will be recreated on the \a newScreen.
1357 Note that if the screen is part of a virtual desktop of multiple screens,
1358 the window can appear on any of the screens returned by QScreen::virtualSiblings().
1360 \sa screen(), QScreen::virtualSiblings()
1362 void QWindow::setScreen(QScreen *newScreen)
1366 newScreen = QGuiApplication::primaryScreen();
1367 if (newScreen != screen()) {
1368 const bool wasCreated = d->platformWindow != 0;
1372 disconnect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
1373 d->screen = newScreen;
1375 connect(d->screen, SIGNAL(destroyed(QObject*)), this, SLOT(screenDestroyed(QObject*)));
1379 emit screenChanged(newScreen);
1383 void QWindow::screenDestroyed(QObject *object)
1386 if (object == static_cast<QObject *>(d->screen)) {
1387 const bool wasVisible = isVisible();
1389 // destroy() might have hidden our window, show it again.
1390 // This might not be the best behavior if the new screen isn't a virtual sibling
1391 // of the old one. This can be removed once platform plugins have the power to
1392 // update the QScreen of its QWindows itself.
1393 if (wasVisible && d->platformWindow)
1399 \fn QWindow::screenChanged(QScreen *screen)
1401 This signal is emitted when a window's \a screen changes, either
1402 by being set explicitly with setScreen(), or automatically when
1403 the window's screen is removed.
1407 Returns the accessibility interface for the object that the window represents
1411 QAccessibleInterface *QWindow::accessibleRoot() const
1417 \fn QWindow::focusObjectChanged(QObject *focusObject)
1419 This signal is emitted when final receiver of events tied to focus is
1420 changed to \a focusObject.
1426 Returns the QObject that will be the final receiver of events tied focus, such
1429 QObject *QWindow::focusObject() const
1431 return const_cast<QWindow *>(this);
1437 This equivalent to calling showFullScreen() or showNormal(), depending
1438 on whether the platform defaults to windows being fullscreen or not.
1440 \sa showFullScreen(), showNormal(), hide(), QStyleHints::showIsFullScreen()
1442 void QWindow::show()
1444 if (qApp->styleHints()->showIsFullScreen())
1453 Equivalent to calling setVisible(false).
1455 \sa show(), setVisible()
1457 void QWindow::hide()
1463 Shows the window as minimized.
1465 Equivalent to calling setWindowState(Qt::WindowMinimized) and then
1468 \sa setWindowState(), setVisible()
1470 void QWindow::showMinimized()
1472 setWindowState(Qt::WindowMinimized);
1477 Shows the window as maximized.
1479 Equivalent to calling setWindowState(Qt::WindowMaximized) and then
1482 \sa setWindowState(), setVisible()
1484 void QWindow::showMaximized()
1486 setWindowState(Qt::WindowMaximized);
1491 Shows the window as fullscreen.
1493 Equivalent to calling setWindowState(Qt::WindowFullScreen) and then
1496 \sa setWindowState(), setVisible()
1498 void QWindow::showFullScreen()
1500 setWindowState(Qt::WindowFullScreen);
1506 Shows the window as normal, i.e. neither maximized, minimized, nor fullscreen.
1508 Equivalent to calling setWindowState(Qt::WindowNoState) and then
1511 \sa setWindowState(), setVisible()
1513 void QWindow::showNormal()
1515 setWindowState(Qt::WindowNoState);
1522 This closes the window, effectively calling destroy(), and potentially
1523 quitting the application. Returns true on success, false if it has a parent
1524 window (in which case the top level window should be closed instead).
1526 \sa destroy(), QGuiApplication::quitOnLastWindowClosed()
1528 bool QWindow::close()
1532 // Do not close non top level windows
1536 if (QGuiApplicationPrivate::focus_window == this)
1537 QGuiApplicationPrivate::focus_window = 0;
1538 if (QGuiApplicationPrivate::currentMouseWindow == this)
1539 QGuiApplicationPrivate::currentMouseWindow = 0;
1541 QGuiApplicationPrivate::window_list.removeAll(this);
1543 d->maybeQuitOnLastWindowClosed();
1548 The expose event (\a ev) is sent by the window system whenever the window's
1549 exposure on screen changes.
1551 The application can start rendering into the window with QBackingStore
1552 and QOpenGLContext as soon as it gets an exposeEvent() such that
1553 isExposed() is true.
1555 If the window is moved off screen, is made totally obscured by another
1556 window, iconified or similar, this function might be called and the
1557 value of isExposed() might change to false. When this happens,
1558 an application should stop its rendering as it is no longer visible
1561 A resize event will always be sent before the expose event the first time
1566 void QWindow::exposeEvent(QExposeEvent *ev)
1572 Override this to handle mouse events (\a ev).
1574 void QWindow::moveEvent(QMoveEvent *ev)
1580 Override this to handle resize events (\a ev).
1582 The resize event is called whenever the window is resized in the windowing system,
1583 either directly through the windowing system acknowledging a setGeometry() or resize() request,
1584 or indirectly through the user resizing the window manually.
1586 void QWindow::resizeEvent(QResizeEvent *ev)
1592 Override this to handle show events (\a ev).
1594 The function is called when the window has requested becoming visible.
1596 If the window is successfully shown by the windowing system, this will
1597 be followed by a resize and an expose event.
1599 void QWindow::showEvent(QShowEvent *ev)
1605 Override this to handle hide events (\a ev).
1607 The function is called when the window has requested being hidden in the
1610 void QWindow::hideEvent(QHideEvent *ev)
1616 Override this to handle any event (\a ev) sent to the window.
1617 Return \c true if the event was recognized and processed.
1619 Remember to call the base class version if you wish for mouse events,
1620 key events, resize events, etc to be dispatched as usual.
1622 bool QWindow::event(QEvent *ev)
1624 switch (ev->type()) {
1625 case QEvent::MouseMove:
1626 mouseMoveEvent(static_cast<QMouseEvent*>(ev));
1629 case QEvent::MouseButtonPress:
1630 mousePressEvent(static_cast<QMouseEvent*>(ev));
1633 case QEvent::MouseButtonRelease:
1634 mouseReleaseEvent(static_cast<QMouseEvent*>(ev));
1637 case QEvent::MouseButtonDblClick:
1638 mouseDoubleClickEvent(static_cast<QMouseEvent*>(ev));
1641 case QEvent::TouchBegin:
1642 case QEvent::TouchUpdate:
1643 case QEvent::TouchEnd:
1644 case QEvent::TouchCancel:
1645 touchEvent(static_cast<QTouchEvent *>(ev));
1649 moveEvent(static_cast<QMoveEvent*>(ev));
1652 case QEvent::Resize:
1653 resizeEvent(static_cast<QResizeEvent*>(ev));
1656 case QEvent::KeyPress:
1657 keyPressEvent(static_cast<QKeyEvent *>(ev));
1660 case QEvent::KeyRelease:
1661 keyReleaseEvent(static_cast<QKeyEvent *>(ev));
1664 case QEvent::FocusIn: {
1665 focusInEvent(static_cast<QFocusEvent *>(ev));
1666 #ifndef QT_NO_ACCESSIBILITY
1667 QAccessible::State state;
1668 state.active = true;
1669 QAccessibleStateChangeEvent event(this, state);
1670 QAccessible::updateAccessibility(&event);
1674 case QEvent::FocusOut: {
1675 focusOutEvent(static_cast<QFocusEvent *>(ev));
1676 #ifndef QT_NO_ACCESSIBILITY
1677 QAccessible::State state;
1678 state.active = true;
1679 QAccessibleStateChangeEvent event(this, state);
1680 QAccessible::updateAccessibility(&event);
1684 #ifndef QT_NO_WHEELEVENT
1686 wheelEvent(static_cast<QWheelEvent*>(ev));
1690 case QEvent::Close: {
1692 bool wasVisible = isVisible();
1695 d->maybeQuitOnLastWindowClosed();
1698 case QEvent::Expose:
1699 exposeEvent(static_cast<QExposeEvent *>(ev));
1703 showEvent(static_cast<QShowEvent *>(ev));
1707 hideEvent(static_cast<QHideEvent *>(ev));
1710 case QEvent::WindowStateChange: {
1712 emit windowStateChanged(d->windowState);
1716 #ifndef QT_NO_TABLETEVENT
1717 case QEvent::TabletPress:
1718 case QEvent::TabletMove:
1719 case QEvent::TabletRelease:
1720 tabletEvent(static_cast<QTabletEvent *>(ev));
1725 return QObject::event(ev);
1731 Override this to handle key press events (\a ev).
1733 \sa keyReleaseEvent()
1735 void QWindow::keyPressEvent(QKeyEvent *ev)
1741 Override this to handle key release events (\a ev).
1745 void QWindow::keyReleaseEvent(QKeyEvent *ev)
1751 Override this to handle focus in events (\a ev).
1753 Focus in events are sent when the window receives keyboard focus.
1757 void QWindow::focusInEvent(QFocusEvent *ev)
1763 Override this to handle focus out events (\a ev).
1765 Focus out events are sent when the window loses keyboard focus.
1769 void QWindow::focusOutEvent(QFocusEvent *ev)
1775 Override this to handle mouse press events (\a ev).
1777 \sa mouseReleaseEvent()
1779 void QWindow::mousePressEvent(QMouseEvent *ev)
1785 Override this to handle mouse release events (\a ev).
1787 \sa mousePressEvent()
1789 void QWindow::mouseReleaseEvent(QMouseEvent *ev)
1795 Override this to handle mouse double click events (\a ev).
1797 \sa mousePressEvent(), QStyleHints::mouseDoubleClickInterval()
1799 void QWindow::mouseDoubleClickEvent(QMouseEvent *ev)
1805 Override this to handle mouse move events (\a ev).
1807 void QWindow::mouseMoveEvent(QMouseEvent *ev)
1812 #ifndef QT_NO_WHEELEVENT
1814 Override this to handle mouse wheel or other wheel events (\a ev).
1816 void QWindow::wheelEvent(QWheelEvent *ev)
1820 #endif //QT_NO_WHEELEVENT
1823 Override this to handle touch events (\a ev).
1825 void QWindow::touchEvent(QTouchEvent *ev)
1830 #ifndef QT_NO_TABLETEVENT
1832 Override this to handle tablet press, move, and release events (\a ev).
1834 Proximity enter and leave events are not sent to windows, they are
1835 delivered to the application instance.
1837 void QWindow::tabletEvent(QTabletEvent *ev)
1844 Override this to handle platform dependent events.
1845 Will be given \a eventType, \a message and \a result.
1847 This might make your application non-portable.
1849 Should return true only if the event was handled.
1851 bool QWindow::nativeEvent(const QByteArray &eventType, void *message, long *result)
1853 Q_UNUSED(eventType);
1860 \fn QPoint QWindow::mapToGlobal(const QPoint &pos) const
1862 Translates the window coordinate \a pos to global screen
1863 coordinates. For example, \c{mapToGlobal(QPoint(0,0))} would give
1864 the global coordinates of the top-left pixel of the window.
1868 QPoint QWindow::mapToGlobal(const QPoint &pos) const
1871 if (d->platformWindow && d->platformWindow->isEmbedded(0))
1872 return d->platformWindow->mapToGlobal(pos);
1874 return pos + d_func()->globalPosition();
1879 \fn QPoint QWindow::mapFromGlobal(const QPoint &pos) const
1881 Translates the global screen coordinate \a pos to window
1886 QPoint QWindow::mapFromGlobal(const QPoint &pos) const
1889 if (d->platformWindow && d->platformWindow->isEmbedded(0))
1890 return d->platformWindow->mapFromGlobal(pos);
1892 return pos - d_func()->globalPosition();
1896 Q_GUI_EXPORT QWindowPrivate *qt_window_private(QWindow *window)
1898 return window->d_func();
1901 void QWindowPrivate::maybeQuitOnLastWindowClosed()
1905 // Attempt to close the application only if this has WA_QuitOnClose set and a non-visible parent
1906 bool quitOnClose = QGuiApplication::quitOnLastWindowClosed() && !q->parent();
1909 QWindowList list = QGuiApplication::topLevelWindows();
1910 bool lastWindowClosed = true;
1911 for (int i = 0; i < list.size(); ++i) {
1912 QWindow *w = list.at(i);
1913 if (!w->isVisible() || w->transientParent())
1915 lastWindowClosed = false;
1918 if (lastWindowClosed) {
1919 QGuiApplicationPrivate::emitLastWindowClosed();
1920 QCoreApplicationPrivate *applicationPrivate = static_cast<QCoreApplicationPrivate*>(QObjectPrivate::get(QCoreApplication::instance()));
1921 applicationPrivate->maybeQuit();
1927 #ifndef QT_NO_CURSOR
1929 \brief set the cursor shape for this window
1931 The mouse \a cursor will assume this shape when it is over this
1932 window, unless an override cursor is set.
1933 See the \l{Qt::CursorShape}{list of predefined cursor objects} for a
1934 range of useful shapes.
1936 By default, the cursor has the Qt::ArrowCursor shape.
1938 Some underlying window implementations will reset the cursor if it
1939 leaves a window even if the mouse is grabbed. If you want to have
1940 a cursor set for all windows, even when outside the window, consider
1941 QGuiApplication::setOverrideCursor().
1943 \sa QGuiApplication::setOverrideCursor()
1945 void QWindow::setCursor(const QCursor &cursor)
1949 // Only attempt to set cursor and emit signal if there is an actual platform cursor
1950 if (d->screen->handle()->cursor()) {
1952 QEvent event(QEvent::CursorChange);
1953 QGuiApplication::sendEvent(this, &event);
1958 \brief Restores the default arrow cursor for this window.
1960 void QWindow::unsetCursor()
1962 setCursor(Qt::ArrowCursor);
1966 \brief the cursor shape for this window
1968 \sa setCursor(), unsetCursor()
1970 QCursor QWindow::cursor() const
1976 void QWindowPrivate::applyCursor()
1979 if (platformWindow) {
1980 if (QPlatformCursor *platformCursor = screen->handle()->cursor()) {
1981 QCursor *oc = QGuiApplication::overrideCursor();
1982 QCursor c = oc ? *oc : cursor;
1983 platformCursor->changeCursor(&c, q);
1987 #endif // QT_NO_CURSOR