juce_ApplicationBase.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   The code included in this file is provided under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license. Permission
   To use, copy, modify, and/or distribute this software for any purpose with or
   without fee is hereby granted provided that the above copyright notice and
   this permission notice appear in all copies.
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  JUCEApplicationBase
{
protected:
    //==============================================================================
    JUCEApplicationBase();
 
public:
    virtual ~JUCEApplicationBase();
 
    //==============================================================================
    static JUCEApplicationBase* getInstance() noexcept          { return appInstance; }
 
    //==============================================================================
    virtual const String getApplicationName() = 0;

    virtual const String getApplicationVersion() = 0;

    virtual bool moreThanOneInstanceAllowed() = 0;

    virtual void initialise (const String& commandLineParameters) = 0;
 
    /* Called to allow the application to clear up before exiting.
 
       After JUCEApplication::quit() has been called, the event-dispatch loop will
       terminate, and this method will get called to allow the app to sort itself
       out.
 
       Be careful that nothing happens in this method that might rely on messages
       being sent, or any kind of window activity, because the message loop is no
       longer running at this point.
 
        @see DeletedAtShutdown
    */
    virtual void shutdown() = 0;

    virtual void anotherInstanceStarted (const String& commandLine) = 0;

    virtual void systemRequestedQuit() = 0;

    virtual void suspended() = 0;

    virtual void resumed() = 0;

    virtual void unhandledException (const std::exception*,
                                     const String& sourceFilename,
                                     int lineNumber) = 0;

    virtual void memoryWarningReceived()     { jassertfalse; }
 
    //==============================================================================
    virtual bool backButtonPressed() { return false; }
 
    //==============================================================================
    static void quit();
 
    //==============================================================================
    static StringArray JUCE_CALLTYPE getCommandLineParameterArray();

    static String JUCE_CALLTYPE getCommandLineParameters();
 
    //==============================================================================
    void setApplicationReturnValue (int newReturnValue) noexcept;

    int getApplicationReturnValue() const noexcept              { return appReturnValue; }
 
    //==============================================================================
    static bool isStandaloneApp() noexcept                      { return createInstance != nullptr; }

    bool isInitialising() const noexcept                        { return stillInitialising; }
 
 
    //==============================================================================
   #ifndef DOXYGEN
    // The following methods are for internal use only...
    static int main();
    static int main (int argc, const char* argv[]);
 
    static void appWillTerminateByForce();
    using CreateInstanceFunction = JUCEApplicationBase* (*)();
    static CreateInstanceFunction createInstance;
 
   #if JUCE_IOS
    static void* iOSCustomDelegate;
   #endif
 
    virtual bool initialiseApp();
    int shutdownApp();
    static void JUCE_CALLTYPE sendUnhandledException (const std::exception*, const char* sourceFile, int lineNumber);
    bool sendCommandLineToPreexistingInstance();
   #endif
 
private:
    //==============================================================================
    static JUCEApplicationBase* appInstance;
    int appReturnValue = 0;
    bool stillInitialising = true;
 
    struct MultipleInstanceHandler;
    std::unique_ptr<MultipleInstanceHandler> multipleInstanceHandler;
 
    JUCE_DECLARE_NON_COPYABLE (JUCEApplicationBase)
};
 
 
//==============================================================================
#if JUCE_CATCH_UNHANDLED_EXCEPTIONS || DOXYGEN

 #define JUCE_TRY try

 #define JUCE_CATCH_EXCEPTION \
    catch (const std::exception& e) { juce::JUCEApplicationBase::sendUnhandledException (&e,      __FILE__, __LINE__); } \
    catch (...)                     { juce::JUCEApplicationBase::sendUnhandledException (nullptr, __FILE__, __LINE__); }
 
#else
 #define JUCE_TRY
 #define JUCE_CATCH_EXCEPTION
#endif
 
} // namespace juce