Abstract base class for application classes. More...

#include <juce_ApplicationBase.h>

Inheritance diagram for JUCEApplicationBase:

Collaboration diagram for JUCEApplicationBase:

Public Member Functions
virtual	~JUCEApplicationBase ()
	Destructor. More...

virtual void	anotherInstanceStarted (const String &commandLine)=0
	Indicates that the user has tried to start up another instance of the app. More...

virtual void	backButtonPressed ()
	Override this method to be informed when the back button is pressed on a device. More...

virtual const String	getApplicationName ()=0
	Returns the application's name. More...

int	getApplicationReturnValue () const noexcept
	Returns the value that has been set as the application's exit code. More...

virtual const String	getApplicationVersion ()=0
	Returns the application's version number. More...

virtual void	initialise (const String &commandLineParameters)=0
	Called when the application starts. More...

bool	isInitialising () const noexcept
	Returns true if the application hasn't yet completed its initialise() method and entered the main event loop. More...

virtual bool	moreThanOneInstanceAllowed ()=0
	Checks whether multiple instances of the app are allowed. More...

virtual void	resumed ()=0
	This method is called when the application is being woken from background mode by the operating system. More...

void	setApplicationReturnValue (int newReturnValue) noexcept
	Sets the value that should be returned as the application's exit code when the app quits. More...

virtual void	shutdown ()=0

virtual void	suspended ()=0
	This method is called when the application is being put into background mode by the operating system. More...

virtual void	systemRequestedQuit ()=0
	Called when the operating system is trying to close the application. More...

virtual void	unhandledException (const std::exception *, const String &sourceFilename, int lineNumber)=0
	If any unhandled exceptions make it through to the message dispatch loop, this callback will be triggered, in case you want to log them or do some other type of error-handling. More...

Static Public Member Functions
static StringArray	getCommandLineParameterArray ()
	Returns the application's command line parameters as a set of strings. More...

static String	getCommandLineParameters ()
	Returns the application's command line parameters as a single string. More...

static JUCEApplicationBase *	getInstance () noexcept
	Returns the global instance of the application object that's running. More...

