An instance of this class is used to specify initialisation and shutdown code for the application. More...

#include <juce_Application.h>

Inheritance diagram for juce::JUCEApplication:

Collaboration diagram for juce::JUCEApplication:

[legend]

Public Member Functions
	JUCEApplication ()
	Constructs a JUCE app object. More...

	~JUCEApplication () override
	Destructor. More...

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

virtual bool	backButtonPressed ()
	This will be called when the back button on a device is pressed. More...

ApplicationCommandTarget *	findFirstTargetParentComponent ()
	If this object is a Component, this method will search upwards in its current UI hierarchy for the next parent component that implements the ApplicationCommandTarget class. More...

void	getAllCommands (Array< CommandID > &) override

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...

void	getCommandInfo (CommandID, ApplicationCommandInfo &) override

ApplicationCommandTarget *	getNextCommandTarget () override

ApplicationCommandTarget *	getTargetForCommand (const CommandID commandID)
	Searches this target and all subsequent ones for the first one that can handle the specified command. More...

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

bool	invoke (const InvocationInfo &invocationInfo, const bool asynchronously)
	Makes this target invoke a command. More...

bool	invokeDirectly (const CommandID commandID, const bool asynchronously)
	Invokes a given command directly on this target. More...

bool	isCommandActive (const CommandID commandID)
	Checks whether this command can currently be performed by this target. 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 void	memoryWarningReceived ()
	Called by the operating system to indicate that you should reduce your memory footprint. More...

bool	moreThanOneInstanceAllowed () override
	Checks whether multiple instances of the app are allowed. More...

bool	perform (const InvocationInfo &) override

void	resumed () override
	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

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

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

void	unhandledException (const std::exception *e, const String &sourceFilename, int lineNumber) override
	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 JUCEApplication *	getInstance () noexcept
	Returns the global instance of the application object being run. 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...

Private Member Functions
bool	initialiseApp () override

bool	tryToInvoke (const InvocationInfo &, bool async)

Private Attributes
int	appReturnValue = 0

std::unique_ptr< MultipleInstanceHandler >	multipleInstanceHandler

bool	stillInitialising = true

Static Private Attributes
static JUCEApplicationBase *	appInstance

Detailed Description

An instance of this class is used to specify initialisation and shutdown code for the application.

Any application that wants to run an event loop must declare a subclass of JUCEApplicationBase or JUCEApplication, 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.

Note that this class is derived from JUCEApplicationBase, which contains most of the useful methods and functionality. This derived class is here simply as a convenient way to also inherit from an ApplicationCommandTarget, and to implement default versions of some of the pure virtual base class methods. But you can derive your app object directly from JUCEApplicationBase if you want to, and by doing so can avoid having a dependency on the juce_gui_basics module.

e.g.

class MyJUCEApp  : public JUCEApplication
{
public:
    MyJUCEApp()  {}
    ~MyJUCEApp() {}
 
