Fixed broken back button behaviour on Android and updated JUCEApplicationBase::backButtonPressed() to return a bool indicating whether the back event has been handled or not to override this behaviour

BREAKING-CHANGES.txt

@@ -4,6 +4,29 @@ JUCE breaking changes
 Develop
 =======
 
+Change
+------
+The JUCEApplicationBase::backButtonPressed() method now returns a bool to
+indicate whether the back event was handled or not.
+
+Possible Issues
+---------------
+Applications which override this method will fail to compile.
+
+Workaround
+----------
+You will need to update your code to return a bool indicating whether the back
+event was handled or not.
+
+Rationale
+---------
+The back button behaviour on Android was previously broken as it would not do
+anything. The new code will correctly call finish() on the Activity when the
+back button is pressed but this method now allows the user to override this to
+implement their own custom navigation behaviour by returning true to indicate
+that it has been handled.
+
+
 Change
 ------
 The AudioBlock class has been refactored and some of the method names have

examples/DemoRunner/Source/Main.cpp

@@ -108,7 +108,7 @@ public:
         mainWindow.reset (new MainAppWindow (getApplicationName()));
     }
 
-    void backButtonPressed() override    { mainWindow->getMainComponent().getSidePanel().showOrHide (false); }
+    bool backButtonPressed() override    { mainWindow->getMainComponent().getSidePanel().showOrHide (false); return true; }
     void shutdown() override             { mainWindow = nullptr; }
 
     //==============================================================================

extras/AudioPluginHost/Source/HostStartup.cpp

@@ -126,10 +126,12 @@ public:
             JUCEApplicationBase::quit();
     }
 
-    void backButtonPressed() override
+    bool backButtonPressed() override
     {
         if (mainWindow->graphHolder != nullptr)
             mainWindow->graphHolder->hideLastSidePanel();
+
+        return true;
     }
 
     const String getApplicationName() override       { return "Juce Plug-In Host"; }

modules/juce_events/messages/juce_ApplicationBase.h

@@ -206,10 +206,17 @@ public:
     virtual void memoryWarningReceived()     { jassertfalse; }
 
     //==============================================================================
-    /** Override this method to be informed when the back button is pressed on a device.
+    /** This will be called when the back button on a device is pressed. The return value
+        should be used to indicate whether the back button event has been handled by
+        the application, for example if you want to implement custom navigation instead
+        of the standard behaviour on Android.
+
         This is currently only implemented on Android devices.
+
+        @returns  true if the event has been handled, or false if the default OS
+                  behaviour should happen
      */
-    virtual void backButtonPressed() {}
+    virtual bool backButtonPressed() { return false; }
 
     //==============================================================================
     /** Signals that the main message loop should stop and the application should terminate.

modules/juce_gui_basics/native/juce_android_Windowing.cpp

@@ -677,12 +677,29 @@ public:
 
     void handleBackButtonCallback()
     {
+        bool handled = false;
+
         if (auto* app = JUCEApplicationBase::getInstance())
-            app->backButtonPressed();
+            handled = app->backButtonPressed();
 
         if (Component* kiosk = Desktop::getInstance().getKioskModeComponent())
             if (kiosk->getPeer() == this)
                 setNavBarsHidden (navBarsHidden);
+
+        if (! handled)
+        {
+            auto* env = getEnv();
+            LocalRef<jobject> activity (getCurrentActivity());
+
+            if (activity != nullptr)
+            {
+                jmethodID finishMethod = env->GetMethodID (AndroidActivity, "finish", "()V");
+
+                if (finishMethod != nullptr)
+                    env->CallVoidMethod (activity.get(), finishMethod);
+            }
+        }
+
     }
 
     void handleKeyboardHiddenCallback()