From 26503041f7ba23738c715f81acadfc1200dfea68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 18 Jan 2022 11:52:44 +0100 Subject: [PATCH] Platform: test and document exit() behavior in {Glfw,Sdl2}Application. It doesn't fire an ExitEvent. --- src/Magnum/Platform/GlfwApplication.h | 25 +++++++++++-------- src/Magnum/Platform/Sdl2Application.h | 25 +++++++++++-------- .../Platform/Test/GlfwApplicationTest.cpp | 3 +++ .../Platform/Test/Sdl2ApplicationTest.cpp | 4 +++ 4 files changed, 37 insertions(+), 20 deletions(-) diff --git a/src/Magnum/Platform/GlfwApplication.h b/src/Magnum/Platform/GlfwApplication.h index e5941d99d..39979d8f7 100644 --- a/src/Magnum/Platform/GlfwApplication.h +++ b/src/Magnum/Platform/GlfwApplication.h @@ -271,18 +271,23 @@ class GlfwApplication { * @param exitCode The exit code the application should return * * When called from application constructor, it will cause the - * application to exit immediately after constructor ends, without any - * events being processed (thus not even @ref exitEvent()). Calling - * this function is recommended over @ref std::exit() or - * @ref Corrade::Utility::Fatal "Fatal", which exit without calling - * destructors on local scope. Note that, however, you need to - * explicitly @cpp return @ce after calling it, as it can't exit the - * constructor on its own: + * application to exit immediately after constructor ends, without + * entering the event loop. When called from within an event handler, + * it will cause it to exit at the start of next event loop iteration. + * Compared to requesting an application exit using the window close + * button or the @m_class{m-label m-default} **Alt** + * @m_class{m-label m-default} **F4** / + * @m_class{m-label m-default} **Cmd** + * @m_class{m-label m-default} **Q** keyboard shortcut, the + * @ref exitEvent() *isn't* called when using this function. + * + * Calling this function from an application constructor is recommended + * over @ref std::exit() or @ref Corrade::Utility::Fatal "Fatal", which + * exit without calling destructors on local scope. Note that, however, + * you need to explicitly @cpp return @ce after calling it, as it can't + * exit the constructor on its own: * * @snippet MagnumPlatform.cpp exit-from-constructor - * - * When called from the main loop, the application exits cleanly - * before next main loop iteration is executed. */ void exit(int exitCode = 0); diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index b4fdbe514..a797f09ef 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -579,18 +579,23 @@ class Sdl2Application { * @param exitCode The exit code the application should return * * When called from application constructor, it will cause the - * application to exit immediately after constructor ends, without any - * events being processed (thus not even @ref exitEvent()). Calling - * this function is recommended over @ref std::exit() or - * @ref Corrade::Utility::Fatal "Fatal", which exit without calling - * destructors on local scope. Note that, however, you need to - * explicitly @cpp return @ce after calling it, as it can't exit the - * constructor on its own: + * application to exit immediately after constructor ends, without + * entering the event loop. When called from within an event handler, + * it will cause it to exit at the start of next event loop iteration. + * Compared to requesting an application exit using the window close + * button or the @m_class{m-label m-default} **Alt** + * @m_class{m-label m-default} **F4** / + * @m_class{m-label m-default} **Cmd** + * @m_class{m-label m-default} **Q** keyboard shortcut, the + * @ref exitEvent() *isn't* called when using this function. + * + * Calling this function from an application constructor is recommended + * over @ref std::exit() or @ref Corrade::Utility::Fatal "Fatal", which + * exit without calling destructors on local scope. Note that, however, + * you need to explicitly @cpp return @ce after calling it, as it can't + * exit the constructor on its own: * * @snippet MagnumPlatform.cpp exit-from-constructor - * - * When called from the main loop, the application exits cleanly - * before next main loop iteration is executed. */ void exit(int exitCode = 0); diff --git a/src/Magnum/Platform/Test/GlfwApplicationTest.cpp b/src/Magnum/Platform/Test/GlfwApplicationTest.cpp index de10695bb..f2f8e4f8f 100644 --- a/src/Magnum/Platform/Test/GlfwApplicationTest.cpp +++ b/src/Magnum/Platform/Test/GlfwApplicationTest.cpp @@ -89,6 +89,9 @@ struct GlfwApplicationTest: Platform::Application { } else if(event.key() == KeyEvent::Key::L) { Debug{} << "toggling locked mouse"; setCursor(cursor() == Cursor::Arrow ? Cursor::HiddenLocked : Cursor::Arrow); + } else if(event.key() == KeyEvent::Key::X) { + Debug{} << "requesting an exit with code 5"; + exit(5); } } diff --git a/src/Magnum/Platform/Test/Sdl2ApplicationTest.cpp b/src/Magnum/Platform/Test/Sdl2ApplicationTest.cpp index edd714162..430e999a0 100644 --- a/src/Magnum/Platform/Test/Sdl2ApplicationTest.cpp +++ b/src/Magnum/Platform/Test/Sdl2ApplicationTest.cpp @@ -133,6 +133,10 @@ struct Sdl2ApplicationTest: Platform::Application { setContainerCssClass((_fullscreen ^= true) ? "mn-fullsize" : ""); } #endif + else if(event.key() == KeyEvent::Key::X) { + Debug{} << "requesting an exit with code 5"; + exit(5); + } } void textInputEvent(TextInputEvent& event) override {