From 206122b405ca8b4dd3fe9fba2a15adce54b7e885 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:48:25 +0200
Subject: [PATCH] Platform: make it possible to create & add a Screen in one
 step.

---
 doc/changelog.dox                           |  5 +++++
 src/Magnum/Platform/Screen.h                | 21 +++++++++++++++++++++
 src/Magnum/Platform/ScreenedApplication.h   |  6 ++++++
 src/Magnum/Platform/ScreenedApplication.hpp | 12 ++++++++++++
 4 files changed, 44 insertions(+)

diff --git a/doc/changelog.dox b/doc/changelog.dox
index d56006293..b00e6fbf8 100644
--- a/doc/changelog.dox
+++ b/doc/changelog.dox
@@ -359,6 +359,11 @@ See also:
     application implementations that provide such events
 -   @ref Platform::BasicScreenedApplication is now available also for
     @ref Platform::AndroidApplication
+-   New @ref Platform::BasicScreen::BasicScreen(BasicScreenedApplication<Application>&, PropagatedEvents&)
+    constructor that directly adds the newly-created screen to an application
+    in a RAII manner, without needing to explicitly call
+    @ref Platform::BasicScreenedApplication::addScreen() and
+    @ref Platform::BasicScreen::setPropagatedEvents() later
 
 @subsubsection changelog-latest-changes-text Text library
 
diff --git a/src/Magnum/Platform/Screen.h b/src/Magnum/Platform/Screen.h
index 3cdd1914f..682f0086c 100644
--- a/src/Magnum/Platform/Screen.h
+++ b/src/Magnum/Platform/Screen.h
@@ -212,8 +212,28 @@ template<class Application> class BasicScreen:
         typedef typename BasicScreenedApplication<Application>::TextEditingEvent TextEditingEvent;
         #endif
 
+        /**
+         * @brief Construct a detached screen
+         *
+         * The screen is not attached to any application, use
+         * @ref BasicScreenedApplication::addScreen() to add it. Alternatively,
+         * use @ref BasicScreen(BasicScreenedApplication<Application>&, PropagatedEvents) to
+         * attach the screen right during the construction.
+         */
         explicit BasicScreen();
 
+        /**
+         * @brief Construct a screen and attach it to an application
+         *
+         * Unlike with @ref BasicScreen(), the screen is added to the
+         * application already during the construction, removing the need to
+         * call @ref addScreen() later. This also means @ref focusEvent() is
+         * not called for the very first time, assuming the screen is put into
+         * desired state already during construction.
+         * @see @ref setPropagatedEvents()
+         */
+        explicit BasicScreen(BasicScreenedApplication<Application>& application, PropagatedEvents events);
+
         /* A common use case is a list of screen derivatives, so allow deleting
            them through a base pointer */
         virtual ~BasicScreen();
@@ -227,6 +247,7 @@ template<class Application> class BasicScreen:
          * For non-propagated events related event functions are not called.
          * No events are propagated by default, call this function in
          * @ref focusEvent() and @ref blurEvent() to reflect focus changes.
+         * @see @ref BasicScreen(BasicScreenedApplication<Application>&, PropagatedEvents)
          */
         void setPropagatedEvents(PropagatedEvents events) { _propagatedEvents = events; }
 
diff --git a/src/Magnum/Platform/ScreenedApplication.h b/src/Magnum/Platform/ScreenedApplication.h
index 2ee242ce2..9f1a816e3 100644
--- a/src/Magnum/Platform/ScreenedApplication.h
+++ b/src/Magnum/Platform/ScreenedApplication.h
@@ -219,6 +219,12 @@ template<class Application> class BasicScreenedApplication:
          * added, @ref BasicScreen::focusEvent() is called. If not, neither
          * @ref BasicScreen::blurEvent() nor @ref BasicScreen::focusEvent() is
          * called (i.e. the screen default state is used).
+         *
+         * Alternatively, a screen can be created using the
+         * @ref BasicScreen::BasicScreen(BasicScreenedApplication<Application>&, PropagatedEvents)
+         * constructor. In that case, the first @ref BasicScreen::focusEvent()
+         * is not called, assuming the screen is put into desired state already
+         * during construction.
          */
         BasicScreenedApplication<Application>& addScreen(BasicScreen<Application>& screen);
 
diff --git a/src/Magnum/Platform/ScreenedApplication.hpp b/src/Magnum/Platform/ScreenedApplication.hpp
index 9a2263346..3ec90ec9d 100644
--- a/src/Magnum/Platform/ScreenedApplication.hpp
+++ b/src/Magnum/Platform/ScreenedApplication.hpp
@@ -106,6 +106,15 @@ true>::textEditingEvent(TextEditingEvent&) {}
 }
 
 template<class Application> BasicScreen<Application>::BasicScreen() = default;
+
+template<class Application> BasicScreen<Application>::BasicScreen(BasicScreenedApplication<Application>& application, PropagatedEvents events) {
+    /* A superset of this (together with focusEvent()) is done in
+       BasicScreenedApplication::addScreen() as well. Keep in sync. */
+    application.Containers::template LinkedList<BasicScreen<Application>>::insert(this);
+    redraw();
+    setPropagatedEvents(events);
+}
+
 template<class Application> BasicScreen<Application>::~BasicScreen() = default;
 
 template<class Application> void BasicScreen<Application>::focusEvent() {}
@@ -140,6 +149,9 @@ template<class Application> BasicScreenedApplication<Application>::BasicScreened
 template<class Application> BasicScreenedApplication<Application>::~BasicScreenedApplication() = default;
 
 template<class Application> BasicScreenedApplication<Application>& BasicScreenedApplication<Application>::addScreen(BasicScreen<Application>& screen) {
+    /* A subset of this (except focusEvent()) is done in
+       BasicScreen(BasicScreenedApplication&, PropagatedEvents) as well. Keep
+       in sync. */
     Containers::LinkedList<BasicScreen<Application>>::insert(&screen);
     if(screens().first() == &screen) screen.focusEvent();
     Application::redraw();