Platform: add {Sdl2,Glfw,Emscripten}Application::setWindowTitle().

On Emscripten as well, however I'm keeping the Configuration::setTitle()
a no-op because the title is usually set by the HTML markup already and
so dynamic code implicitly changing it to something else doesn't make
much sense.

doc/changelog.dox

@@ -206,6 +206,10 @@ See also:
 -   New [base-wxwidgets](https://github.com/mosra/magnum-bootstrap/tree/base-wxwidgets)
     bootstrap project for using Magnum together with wxWidgets (see
     [mosra/magnum-bootstrap#19](https://github.com/mosra/magnum-bootstrap/pull/19))
+-   Added @ref Platform::Sdl2Application::setWindowTitle() (and equivalents
+    in @ref Platform::GlfwApplication and @ref Platform::EmscriptenApplication)
+    for changing window title at runtime as opposed to setting them on
+    application startup
 
 @subsubsection changelog-latest-new-primitives Primitives library
 

src/Magnum/Platform/EmscriptenApplication.cpp

@@ -384,6 +384,13 @@ Vector2i EmscriptenApplication::framebufferSize() const {
 }
 #endif
 
+void EmscriptenApplication::setWindowTitle(const std::string& title) {
+    #pragma GCC diagnostic push
+    #pragma GCC diagnostic ignored "-Wdollar-in-identifier-extension"
+    EM_ASM_({document.title = UTF8ToString($0);}, title.data());
+    #pragma GCC diagnostic pop
+}
+
 void EmscriptenApplication::setContainerCssClass(const std::string& cssClass) {
     #pragma GCC diagnostic push
     #pragma GCC diagnostic ignored "-Wdollar-in-identifier-extension"

src/Magnum/Platform/EmscriptenApplication.h

@@ -484,6 +484,13 @@ class EmscriptenApplication {
          */
         Vector2 devicePixelRatio() const { return _devicePixelRatio; }
 
+        /**
+         * @brief Set window title
+         *
+         * The @p title is expected to be encoded in UTF-8.
+         */
+        void setWindowTitle(const std::string& title);
+
         /**
          * @brief Set container CSS class
          *
@@ -920,8 +927,10 @@ class EmscriptenApplication::Configuration {
          * @return Reference to self (for method chaining)
          *
          * @note This function does nothing and is included only for
-         *      compatibility with other toolkits. You need to set the title
-         *      separately in the HTML markup.
+         *      compatibility with other toolkits, as the page title is
+         *      expected to be set by the HTML markup. However, it's possible
+         *      to change the page title later (for example in response to
+         *      application state change) using @ref setWindowTitle().
          */
         template<class T> Configuration& setTitle(const T&) { return *this; }
 

src/Magnum/Platform/GlfwApplication.cpp

@@ -214,6 +214,10 @@ Vector2 GlfwApplication::dpiScaling(const Configuration& configuration) const {
     #endif
 }
 
+void GlfwApplication::setWindowTitle(const std::string& title) {
+    glfwSetWindowTitle(_window, title.data());
+}
+
 bool GlfwApplication::tryCreate(const Configuration& configuration) {
     #ifdef MAGNUM_TARGET_GL
     #ifdef GLFW_NO_API

src/Magnum/Platform/GlfwApplication.h

@@ -406,6 +406,13 @@ class GlfwApplication {
          */
         Vector2 dpiScaling(const Configuration& configuration) const;
 
+        /**
+         * @brief Set window title
+         *
+         * The @p title is expected to be encoded in UTF-8.
+         */
+        void setWindowTitle(const std::string& title);
+
         /**
          * @brief Swap buffers
          *

src/Magnum/Platform/Sdl2Application.cpp

@@ -264,6 +264,16 @@ Vector2 Sdl2Application::dpiScaling(const Configuration& configuration) const {
     #endif
 }
 
+void Sdl2Application::setWindowTitle(const std::string& title) {
+    #ifndef CORRADE_TARGET_EMSCRIPTEN
+    SDL_SetWindowTitle(_window, title.data());
+    #else
+    /* We don't have the _window because SDL_CreateWindow() doesn't exist in
+       the SDL1/2 hybrid. But it's not used anyway, so pass nullptr there. */
+    SDL_SetWindowTitle(nullptr, title.data());
+    #endif
+}
+
 bool Sdl2Application::tryCreate(const Configuration& configuration) {
     #ifdef MAGNUM_TARGET_GL
     if(!(configuration.windowFlags() & Configuration::WindowFlag::Contextless))

src/Magnum/Platform/Sdl2Application.h

@@ -690,6 +690,13 @@ class Sdl2Application {
          */
         Vector2 dpiScaling(const Configuration& configuration) const;
 
+        /**
+         * @brief Set window title
+         *
+         * The @p title is expected to be encoded in UTF-8.
+         */
+        void setWindowTitle(const std::string& title);
+
         #if defined(CORRADE_TARGET_EMSCRIPTEN) || defined(DOXYGEN_GENERATING_OUTPUT)
         /**
          * @brief Set container CSS class
@@ -1496,10 +1503,14 @@ class Sdl2Application::Configuration {
          * @return Reference to self (for method chaining)
          *
          * Default is @cpp "Magnum SDL2 Application" @ce.
-         * @note In @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" and
-         *      @ref CORRADE_TARGET_IOS "iOS" this function does nothing and is
-         *      included only for compatibility. You need to set the title
-         *      separately in platform-specific configuration file.
+         * @note On @ref CORRADE_TARGET_IOS "iOS" this function does nothing
+         *      and is included only for compatibility. You need to set the
+         *      title separately in platform-specific configuration file.
+         * @note Similarly, on @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" this
+         *      function is only for compatibility, as the page title is
+         *      expected to be set by the HTML markup. However, it's possible
+         *      to change the page title later (for example in response to
+         *      application state change) using @ref setWindowTitle().
          */
         #if !defined(CORRADE_TARGET_EMSCRIPTEN) && !defined(CORRADE_TARGET_IOS)
         Configuration& setTitle(std::string title) {

src/Magnum/Platform/Test/EmscriptenApplicationTest.cpp

@@ -113,6 +113,9 @@ struct EmscriptenApplicationTest: Platform::Application {
         } else if(event.key() == KeyEvent::Key::F) {
             Debug{} << "toggling fullscreen";
             setContainerCssClass((_fullscreen ^= true) ? "fullsize" : "");
+        } else if(event.key() == KeyEvent::Key::T) {
+            Debug{} << "setting window title";
+            setWindowTitle("This is a UTF-8 Window Title™!");
         }
 
         event.setAccepted();

src/Magnum/Platform/Test/GlfwApplicationTest.cpp

@@ -54,6 +54,9 @@ struct GlfwApplicationTest: Platform::Application {
         } else if(event.key() == KeyEvent::Key::Esc) {
             Debug{} << "stopping text input";
             stopTextInput();
+        } else if(event.key() == KeyEvent::Key::T) {
+            Debug{} << "setting window title";
+            setWindowTitle("This is a UTF-8 Window Title™!");
         }
     }
 

src/Magnum/Platform/Test/Sdl2ApplicationTest.cpp

@@ -79,6 +79,9 @@ struct Sdl2ApplicationTest: Platform::Application {
         } else if(event.key() == KeyEvent::Key::Esc) {
             Debug{} << "stopping text input";
             stopTextInput();
+        } else if(event.key() == KeyEvent::Key::T) {
+            Debug{} << "setting window title";
+            setWindowTitle("This is a UTF-8 Window Title™!");
         }
         #ifdef CORRADE_TARGET_EMSCRIPTEN
         else if(event.key() == KeyEvent::Key::F) {