Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example rasterwindow
++ \title Raster Window Example
++ \examplecategory {Graphics}
++
++ \brief This example shows how to create a minimal QWindow based
++ application using QPainter for rendering.
++
++
++ \section1 Application Entry Point
++
++ \snippet rasterwindow/main.cpp 1
++
++ The entry point for a QWindow based application is the \l
++ QGuiApplication class. It manages the GUI application's control
++ flow and main settings. We pass the command line arguments which
++ can be used to pick up certain system wide options.
++
++ From there, we go on to create our window instance and then call
++ the \l QWindow::show() function to tell the windowing system that
++ this window should now be made visible on screen.
++
++ Once this is done, we enter the application's event loop so the
++ application can run.
++
++
++ \section1 RasterWindow Declaration
++
++ \snippet rasterwindow/rasterwindow.h 1
++
++ We first start by including the \c <QtGui> header. This means we
++ can use all classes in the Qt GUI module. Classes can also be
++ included individually if that is preferred.
++
++ The RasterWindow class subclasses QWindow directly and provides a
++ constructor which allows the window to be a sub-window of another
++ QWindow. Parent-less QWindows show up in the windowing system as
++ top-level windows.
++
++ The class declares a QBackingStore which is what we use to manage
++ the window's back buffer for QPainter based graphics.
++
++ \e {The raster window is also reused in a few other examples and adds
++ a few helper functions, like renderLater().}
++
++
++ \section1 RasterWindow Implementation
++
++ \snippet rasterwindow/rasterwindow.cpp 1
++
++ In the constructor we create the backingstore and pass it the window
++ instance it is supposed to manage. We also set the initial window
++ geometry.
++
++ \snippet rasterwindow/rasterwindow.cpp 2
++
++ Shortly after calling \l QWindow::show() on a created window, the
++ virtual function \l QWindow::exposeEvent() will be called to
++ notify us that the window's exposure in the windowing system has
++ changed. The event contains the exposed sub-region, but since we
++ will anyway draw the entire window every time, we do not make use
++ of that.
++
++ The function \l QWindow::isExposed() will tell us if the window is
++ showing or not. We need this as the exposeEvent is called also
++ when the window becomes obscured in the windowing system. If the
++ window is showing, we call renderNow() to draw the window
++ immediately. We want to draw right away so we can present the
++ system with some visual content.
++
++
++ \snippet rasterwindow/rasterwindow.cpp 5
++
++ The resize event is guaranteed to be called prior to the window
++ being shown on screen and will also be called whenever the window
++ is resized while on screen. We use this to resize the back buffer,
++ and defer rendering to the corresponding/following expose event.
++
++ \snippet rasterwindow/rasterwindow.cpp 3
++
++ The renderNow function sets up what is needed for a \l QWindow to
++ render its content using QPainter. As obscured windows have will
++ not be visible, we abort if the window is not exposed in the
++ windowing system. This can for instance happen when another window
++ fully obscures this window.
++
++ We start the drawing by calling \l QBackingStore::beginPaint() on
++ the region we want to draw. Then we get the \l QPaintDevice of the
++ back buffer and create a QPainter to render to that paint device.
++
++ To void leaving traces from the previous rendering and start with a
++ clean buffer, we fill the entire buffer with the color white. Then
++ we call the virtual render() function which does the actual
++ drawing of this window.
++
++ After drawing is complete, we call endPaint() to signal that we
++ are done rendering and present the contents in the back buffer
++ using \l QBackingStore::flush().
++
++
++ \snippet rasterwindow/rasterwindow.cpp 4
++
++ The render function contains the drawing code for the window. In
++ this minial example, we only draw the string "QWindow" in the
++ center.
++
++
++ \section1 Rendering Asynchronously
++
++
++ \snippet rasterwindow/rasterwindow.cpp 6
++
++ We went through a few places where the window needed to repainted
++ immediately. There are some cases where this is not desirable,
++ but rather let the application return to the event loop and
++ schedule the repaint for later. We achieve this by requesting
++ an update, using QWindow::requestUpdate(), which will then be
++ delivered when the system is ready to repaint.
++
++ \snippet rasterwindow/rasterwindow.cpp 7
++
++ We reimplement the virtual \l QObject::event() function to handle
++ the update event. When the event comes in we call renderNow() to
++ render the window right away.
++
++ */