qt 6.5.1 original

examples/gui/doc/src/rasterwindow.qdoc

@@ -0,0 +1,128 @@
+// 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
+
+    \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.
+
+  */