include/QtGui/qwindow.h

0001 // Copyright (C) 2016 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003
0004 #ifndef QWINDOW_H
0005 #define QWINDOW_H
0006
0007 #include <QtGui/qtguiglobal.h>
0008 #include <QtCore/QObject>
0009 #include <QtCore/QEvent>
0010 #include <QtCore/QMargins>
0011 #include <QtCore/QRect>
0012
0013 #include <QtCore/qnamespace.h>
0014 #include <QtCore/qnativeinterface.h>
0015
0016 #include <QtGui/qsurface.h>
0017 #include <QtGui/qsurfaceformat.h>
0018 #include <QtGui/qwindowdefs.h>
0019
0020 #include <QtGui/qicon.h>
0021
0022 #ifndef QT_NO_CURSOR
0023 #include <QtGui/qcursor.h>
0024 #endif
0025
0026 QT_BEGIN_NAMESPACE
0027
0028
0029 class QWindowPrivate;
0030
0031 class QExposeEvent;
0032 class QPaintEvent;
0033 class QFocusEvent;
0034 class QMoveEvent;
0035 class QResizeEvent;
0036 class QShowEvent;
0037 class QHideEvent;
0038 class QCloseEvent;
0039 class QKeyEvent;
0040 class QMouseEvent;
0041 #if QT_CONFIG(wheelevent)
0042 class QWheelEvent;
0043 #endif
0044 class QTouchEvent;
0045 #if QT_CONFIG(tabletevent)
0046 class QTabletEvent;
0047 #endif
0048
0049 class QPlatformSurface;
0050 class QPlatformWindow;
0051 class QBackingStore;
0052 class QScreen;
0053 class QAccessibleInterface;
0054 class QWindowContainer;
0055 #ifndef QT_NO_DEBUG_STREAM
0056 class QDebug;
0057 #endif
0058 #if QT_CONFIG(vulkan) || defined(Q_QDOC)
0059 class QVulkanInstance;
0060 #endif
0061
0062 class Q_GUI_EXPORT QWindow : public QObject, public QSurface
0063 {
0064     Q_OBJECT
0065     Q_DECLARE_PRIVATE(QWindow)
0066
0067     // All properties which are declared here are inherited by QQuickWindow and therefore available in QML.
0068     // So please think carefully about what it does to the QML namespace if you add any new ones,
0069     // particularly the possible meanings these names might have in any specializations of Window.
0070     // For example "state" (meaning windowState) is not a good property to declare, because it has
0071     // a different meaning in QQuickItem, and users will tend to assume it is the same for Window.
0072
0073     // Any new properties which you add here MUST be versioned and MUST be documented both as
0074     // C++ properties in qwindow.cpp AND as QML properties in qquickwindow.cpp.
0075     // https://doc.qt.io/qt/qtqml-cppintegration-definetypes.html#type-revisions-and-versions
0076
0077     Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY windowTitleChanged)
0078     Q_PROPERTY(Qt::WindowModality modality READ modality WRITE setModality NOTIFY modalityChanged)
0079     Q_PROPERTY(Qt::WindowFlags flags READ flags WRITE setFlags NOTIFY flagsChanged)
0080     Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged)
0081     Q_PROPERTY(int y READ y WRITE setY NOTIFY yChanged)
0082     Q_PROPERTY(int width READ width WRITE setWidth NOTIFY widthChanged)
0083     Q_PROPERTY(int height READ height WRITE setHeight NOTIFY heightChanged)
0084     Q_PROPERTY(int minimumWidth READ minimumWidth WRITE setMinimumWidth NOTIFY minimumWidthChanged)
0085     Q_PROPERTY(int minimumHeight READ minimumHeight WRITE setMinimumHeight
0086                NOTIFY minimumHeightChanged)
0087     Q_PROPERTY(int maximumWidth READ maximumWidth WRITE setMaximumWidth NOTIFY maximumWidthChanged)
0088     Q_PROPERTY(int maximumHeight READ maximumHeight WRITE setMaximumHeight
0089                NOTIFY maximumHeightChanged)
0090     Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibleChanged VIRTUAL)
0091     Q_PROPERTY(bool active READ isActive NOTIFY activeChanged REVISION(2, 1))
0092     Q_PROPERTY(Visibility visibility READ visibility WRITE setVisibility NOTIFY visibilityChanged VIRTUAL REVISION(2, 1))
0093     Q_PROPERTY(Qt::ScreenOrientation contentOrientation READ contentOrientation
0094                WRITE reportContentOrientationChange NOTIFY contentOrientationChanged)
0095     Q_PROPERTY(qreal opacity READ opacity WRITE setOpacity NOTIFY opacityChanged REVISION(2, 1))
0096 #ifdef Q_QDOC
0097     Q_PROPERTY(QWindow* transientParent READ transientParent WRITE setTransientParent NOTIFY transientParentChanged)
0098 #else
0099     Q_PRIVATE_PROPERTY(QWindow::d_func(), QWindow* transientParent MEMBER transientParent
0100                        WRITE setTransientParent NOTIFY transientParentChanged REVISION(2, 13))
0101 #endif
0102
0103 public:
0104     enum Visibility {
0105         Hidden = 0,
0106         AutomaticVisibility,
0107         Windowed,
0108         Minimized,
0109         Maximized,
0110         FullScreen
0111     };
0112     Q_ENUM(Visibility)
0113
0114     enum AncestorMode {
0115         ExcludeTransients,
0116         IncludeTransients
0117     };
0118     Q_ENUM(AncestorMode)
0119
0120     explicit QWindow(QScreen *screen = nullptr);
0121     explicit QWindow(QWindow *parent);
0122     ~QWindow();
0123
0124     void setSurfaceType(SurfaceType surfaceType);
0125     SurfaceType surfaceType() const override;
0126
0127     bool isVisible() const;
0128
0129     Visibility visibility() const;
0130     void setVisibility(Visibility v);
0131
0132     void create();
0133
0134     WId winId() const;
0135
0136     QWindow *parent(AncestorMode mode = ExcludeTransients) const;
0137     void setParent(QWindow *parent);
0138
0139     bool isTopLevel() const;
0140
0141     bool isModal() const;
0142     Qt::WindowModality modality() const;
0143     void setModality(Qt::WindowModality modality);
0144
0145     void setFormat(const QSurfaceFormat &format);
0146     QSurfaceFormat format() const override;
0147     QSurfaceFormat requestedFormat() const;
0148
0149     void setFlags(Qt::WindowFlags flags);
0150     Qt::WindowFlags flags() const;
0151     void setFlag(Qt::WindowType, bool on = true);
0152     Qt::WindowType type() const;
0153
0154     QString title() const;
0155
0156     void setOpacity(qreal level);
0157     qreal opacity() const;
0158
0159     void setMask(const QRegion &region);
0160     QRegion mask() const;
0161
0162     bool isActive() const;
0163
0164     void reportContentOrientationChange(Qt::ScreenOrientation orientation);
0165     Qt::ScreenOrientation contentOrientation() const;
0166
0167     qreal devicePixelRatio() const;
0168
0169     Qt::WindowState windowState() const;
0170     Qt::WindowStates windowStates() const;
0171     void setWindowState(Qt::WindowState state);
0172     void setWindowStates(Qt::WindowStates states);
0173
0174     void setTransientParent(QWindow *parent);
0175     QWindow *transientParent() const;
0176
0177     bool isAncestorOf(const QWindow *child, AncestorMode mode = IncludeTransients) const;
0178
0179     bool isExposed() const;
0180
0181     inline int minimumWidth() const { return minimumSize().width(); }
0182     inline int minimumHeight() const { return minimumSize().height(); }
0183     inline int maximumWidth() const { return maximumSize().width(); }
0184     inline int maximumHeight() const { return maximumSize().height(); }
0185
0186     QSize minimumSize() const;
0187     QSize maximumSize() const;
0188     QSize baseSize() const;
0189     QSize sizeIncrement() const;
0190
0191     void setMinimumSize(const QSize &size);
0192     void setMaximumSize(const QSize &size);
0193     void setBaseSize(const QSize &size);
0194     void setSizeIncrement(const QSize &size);
0195
0196     QRect geometry() const;
0197
0198     QMargins frameMargins() const;
0199     QRect frameGeometry() const;
0200
0201     QPoint framePosition() const;
0202     void setFramePosition(const QPoint &point);
0203
0204     QMargins safeAreaMargins() const;
0205
0206     inline int width() const { return geometry().width(); }
0207     inline int height() const { return geometry().height(); }
0208     inline int x() const { return geometry().x(); }
0209     inline int y() const { return geometry().y(); }
0210
0211     QSize size() const override { return geometry().size(); }
0212     inline QPoint position() const { return geometry().topLeft(); }
0213
0214     void setPosition(const QPoint &pt);
0215     void setPosition(int posx, int posy);
0216
0217     void resize(const QSize &newSize);
0218     void resize(int w, int h);
0219
0220     void setFilePath(const QString &filePath);
0221     QString filePath() const;
0222
0223     void setIcon(const QIcon &icon);
0224     QIcon icon() const;
0225
0226     void destroy();
0227
0228     QPlatformWindow *handle() const;
0229
0230     bool setKeyboardGrabEnabled(bool grab);
0231     bool setMouseGrabEnabled(bool grab);
0232
0233     QScreen *screen() const;
0234     void setScreen(QScreen *screen);
0235
0236     virtual QAccessibleInterface *accessibleRoot() const;
0237     virtual QObject *focusObject() const;
0238
0239     QPointF mapToGlobal(const QPointF &pos) const;
0240     QPointF mapFromGlobal(const QPointF &pos) const;
0241     QPoint mapToGlobal(const QPoint &pos) const;
0242     QPoint mapFromGlobal(const QPoint &pos) const;
0243
0244 #ifndef QT_NO_CURSOR
0245     QCursor cursor() const;
0246     void setCursor(const QCursor &);
0247     void unsetCursor();
0248 #endif
0249
0250     static QWindow *fromWinId(WId id);
0251
0252 #if QT_CONFIG(vulkan) || defined(Q_QDOC)
0253     void setVulkanInstance(QVulkanInstance *instance);
0254     QVulkanInstance *vulkanInstance() const;
0255 #endif
0256
0257     QT_DECLARE_NATIVE_INTERFACE_ACCESSOR(QWindow)
0258
0259 public Q_SLOTS:
0260     Q_REVISION(2, 1) void requestActivate();
0261
0262     void setVisible(bool visible);
0263
0264     void show();
0265     void hide();
0266
0267     void showMinimized();
0268     void showMaximized();
0269     void showFullScreen();
0270     void showNormal();
0271
0272     bool close();
0273     void raise();
0274     void lower();
0275     bool startSystemResize(Qt::Edges edges);
0276     bool startSystemMove();
0277
0278     void setTitle(const QString &);
0279
0280     void setX(int arg);
0281     void setY(int arg);
0282     void setWidth(int arg);
0283     void setHeight(int arg);
0284     void setGeometry(int posx, int posy, int w, int h);
0285     void setGeometry(const QRect &rect);
0286
0287     void setMinimumWidth(int w);
0288     void setMinimumHeight(int h);
0289     void setMaximumWidth(int w);
0290     void setMaximumHeight(int h);
0291
0292     Q_REVISION(2, 1) void alert(int msec);
0293
0294     Q_REVISION(2, 3) void requestUpdate();
0295
0296 Q_SIGNALS:
0297     void screenChanged(QScreen *screen);
0298     void modalityChanged(Qt::WindowModality modality);
0299     Q_REVISION(6, 10) void flagsChanged(Qt::WindowFlags flags);
0300     void windowStateChanged(Qt::WindowState windowState);
0301     Q_REVISION(2, 2) void windowTitleChanged(const QString &title);
0302
0303     void xChanged(int arg);
0304     void yChanged(int arg);
0305
0306     void widthChanged(int arg);
0307     void heightChanged(int arg);
0308
0309     void minimumWidthChanged(int arg);
0310     void minimumHeightChanged(int arg);
0311     void maximumWidthChanged(int arg);
0312     void maximumHeightChanged(int arg);
0313
0314     Q_REVISION(6, 9) void safeAreaMarginsChanged(QMargins arg);
0315
0316     void visibleChanged(bool arg);
0317     Q_REVISION(2, 1) void visibilityChanged(QWindow::Visibility visibility);
0318     Q_REVISION(2, 1) void activeChanged();
0319     void contentOrientationChanged(Qt::ScreenOrientation orientation);
0320
0321     void focusObjectChanged(QObject *object);
0322
0323     Q_REVISION(2, 1) void opacityChanged(qreal opacity);
0324
0325     Q_REVISION(2, 13) void transientParentChanged(QWindow *transientParent);
0326
0327 protected:
0328     virtual void exposeEvent(QExposeEvent *);
0329     virtual void resizeEvent(QResizeEvent *);
0330     virtual void paintEvent(QPaintEvent *);
0331     virtual void moveEvent(QMoveEvent *);
0332     virtual void focusInEvent(QFocusEvent *);
0333     virtual void focusOutEvent(QFocusEvent *);
0334
0335     virtual void showEvent(QShowEvent *);
0336     virtual void hideEvent(QHideEvent *);
0337     virtual void closeEvent(QCloseEvent *);
0338
0339     virtual bool event(QEvent *) override;
0340     virtual void keyPressEvent(QKeyEvent *);
0341     virtual void keyReleaseEvent(QKeyEvent *);
0342     virtual void mousePressEvent(QMouseEvent *);
0343     virtual void mouseReleaseEvent(QMouseEvent *);
0344     virtual void mouseDoubleClickEvent(QMouseEvent *);
0345     virtual void mouseMoveEvent(QMouseEvent *);
0346 #if QT_CONFIG(wheelevent)
0347     virtual void wheelEvent(QWheelEvent *);
0348 #endif
0349     virtual void touchEvent(QTouchEvent *);
0350 #if QT_CONFIG(tabletevent)
0351     virtual void tabletEvent(QTabletEvent *);
0352 #endif
0353     virtual bool nativeEvent(const QByteArray &eventType, void *message, qintptr *result);
0354
0355     QWindow(QWindowPrivate &dd, QWindow *parent);
0356
0357 private:
0358     Q_PRIVATE_SLOT(d_func(), void _q_clearAlert())
0359     QPlatformSurface *surfaceHandle() const override;
0360
0361     Q_DISABLE_COPY(QWindow)
0362
0363     friend class QGuiApplication;
0364     friend class QGuiApplicationPrivate;
0365     friend class QWindowContainer;
0366     friend Q_GUI_EXPORT QWindowPrivate *qt_window_private(QWindow *window);
0367 };
0368
0369 #ifndef Q_QDOC
0370 // should these be seen by clang-qdoc?
0371 template <> inline QWindow *qobject_cast<QWindow*>(QObject *o)
0372 {
0373     if (!o || !o->isWindowType()) return nullptr;
0374     return static_cast<QWindow*>(o);
0375 }
0376 template <> inline const QWindow *qobject_cast<const QWindow*>(const QObject *o)
0377 {
0378     if (!o || !o->isWindowType()) return nullptr;
0379     return static_cast<const QWindow*>(o);
0380 }
0381 #endif // !Q_QDOC
0382
0383 #ifndef QT_NO_DEBUG_STREAM
0384 Q_GUI_EXPORT QDebug operator<<(QDebug, const QWindow *);
0385 #endif
0386
0387 QT_END_NAMESPACE
0388
0389 #endif // QWINDOW_H