From 081f784836f08d67e42c3165b0a73bafa7ea9858 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Fri, 2 Aug 2019 13:27:27 +0200
Subject: [PATCH] Platform: improve ScreenedApplication docs.

---
 doc/snippets/MagnumPlatform.cpp           | 51 +++++++++++++++++++++++
 src/Magnum/Platform/Screen.h              |  7 ++--
 src/Magnum/Platform/ScreenedApplication.h | 47 ++++++++++++---------
 3 files changed, 81 insertions(+), 24 deletions(-)

diff --git a/doc/snippets/MagnumPlatform.cpp b/doc/snippets/MagnumPlatform.cpp
index 380452a6c..04a323444 100644
--- a/doc/snippets/MagnumPlatform.cpp
+++ b/doc/snippets/MagnumPlatform.cpp
@@ -27,6 +27,8 @@
 #include <Magnum/GL/DefaultFramebuffer.h>
 #include <Magnum/GL/Renderer.h>
 #include <Magnum/Math/Color.h>
+#include <Magnum/Platform/ScreenedApplication.h>
+#include <Magnum/Platform/Screen.h>
 #include <Magnum/Platform/Sdl2Application.h>
 #include <Magnum/Platform/GLContext.h>
 
@@ -144,3 +146,52 @@ MyApplication::MyApplication(const Arguments& arguments):
 /* [trycreatecontext] */
 
 }
+
+namespace F {
+
+int argc = 0;
+struct MyApplication: Platform::ScreenedApplication {
+    MyApplication(): Platform::ScreenedApplication{Arguments{argc, nullptr}} {}
+
+    void globalViewportEvent(ViewportEvent& event) override;
+    void globalDrawEvent() override;
+};
+
+/* [ScreenedApplication-global-events] */
+void MyApplication::globalViewportEvent(ViewportEvent& event) {
+    GL::defaultFramebuffer.setViewport({{}, event.framebufferSize()});
+
+    // Other stuff that should be done *before* all other event handlers ...
+}
+
+void MyApplication::globalDrawEvent() {
+    // Other stuff that should be done *after* all other event handlers ...
+
+    swapBuffers();
+}
+/* [ScreenedApplication-global-events] */
+
+void foo();
+void foo() {
+#ifdef __GNUC__
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wunused-variable"
+#endif
+/* [ScreenedApplication-for-range] */
+MyApplication app;
+for(Platform::Screen& screen: app.screens()) {
+    // ...
+}
+/* [ScreenedApplication-for-range] */
+
+/* [ScreenedApplication-for] */
+for(Platform::Screen* s = app.screens().first(); s; s = s->nextFartherScreen()) {
+    // ...
+}
+/* [ScreenedApplication-for] */
+#ifdef __GNUC__
+#pragma GCC diagnostic pop
+#endif
+}
+
+}
diff --git a/src/Magnum/Platform/Screen.h b/src/Magnum/Platform/Screen.h
index 9f993c866..3cdd1914f 100644
--- a/src/Magnum/Platform/Screen.h
+++ b/src/Magnum/Platform/Screen.h
@@ -101,15 +101,14 @@ template<class Application> class ScreenTextEditingEventMixin<Application, true>
 
 @m_keywords{Screen}
 
-See @ref BasicScreenedApplication for more information.
-
-If exactly one application header is included, this class is also aliased to
+See @ref BasicScreenedApplication for more information. If exactly one
+application header is included, this class is also aliased to
 @cpp Platform::Screen @ce.
 
 @section Platform-BasicScreen-template-specializations Explicit template specializations
 
 The following specialization are explicitly compiled into each particular
-`*Application` library. For other specializations you have to use
+`*Application` library. For other specializations you have to use the
 @ref ScreenedApplication.hpp implementation file to avoid linker errors. See
 @ref compilation-speedup-hpp for more information.
 
