src/gui/kernel/qplatformwindow.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   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.
  16 **
  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.
  24 **
  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.
  28 **
  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.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qplatformwindow.h"
  43 #include "qplatformwindow_p.h"
  44
  45 #include <qpa/qwindowsysteminterface.h>
  46 #include <QtGui/qwindow.h>
  47 #include <QtGui/qscreen.h>
  48
  49 QT_BEGIN_NAMESPACE
  50
  51 /*!
  52     Constructs a platform window with the given top level window.
  53 */
  54
  55 QPlatformWindow::QPlatformWindow(QWindow *window)
  56     : QPlatformSurface(window)
  57     , d_ptr(new QPlatformWindowPrivate)
  58 {
  59     Q_D(QPlatformWindow);
  60     d->rect = window->geometry();
  61 }
  62
  63 /*!
  64     Virtual destructor does not delete its top level window.
  65 */
  66 QPlatformWindow::~QPlatformWindow()
  67 {
  68 }
  69
  70 /*!
  71     Returns the window which belongs to the QPlatformWindow
  72 */
  73 QWindow *QPlatformWindow::window() const
  74 {
  75     return static_cast<QWindow *>(m_surface);
  76 }
  77
  78 /*!
  79     Returns the parent platform window (or 0 if orphan).
  80 */
  81 QPlatformWindow *QPlatformWindow::parent() const
  82 {
  83     return window()->parent() ? window()->parent()->handle() : 0;
  84 }
  85
  86 /*!
  87     Returns the platform screen handle corresponding to this platform window.
  88 */
  89 QPlatformScreen *QPlatformWindow::screen() const
  90 {
  91     return window()->screen()->handle();
  92 }
  93
  94 /*!
  95     Returns the actual surface format of the window.
  96 */
  97 QSurfaceFormat QPlatformWindow::format() const
  98 {
  99     return QSurfaceFormat();
 100 }
 101
 102 /*!
 103     This function is called by Qt whenever a window is moved or the window is resized. The resize
 104     can happen programatically(from ie. user application) or by the window manager. This means that
 105     there is no need to call this function specifically from the window manager callback, instead
 106     call QWindowSystemInterface::handleGeometryChange(QWindow *w, const QRect &newRect);
 107
 108     The position(x, y) part of the rect might be inclusive or exclusive of the window frame
 109     as returned by frameMargins(). You can detect this in the plugin by checking
 110     qt_window_private(window())->positionPolicy.
 111 */
 112 void QPlatformWindow::setGeometry(const QRect &rect)
 113 {
 114     Q_D(QPlatformWindow);
 115     d->rect = rect;
 116 }
 117
 118 /*!
 119     Returnes the current geometry of a window
 120 */
 121 QRect QPlatformWindow::geometry() const
 122 {
 123     Q_D(const QPlatformWindow);
 124     return d->rect;
 125 }
 126
 127 QMargins QPlatformWindow::frameMargins() const
 128 {
 129     return QMargins();
 130 }
 131
 132 /*!
 133     Reimplemented in subclasses to show the surface
 134     if \a visible is \c true, and hide it if \a visible is \c false.
 135
 136     The default implementation sends a synchronous expose event.
 137 */
 138 void QPlatformWindow::setVisible(bool visible)
 139 {
 140     Q_UNUSED(visible);
 141     QRect rect(QPoint(), geometry().size());
 142     QWindowSystemInterface::handleExposeEvent(window(), rect);
 143     QWindowSystemInterface::flushWindowSystemEvents();
 144 }
 145
 146 /*!
 147     Requests setting the window flags of this surface
 148     to \a flags.
 149 */
 150 void QPlatformWindow::setWindowFlags(Qt::WindowFlags flags)
 151 {
 152     Q_UNUSED(flags);
 153 }
 154
 155 /*!
 156     Returns if this window is exposed in the windowing system.
 157
 158     An exposeEvent() is sent every time this value changes.
 159  */
 160
 161 bool QPlatformWindow::isExposed() const
 162 {
 163     return window()->isVisible();
 164 }
 165
 166 /*!
 167     Returns true if the window should appear active from a style perspective.
 168
 169     This function can make platform-specific isActive checks, such as checking
 170     if the QWindow is embedded in an active native window.
 171 */
 172 bool QPlatformWindow::isActive() const
 173 {
 174     return false;
 175 }
 176
 177 /*!
 178     Returns true if the window is a descendant of an embedded non-Qt window.
 179     Example of an embedded non-Qt window is the parent window of an in-process QAxServer.
 180
 181     If \a parentWindow is nonzero, only check if the window is embedded in the
 182     specified \a parentWindow.
 183 */
 184 bool QPlatformWindow::isEmbedded(const QPlatformWindow *parentWindow) const
 185 {
 186     Q_UNUSED(parentWindow);
 187     return false;
 188 }
 189
 190 /*!
 191     Translates the window coordinate \a pos to global screen
 192     coordinates using native methods. This is required for embedded windows,
 193     where the topmost QWindow coordinates are not global screen coordinates.
 194
 195     Returns \a pos if there is no platform specific implementation.
 196 */
 197 QPoint QPlatformWindow::mapToGlobal(const QPoint &pos) const
 198 {
 199     return pos;
 200 }
 201
 202 /*!
 203     Translates the global screen coordinate \a pos to window
 204     coordinates using native methods. This is required for embedded windows,
 205     where the topmost QWindow coordinates are not global screen coordinates.
 206
 207     Returns \a pos if there is no platform specific implementation.
 208 */
 209 QPoint QPlatformWindow::mapFromGlobal(const QPoint &pos) const
 210 {
 211     return pos;
 212 }
 213
 214 /*!
 215     Requests setting the window state of this surface
 216     to \a type.
 217
 218     Qt::WindowActive can be ignored.
 219 */
 220 void QPlatformWindow::setWindowState(Qt::WindowState)
 221 {
 222 }
 223
 224 /*!
 225   Reimplement in subclasses to return a handle to the native window
 226 */
 227 WId QPlatformWindow::winId() const
 228 {
 229     // Return anything but 0. Returning 0 would cause havoc with QWidgets on
 230     // very basic platform plugins that do not reimplement this function,
 231     // because the top-level widget's internalWinId() would always be 0 which
 232     // would mean top-levels are never treated as native.
 233     return WId(1);
 234 }
 235
 236 /*!
 237     This function is called to enable native child window in QPA. It is common not to support this
 238     feature in Window systems, but can be faked. When this function is called all geometry of this
 239     platform window will be relative to the parent.
 240 */
 241 //jl: It would be useful to have a property on the platform window which indicated if the sub-class
 242 // supported the setParent. If not, then geometry would be in screen coordinates.
 243 void QPlatformWindow::setParent(const QPlatformWindow *parent)
 244 {
 245     Q_UNUSED(parent);
 246     qWarning("This plugin does not support setParent!");
 247 }
 248
 249 /*!
 250   Reimplement to set the window title to \a title
 251 */
 252 void QPlatformWindow::setWindowTitle(const QString &title) { Q_UNUSED(title); }
 253
 254 /*!
 255   Reimplement to set the window file path to \a filePath
 256 */
 257 void QPlatformWindow::setWindowFilePath(const QString &filePath) { Q_UNUSED(filePath); }
 258
 259 /*!
 260   Reimplement to set the window icon to \a icon
 261 */
 262 void QPlatformWindow::setWindowIcon(const QIcon &icon) { Q_UNUSED(icon); }
 263
 264 /*!
 265   Reimplement to be able to let Qt raise windows to the top of the desktop
 266 */
 267 void QPlatformWindow::raise() { qWarning("This plugin does not support raise()"); }
 268
 269 /*!
 270   Reimplement to be able to let Qt lower windows to the bottom of the desktop
 271 */
 272 void QPlatformWindow::lower() { qWarning("This plugin does not support lower()"); }
 273
 274 /*!
 275   Reimplement to propagate the size hints of the QWindow.
 276
 277   The size hints include QWindow::minimumSize(), QWindow::maximumSize(),
 278   QWindow::sizeIncrement(), and QWindow::baseSize().
 279 */
 280 void QPlatformWindow::propagateSizeHints() {qWarning("This plugin does not support propagateSizeHints()"); }
 281
 282 /*!
 283   Reimplement to be able to let Qt set the opacity level of a window
 284 */
 285 void QPlatformWindow::setOpacity(qreal level)
 286 {
 287     Q_UNUSED(level);
 288     qWarning("This plugin does not support setting window opacity");
 289 }
 290
 291 /*!
 292   Reimplement to  be able to let Qt set the mask of a window
 293 */
 294
 295 void QPlatformWindow::setMask(const QRegion &region)
 296 {
 297     Q_UNUSED(region);
 298     qWarning("This plugin does not support setting window masks");
 299 }
 300
 301 /*!
 302   Reimplement to let Qt be able to request activation/focus for a window
 303
 304   Some window systems will probably not have callbacks for this functionality,
 305   and then calling QWindowSystemInterface::handleWindowActivated(QWindow *w)
 306   would be sufficient.
 307
 308   If the window system has some event handling/callbacks then call
 309   QWindowSystemInterface::handleWindowActivated(QWindow *w) when the window system
 310   gives the notification.
 311
 312   Default implementation calls QWindowSystem::handleWindowActivated(QWindow *w)
 313 */
 314 void QPlatformWindow::requestActivateWindow()
 315 {
 316     QWindowSystemInterface::handleWindowActivated(window());
 317 }
 318
 319 /*!
 320   Handle changes to the orientation of the platform window's contents.
 321
 322   This is a hint to the window manager in case it needs to display
 323   additional content like popups, dialogs, status bars, or similar
 324   in relation to the window.
 325
 326   \sa QWindow::reportContentOrientationChange()
 327 */
 328 void QPlatformWindow::handleContentOrientationChange(Qt::ScreenOrientation orientation)
 329 {
 330     Q_UNUSED(orientation);
 331 }
 332
 333 /*!
 334   Request a different orientation of the platform window.
 335
 336   This tells the window manager how the window wants to be rotated in order
 337   to be displayed, and how input events should be translated.
 338
 339   As an example, a portrait compositor might rotate the window by 90 degrees,
 340   if the window is in landscape. It will also rotate input coordinates from
 341   portrait to landscape such that top right in portrait gets mapped to top
 342   left in landscape.
 343
 344   If the implementation doesn't support the requested orientation it should
 345   signal this by returning an actual supported orientation.
 346
 347   If the implementation doesn't support rotating the window at all it should
 348   return Qt::PrimaryOrientation, this is also the default value.
 349
 350   \sa QWindow::requestWindowOrientation()
 351 */
 352 Qt::ScreenOrientation QPlatformWindow::requestWindowOrientation(Qt::ScreenOrientation orientation)
 353 {
 354     Q_UNUSED(orientation);
 355     return Qt::PrimaryOrientation;
 356 }
 357
 358 bool QPlatformWindow::setKeyboardGrabEnabled(bool grab)
 359 {
 360     Q_UNUSED(grab);
 361     qWarning("This plugin does not support grabbing the keyboard");
 362     return false;
 363 }
 364
 365 bool QPlatformWindow::setMouseGrabEnabled(bool grab)
 366 {
 367     Q_UNUSED(grab);
 368     qWarning("This plugin does not support grabbing the mouse");
 369     return false;
 370 }
 371
 372 /*!
 373     Reimplement to be able to let Qt indicate that the window has been
 374     modified. Return true if the native window supports setting the modified
 375     flag, false otherwise.
 376 */
 377 bool QPlatformWindow::setWindowModified(bool modified)
 378 {
 379     Q_UNUSED(modified);
 380     return false;
 381 }
 382
 383 /*!
 384     Reimplement this method to be able to do any platform specific event
 385     handling. All events for window() are passed to this function before being
 386     sent to QWindow::event().
 387
 388     The default implementation is empty and does nothing with \a event.
 389 */
 390 void QPlatformWindow::windowEvent(QEvent *event)
 391 {
 392     Q_UNUSED(event);
 393 }
 394
 395 /*!
 396     Reimplement this method to start a system size grip drag
 397     operation if the system supports it and return true to indicate
 398     success.
 399     It is called from the mouse press event handler of the size grip.
 400
 401     The default implementation is empty and does nothing with \a pos
 402     and \a corner.
 403 */
 404
 405 bool QPlatformWindow::startSystemResize(const QPoint &pos, Qt::Corner corner)
 406 {
 407     Q_UNUSED(pos)
 408     Q_UNUSED(corner)
 409     return false;
 410 }
 411
 412 /*!
 413     Reimplement this method to set whether frame strut events
 414     should be sent to \a enabled.
 415
 416     \sa frameStrutEventsEnabled
 417 */
 418
 419 void QPlatformWindow::setFrameStrutEventsEnabled(bool enabled)
 420 {
 421     if (enabled)
 422         qWarning("This plugin does not support frame strut events.");
 423 }
 424
 425 /*!
 426     Reimplement this method to return whether
 427     frame strut events are enabled.
 428 */
 429
 430 bool QPlatformWindow::frameStrutEventsEnabled() const
 431 {
 432     return false;
 433 }
 434
 435 /*!
 436     \class QPlatformWindow
 437     \since 4.8
 438     \internal
 439     \preliminary
 440     \ingroup qpa
 441
 442     \brief The QPlatformWindow class provides an abstraction for top-level windows.
 443
 444     The QPlatformWindow abstraction is used by QWindow for all its top level windows. It is being
 445     created by calling the createPlatformWindow function in the loaded QPlatformIntegration
 446     instance.
 447
 448     QPlatformWindow is used to signal to the windowing system, how Qt perceives its frame.
 449     However, it is not concerned with how Qt renders into the window it represents.
 450
 451     Visible QWindows will always have a QPlatformWindow. However, it is not necessary for
 452     all windows to have a QBackingStore. This is the case for QOpenGLWidget. And could be the case for
 453     windows where some  3.party renders into it.
 454
 455     The platform specific window handle can be retrieved by the winId function.
 456
 457     QPlatformWindow is also the way QPA defines how native child windows should be supported
 458     through the setParent function.
 459
 460     The only way to retrieve a QPlatformOpenGLContext in QPA is by calling the glContext() function
 461     on QPlatformWindow.
 462
 463     \section1 Implementation Aspects
 464
 465     \list 1
 466         \li Mouse grab: Qt expects windows to automatically grab the mouse if the user presses
 467             a button until the button is released.
 468             Automatic grab should be released if some window is explicitly grabbed.
 469         \li Enter/Leave events: Enter and leave events should be sent independently of
 470             explicit mouse grabs (\c{setMouseGrabEnabled()}). That is, if the mouse leaves
 471             a window that has explicit mouse grab, a leave event should be sent and other
 472             windows should get enter/leave events as well as the mouse traverses them.
 473             For automatic mouse grab, however, a leave event should be sent when the
 474             button is released.
 475         \li Window positioning: When calling \c{QWindow::setFramePos()}, the flag
 476             \c{QWindowPrivate::positionPolicy} is set to \c{QWindowPrivate::WindowFrameInclusive}.
 477             This means the position includes the window frame, whose size is at this point
 478             unknown and the geometry's topleft point is the position of the window frame.
 479     \endlist
 480
 481     Apart from the auto-tests (\c{tests/auto/gui/kernel/qwindow},
 482     \c{tests/auto/gui/kernel/qguiapplication} and \c{tests/auto/widgets/kernel/qwidget}),
 483     there are a number of manual tests and examples that can help testing a platform plugin:
 484
 485     \list 1
 486         \li \c{examples/qpa/windows}: Basic \c{QWindow} creation.
 487         \li \c{examples/opengl/hellowindow}: Basic Open GL windows.
 488         \li \c{tests/manual/windowflags}: Tests setting the window flags.
 489         \li \c{tests/manual/windowgeometry} Tests setting the window geometry.
 490         \li \c{tests/manual/windowmodality} Tests setting the window modality.
 491         \li \c{tests/manual/widgetgrab} Tests mouse grab and dialogs.
 492     \endlist
 493
 494     \sa QBackingStore, QWindow
 495 */
 496
 497 QT_END_NAMESPACE