    void initialise (const String& commandLine) override
    {
        myMainWindow.reset (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:
    std::unique_ptr<MyApplicationWindow> myMainWindow;
};
 
// this generates boilerplate code to launch our app class:
START_JUCE_APPLICATION (MyJUCEApp)

See also: JUCEApplicationBase, START_JUCE_APPLICATION

@tags{GUI}

Constructor & Destructor Documentation

◆ JUCEApplication()

juce::JUCEApplication::JUCEApplication ( )

Constructs a JUCE app object.

If subclasses implement a constructor or destructor, they shouldn't call any JUCE code in there - put your startup/shutdown code in initialise() and shutdown() instead.

◆ ~JUCEApplication()

juce::JUCEApplication::~JUCEApplication ( )

override

Destructor.

If subclasses implement a constructor or destructor, they shouldn't call any JUCE code in there - put your startup/shutdown code in initialise() and shutdown() instead.

Member Function Documentation

◆ anotherInstanceStarted()

void juce::JUCEApplication::anotherInstanceStarted ( const String & commandLine )

overridevirtual

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

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

Implements juce::JUCEApplicationBase.

◆ backButtonPressed()

virtual bool juce::JUCEApplicationBase::backButtonPressed ( )

inlinevirtualinherited

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

◆ findFirstTargetParentComponent()

ApplicationCommandTarget* juce::ApplicationCommandTarget::findFirstTargetParentComponent ( )

inherited

If this object is a Component, this method will search upwards in its current UI hierarchy for the next parent component that implements the ApplicationCommandTarget class.

If your target is a Component, this is a very handy method to use in your getNextCommandTarget() implementation.

◆ getAllCommands()

void juce::JUCEApplication::getAllCommands ( Array< CommandID > & )

overridevirtual

Implements juce::ApplicationCommandTarget.

◆ getApplicationName()

virtual const String juce::JUCEApplication::getApplicationName ( )

pure virtual

Returns the application's name.

Implements juce::JUCEApplicationBase.

◆ getApplicationReturnValue()

int juce::JUCEApplicationBase::getApplicationReturnValue ( ) const

inlinenoexceptinherited

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

See also: setApplicationReturnValue

◆ getApplicationVersion()

virtual const String juce::JUCEApplication::getApplicationVersion ( )

pure virtual

Returns the application's version number.

Implements juce::JUCEApplicationBase.

◆ getCommandInfo()

void juce::JUCEApplication::getCommandInfo	(	CommandID	,
		ApplicationCommandInfo &
	)

overridevirtual

Implements juce::ApplicationCommandTarget.

◆ getCommandLineParameterArray()

static StringArray juce::JUCEApplicationBase::getCommandLineParameterArray ( )

staticinherited

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

See also: getCommandLineParameters

◆ getCommandLineParameters()

static String juce::JUCEApplicationBase::getCommandLineParameters ( )

staticinherited

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

See also: getCommandLineParameterArray

◆ getInstance()

static JUCEApplication* juce::JUCEApplication::getInstance ( )

staticnoexcept

Returns the global instance of the application object being run.

◆ getNextCommandTarget()

ApplicationCommandTarget* juce::JUCEApplication::getNextCommandTarget ( )

overridevirtual

Implements juce::ApplicationCommandTarget.

◆ getTargetForCommand()

ApplicationCommandTarget* juce::ApplicationCommandTarget::getTargetForCommand ( const CommandID commandID )

inherited

Searches this target and all subsequent ones for the first one that can handle the specified command.

This will use getNextCommandTarget() to determine the chain of targets to try after this one.

◆ initialise()

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

pure virtualinherited

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

◆ initialiseApp()

bool juce::JUCEApplication::initialiseApp ( )

overrideprivate

◆ invoke()

bool juce::ApplicationCommandTarget::invoke	(	const InvocationInfo &	invocationInfo,
		const bool	asynchronously
	)

inherited

Makes this target invoke a command.

Your code can call this method to invoke a command on this target, but normally you'd call it indirectly via ApplicationCommandManager::invoke() or ApplicationCommandManager::invokeDirectly().

If this target can perform the given command, it will call its perform() method to do so. If not, then getNextCommandTarget() will be used to determine the next target to try, and the command will be passed along to it.

Parameters

invocationInfo	this must be correctly filled-in, describing the context for the invocation.
asynchronously	if false, the command will be performed before this method returns. If true, a message will be posted so that the command will be performed later on the message thread, and this method will return immediately.

See also: perform, ApplicationCommandManager::invoke

◆ invokeDirectly()

bool juce::ApplicationCommandTarget::invokeDirectly	(	const CommandID	commandID,
		const bool	asynchronously
	)

inherited

Invokes a given command directly on this target.

This is just an easy way to call invoke() without having to fill out the InvocationInfo structure.

◆ isCommandActive()

bool juce::ApplicationCommandTarget::isCommandActive ( const CommandID commandID )

inherited

Checks whether this command can currently be performed by this target.

This will return true only if a call to getCommandInfo() doesn't set the isDisabled flag to indicate that the command is inactive.

◆ isInitialising()

bool juce::JUCEApplicationBase::isInitialising ( ) const

inlinenoexceptinherited

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.

◆ isStandaloneApp()

static bool juce::JUCEApplicationBase::isStandaloneApp ( )

inlinestaticnoexceptinherited

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

◆ memoryWarningReceived()

virtual void juce::JUCEApplicationBase::memoryWarningReceived ( )

inlinevirtualinherited

Called by the operating system to indicate that you should reduce your memory footprint.

You should override this method to free up some memory gracefully, if possible, otherwise the host may forcibly kill your app.

At the moment this method is only called on iOS.

References jassertfalse.

◆ moreThanOneInstanceAllowed()

bool juce::JUCEApplication::moreThanOneInstanceAllowed ( )

overridevirtual

Checks whether multiple instances of the app are allowed.

If your application class returns true for this, more than one instance is permitted to run (except on OSX where the OS automatically stops you launching a second instance of an app without explicitly starting it from the command-line).

If it's false, the second instance won't start, but 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.

Implements juce::JUCEApplicationBase.

◆ perform()

bool juce::JUCEApplication::perform ( const InvocationInfo & )

overridevirtual

Implements juce::ApplicationCommandTarget.

◆ quit()

static void juce::JUCEApplicationBase::quit ( )

staticinherited

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 juce::StandaloneFilterWindow::closeButtonPressed().

◆ resumed()

void juce::JUCEApplication::resumed ( )

overridevirtual

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

Implements juce::JUCEApplicationBase.

◆ setApplicationReturnValue()

void juce::JUCEApplicationBase::setApplicationReturnValue ( int newReturnValue )

noexceptinherited

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 juce::JUCEApplicationBase::shutdown ( )

pure virtualinherited

◆ suspended()

void juce::JUCEApplication::suspended ( )

overridevirtual

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

Implements juce::JUCEApplicationBase.

◆ systemRequestedQuit()

void juce::JUCEApplication::systemRequestedQuit ( )

overridevirtual

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.

Implements juce::JUCEApplicationBase.

◆ tryToInvoke()

bool juce::ApplicationCommandTarget::tryToInvoke	(	const InvocationInfo &	,
		bool	async
	)

privateinherited

◆ unhandledException()

void juce::JUCEApplication::unhandledException	(	const std::exception *	e,
		const String &	sourceFilename,
		int	lineNumber
	)

overridevirtual

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.

Implements juce::JUCEApplicationBase.

Member Data Documentation

◆ appInstance

JUCEApplicationBase* juce::JUCEApplicationBase::appInstance

staticprivateinherited

◆ appReturnValue

int juce::JUCEApplicationBase::appReturnValue = 0

privateinherited

◆ multipleInstanceHandler

std::unique_ptr<MultipleInstanceHandler> juce::JUCEApplicationBase::multipleInstanceHandler

privateinherited

◆ stillInitialising

bool juce::JUCEApplicationBase::stillInitialising = true

privateinherited

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

juce_Application.h

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ JUCEApplication()

◆ ~JUCEApplication()

Member Function Documentation

◆ anotherInstanceStarted()

◆ backButtonPressed()

◆ findFirstTargetParentComponent()

◆ getAllCommands()

◆ getApplicationName()

◆ getApplicationReturnValue()

◆ getApplicationVersion()

◆ getCommandInfo()

◆ getCommandLineParameterArray()

◆ getCommandLineParameters()

◆ getInstance()

◆ getNextCommandTarget()

◆ getTargetForCommand()

◆ initialise()

◆ initialiseApp()

◆ invoke()

◆ invokeDirectly()

◆ isCommandActive()

◆ isInitialising()

◆ isStandaloneApp()

◆ memoryWarningReceived()

◆ moreThanOneInstanceAllowed()

◆ perform()

◆ quit()

◆ resumed()

◆ setApplicationReturnValue()

◆ shutdown()

◆ suspended()

◆ systemRequestedQuit()

◆ tryToInvoke()

◆ unhandledException()

Member Data Documentation

◆ appInstance

◆ appReturnValue

◆ multipleInstanceHandler

◆ stillInitialising