diff --git a/src/Magnum/Platform/ScreenedApplication.h b/src/Magnum/Platform/ScreenedApplication.h
index d9445af17..2ee242ce2 100644
--- a/src/Magnum/Platform/ScreenedApplication.h
+++ b/src/Magnum/Platform/ScreenedApplication.h
@@ -105,14 +105,16 @@ template<class Application> struct ApplicationTextEditingEventMixin<Application,
 
 @m_keywords{ScreenedApplication}
 
-Manages list of screens and propagates events to them.
-
-If exactly one application header is included, this class is also aliased to
+Manages list of screens and propagates events to them. If exactly one
+application header is included, this class is also aliased to
 @cpp Platform::ScreenedApplication @ce.
 
-Each @ref BasicScreen "Screen" specifies which set of events should be
-propagated to it using @ref BasicScreen::setPropagatedEvents(). When
-application gets an event, they are propagated to the screens:
+When you derive from this class, you're not allowed to implement any
+usual application event handlers --- instead, these are propagated to
+@ref BasicScreen "Screen" instances that get added using @ref addScreen(). Each
+@ref BasicScreen "Screen" specifies which set of events should be propagated to
+it using @ref BasicScreen::setPropagatedEvents(). When the application gets an
+event, they are propagated to the screens:
 
 -   @ref Sdl2Application::viewportEvent() "viewportEvent()" is propagated to
     all screens.
@@ -122,37 +124,42 @@ application gets an event, they are propagated to the screens:
 -   Input events (@ref Sdl2Application::keyPressEvent() "keyPressEvent()",
     @ref Sdl2Application::keyReleaseEvent() "keyReleaseEvent()",
     @ref Sdl2Application::mousePressEvent() "mousePressEvent()",
-    @ref Sdl2Application::mouseReleaseEvent() "mouseReleaseEvent()"
-    and @ref Sdl2Application::mouseMoveEvent() "mouseMoveEvent()")
+    @ref Sdl2Application::mouseReleaseEvent() "mouseReleaseEvent()",
+    @ref Sdl2Application::mouseMoveEvent() "mouseMoveEvent()",
+    @ref Sdl2Application::mouseMoveEvent() "mouseScrollEvent()",
+    @ref Sdl2Application::textInputEvent() "textInputEvent()" and
+    @ref Sdl2Application::textEditingEvent() "textEditingEvent()")
     are propagated in front-to-back order to screens which have
     @ref BasicScreen::PropagatedEvent::Input enabled. If any screen sets the
     event as accepted, it is not propagated further.
 
+For the actual application, at the very least you need to implement
+@ref globalDrawEvent(), and in case your application is resizable,
+@ref globalViewportEvent() as well. The global draw event gets called *after*
+all @ref BasicScreen::drawEvent() "Screen::drawEvent()" in order to make it
+possible for you to do a buffer swap, while the global viewport event gets
+called *before* all @ref BasicScreen::viewportEvent() "Screen::viewportEvent()",
+in this case to make it possible to handle viewport changes on the default
+framebuffer:
+
+@snippet MagnumPlatform.cpp ScreenedApplication-global-events
+
 Uses @ref Corrade::Containers::LinkedList for efficient screen management.
 Traversing front-to-back through the list of screens can be done using
 range-based for:
 
-@code{.cpp}
-MyApplication app;
-for(Screen& screen: app.screens()) {
-    // ...
-}
-@endcode
+@snippet MagnumPlatform.cpp ScreenedApplication-for-range
 
 Or, if you need more flexibility, like in the following code. Traversing
 back-to-front can be done using @ref Corrade::Containers::LinkedList::last()
 and @ref BasicScreen::nextNearerScreen().
 
-@code{.cpp}
-for(Screen* s = app.screens().first(); s; s = s->nextFartherScreen()) {
-    // ...
-}
-@endcode
+@snippet MagnumPlatform.cpp ScreenedApplication-for
 
 @section Platform-ScreenedApplication-template-specializations Explicit template specializations
 
 The following specialization are explicitly compiled into each particular
-`*Application` library. For other specializations you have to use
+`*Application` library. For other specializations you have to use the
 @ref ScreenedApplication.hpp implementation file to avoid linker errors. See
 @ref compilation-speedup-hpp for more information.