static bool	isStandaloneApp () noexcept
	Returns true if this executable is running as an app (as opposed to being a plugin or other kind of shared library. More...

static void	quit ()
	Signals that the main message loop should stop and the application should terminate. More...

Protected Member Functions
	JUCEApplicationBase ()

Private Attributes
int	appReturnValue

ScopedPointer< MultipleInstanceHandler >	multipleInstanceHandler

bool	stillInitialising

Static Private Attributes
static JUCEApplicationBase *	appInstance

Friends
struct	ContainerDeletePolicy< MultipleInstanceHandler >

struct	MultipleInstanceHandler

Detailed Description

Abstract base class for application classes.

Note that in the juce_gui_basics module, there's a utility class JUCEApplication which derives from JUCEApplicationBase, and takes care of a few chores. Most of the time you'll want to derive your class from JUCEApplication rather than using JUCEApplicationBase directly, but if you're not using the juce_gui_basics module then you might need to go straight to this base class.

Any application that wants to run an event loop must declare a subclass of JUCEApplicationBase, and implement its various pure virtual methods.

It then needs to use the START_JUCE_APPLICATION macro somewhere in a CPP file to declare an instance of this class and generate suitable platform-specific boilerplate code to launch the app.

e.g.

class MyJUCEApp  : public JUCEApplication
{
public:
    MyJUCEApp()  {}
    ~MyJUCEApp() {}
    void initialise (const String& commandLine) override
    {
        myMainWindow = new MyApplicationWindow();
        myMainWindow->setBounds (100, 100, 400, 500);
        myMainWindow->setVisible (true);
    }
    void shutdown() override
    {
        myMainWindow = nullptr;
    }
    const String getApplicationName() override
    {
        return "Super JUCE-o-matic";
    }
    const String getApplicationVersion() override
    {
        return "1.0";
    }
private:
    ScopedPointer<MyApplicationWindow> myMainWindow;
};
// this generates boilerplate code to launch our app class:
START_JUCE_APPLICATION (MyJUCEApp)

See also: JUCEApplication, START_JUCE_APPLICATION

Constructor & Destructor Documentation

◆ JUCEApplicationBase()

JUCEApplicationBase::JUCEApplicationBase ( )

protected

◆ ~JUCEApplicationBase()

virtual JUCEApplicationBase::~JUCEApplicationBase ( )

virtual

Destructor.

Member Function Documentation

◆ anotherInstanceStarted()

virtual void JUCEApplicationBase::anotherInstanceStarted ( const String & commandLine )

pure virtual

Indicates that the user has tried to start up another instance of the app.

This will get called even if moreThanOneInstanceAllowed() is false.

Implemented in JUCEApplication.

◆ backButtonPressed()

virtual void JUCEApplicationBase::backButtonPressed ( )

inlinevirtual

Override this method to be informed when the back button is pressed on a device.

This is currently only implemented on Android devices.

References JUCE_CALLTYPE, and StandardApplicationCommandIDs::quit.

◆ getApplicationName()

virtual const String JUCEApplicationBase::getApplicationName ( )

pure virtual

Returns the application's name.

Implemented in JUCEApplication.

◆ getApplicationReturnValue()

int JUCEApplicationBase::getApplicationReturnValue ( ) const

inlinenoexcept

Returns the value that has been set as the application's exit code.

See also: setApplicationReturnValue

◆ getApplicationVersion()

virtual const String JUCEApplicationBase::getApplicationVersion ( )

pure virtual

Returns the application's version number.

Implemented in JUCEApplication.

◆ getCommandLineParameterArray()

static StringArray JUCEApplicationBase::getCommandLineParameterArray ( )

static

Returns the application's command line parameters as a set of strings.

See also: getCommandLineParameters

◆ getCommandLineParameters()

static String JUCEApplicationBase::getCommandLineParameters ( )

static

Returns the application's command line parameters as a single string.

See also: getCommandLineParameterArray

◆ getInstance()

static JUCEApplicationBase* JUCEApplicationBase::getInstance ( )

inlinestaticnoexcept

Returns the global instance of the application object that's running.

◆ initialise()

virtual void JUCEApplicationBase::initialise ( const String & commandLineParameters )

pure virtual

Called when the application starts.

This will be called once to let the application do whatever initialisation it needs, create its windows, etc.

After the method returns, the normal event-dispatch loop will be run, until the quit() method is called, at which point the shutdown() method will be called to let the application clear up anything it needs to delete.

If during the initialise() method, the application decides not to start-up after all, it can just call the quit() method and the event loop won't be run.

Parameters

commandLineParameters the line passed in does not include the name of the executable, just the parameter list. To get the parameters as an array, you can call JUCEApplication::getCommandLineParameters()

See also: shutdown, quit

◆ isInitialising()

bool JUCEApplicationBase::isInitialising ( ) const

inlinenoexcept

Returns true if the application hasn't yet completed its initialise() method and entered the main event loop.

This is handy for things like splash screens to know when the app's up-and-running properly.

References JUCE_CALLTYPE.

◆ isStandaloneApp()

static bool JUCEApplicationBase::isStandaloneApp ( )

inlinestaticnoexcept

Returns true if this executable is running as an app (as opposed to being a plugin or other kind of shared library.

◆ moreThanOneInstanceAllowed()

virtual bool JUCEApplicationBase::moreThanOneInstanceAllowed ( )

pure virtual

Checks whether multiple instances of the app are allowed.

If you application class returns true for this, more than one instance is permitted to run (except on the Mac where this isn't possible).

If it's false, the second instance won't start, but it you will still get a callback to anotherInstanceStarted() to tell you about this - which gives you a chance to react to what the user was trying to do.

Implemented in JUCEApplication.

◆ quit()

static void JUCEApplicationBase::quit ( )

static

Signals that the main message loop should stop and the application should terminate.

This isn't synchronous, it just posts a quit message to the main queue, and when this message arrives, the message loop will stop, the shutdown() method will be called, and the app will exit.

Note that this will cause an unconditional quit to happen, so if you need an extra level before this, e.g. to give the user the chance to save their work and maybe cancel the quit, you'll need to handle this in the systemRequestedQuit() method - see that method's help for more info.

See also: MessageManager

Referenced by StandaloneFilterWindow::closeButtonPressed().

◆ resumed()

virtual void JUCEApplicationBase::resumed ( )

pure virtual

This method is called when the application is being woken from background mode by the operating system.

Implemented in JUCEApplication.

◆ setApplicationReturnValue()

void JUCEApplicationBase::setApplicationReturnValue ( int newReturnValue )

noexcept

Sets the value that should be returned as the application's exit code when the app quits.

This is the value that's returned by the main() function. Normally you'd leave this as 0 unless you want to indicate an error code.

See also: getApplicationReturnValue

◆ shutdown()

virtual void JUCEApplicationBase::shutdown ( )

pure virtual

◆ suspended()

virtual void JUCEApplicationBase::suspended ( )

pure virtual

This method is called when the application is being put into background mode by the operating system.

Implemented in JUCEApplication.

◆ systemRequestedQuit()

virtual void JUCEApplicationBase::systemRequestedQuit ( )

pure virtual

Called when the operating system is trying to close the application.

The default implementation of this method is to call quit(), but it may be overloaded to ignore the request or do some other special behaviour instead. For example, you might want to offer the user the chance to save their changes before quitting, and give them the chance to cancel.

If you want to send a quit signal to your app, this is the correct method to call, because it means that requests that come from the system get handled in the same way as those from your own application code. So e.g. you'd call this method from a "quit" item on a menu bar.

Implemented in JUCEApplication.

◆ unhandledException()

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

pure virtual

If any unhandled exceptions make it through to the message dispatch loop, this callback will be triggered, in case you want to log them or do some other type of error-handling.

If the type of exception is derived from the std::exception class, the pointer passed-in will be valid. If the exception is of unknown type, this pointer will be null.

Implemented in JUCEApplication.

Friends And Related Function Documentation

◆ ContainerDeletePolicy< MultipleInstanceHandler >

friend struct ContainerDeletePolicy< MultipleInstanceHandler >

friend

◆ MultipleInstanceHandler

friend struct MultipleInstanceHandler

friend

Member Data Documentation

◆ appInstance

JUCEApplicationBase* JUCEApplicationBase::appInstance

staticprivate

◆ appReturnValue

int JUCEApplicationBase::appReturnValue

private

◆ multipleInstanceHandler

ScopedPointer<MultipleInstanceHandler> JUCEApplicationBase::multipleInstanceHandler

private

◆ stillInitialising

bool JUCEApplicationBase::stillInitialising

private

The documentation for this class was generated from the following file:

juce_ApplicationBase.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ JUCEApplicationBase()

◆ ~JUCEApplicationBase()

Member Function Documentation

◆ anotherInstanceStarted()

◆ backButtonPressed()

◆ getApplicationName()

◆ getApplicationReturnValue()

◆ getApplicationVersion()

◆ getCommandLineParameterArray()

◆ getCommandLineParameters()

◆ getInstance()

◆ initialise()

◆ isInitialising()

◆ isStandaloneApp()

◆ moreThanOneInstanceAllowed()

◆ quit()

◆ resumed()

◆ setApplicationReturnValue()

◆ shutdown()

◆ suspended()

◆ systemRequestedQuit()

◆ unhandledException()

Friends And Related Function Documentation

◆ ContainerDeletePolicy< MultipleInstanceHandler >

◆ MultipleInstanceHandler

Member Data Documentation

◆ appInstance

◆ appReturnValue

◆ multipleInstanceHandler

◆ stillInitialising