OpenShot Library | libopenshot-audio 0.2.0
juce_ApplicationBase.h
1
2/** @weakgroup juce_events-messages
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 Abstract base class for application classes.
33
34 Note that in the juce_gui_basics module, there's a utility class JUCEApplication
35 which derives from JUCEApplicationBase, and takes care of a few chores. Most
36 of the time you'll want to derive your class from JUCEApplication rather than
37 using JUCEApplicationBase directly, but if you're not using the juce_gui_basics
38 module then you might need to go straight to this base class.
39
40 Any application that wants to run an event loop must declare a subclass of
41 JUCEApplicationBase, and implement its various pure virtual methods.
42
43 It then needs to use the START_JUCE_APPLICATION macro somewhere in a CPP file
44 to declare an instance of this class and generate suitable platform-specific
45 boilerplate code to launch the app.
46
47 e.g. @code
48 class MyJUCEApp : public JUCEApplication
49 {
50 public:
51 MyJUCEApp() {}
52 ~MyJUCEApp() {}
53
54 void initialise (const String& commandLine) override
55 {
56 myMainWindow.reset (new MyApplicationWindow());
57 myMainWindow->setBounds (100, 100, 400, 500);
58 myMainWindow->setVisible (true);
59 }
60
61 void shutdown() override
62 {
63 myMainWindow = nullptr;
64 }
65
66 const String getApplicationName() override
67 {
68 return "Super JUCE-o-matic";
69 }
70
71 const String getApplicationVersion() override
72 {
73 return "1.0";
74 }
75
76 private:
77 std::unique_ptr<MyApplicationWindow> myMainWindow;
78 };
79
80 // this generates boilerplate code to launch our app class:
81 START_JUCE_APPLICATION (MyJUCEApp)
82 @endcode
83
84 @see JUCEApplication, START_JUCE_APPLICATION
85
86 @tags{Events}
87*/
89{
90protected:
91 //==============================================================================
93
94public:
95 /** Destructor. */
96 virtual ~JUCEApplicationBase();
97
98 //==============================================================================
99 /** Returns the global instance of the application object that's running. */
100 static JUCEApplicationBase* getInstance() noexcept { return appInstance; }
101
102 //==============================================================================
103 /** Returns the application's name. */
104 virtual const String getApplicationName() = 0;
105
106 /** Returns the application's version number. */
107 virtual const String getApplicationVersion() = 0;
108
109 /** Checks whether multiple instances of the app are allowed.
110
111 If your application class returns true for this, more than one instance is
112 permitted to run (except on the Mac where this isn't possible).
113
114 If it's false, the second instance won't start, but you will still get a
115 callback to anotherInstanceStarted() to tell you about this - which
116 gives you a chance to react to what the user was trying to do.
117
118 @see anotherInstanceStarted
119 */
120 virtual bool moreThanOneInstanceAllowed() = 0;
121
122 /** Called when the application starts.
123
124 This will be called once to let the application do whatever initialisation
125 it needs, create its windows, etc.
126
127 After the method returns, the normal event-dispatch loop will be run,
128 until the quit() method is called, at which point the shutdown()
129 method will be called to let the application clear up anything it needs
130 to delete.
131
132 If during the initialise() method, the application decides not to start-up
133 after all, it can just call the quit() method and the event loop won't be run.
134
135 @param commandLineParameters the line passed in does not include the name of
136 the executable, just the parameter list. To get the
137 parameters as an array, you can call
138 JUCEApplication::getCommandLineParameters()
139 @see shutdown, quit
140 */
141 virtual void initialise (const String& commandLineParameters) = 0;
142
143 /* Called to allow the application to clear up before exiting.
144
145 After JUCEApplication::quit() has been called, the event-dispatch loop will
146 terminate, and this method will get called to allow the app to sort itself
147 out.
148
149 Be careful that nothing happens in this method that might rely on messages
150 being sent, or any kind of window activity, because the message loop is no
151 longer running at this point.
152
153 @see DeletedAtShutdown
154 */
155 virtual void shutdown() = 0;
156
157 /** Indicates that the user has tried to start up another instance of the app.
158
159 This will get called even if moreThanOneInstanceAllowed() is false.
160 It is currently only implemented on Windows and Mac.
161
162 @see moreThanOneInstanceAllowed
163 */
164 virtual void anotherInstanceStarted (const String& commandLine) = 0;
165
166 /** Called when the operating system is trying to close the application.
167
168 The default implementation of this method is to call quit(), but it may
169 be overloaded to ignore the request or do some other special behaviour
170 instead. For example, you might want to offer the user the chance to save
171 their changes before quitting, and give them the chance to cancel.
172
173 If you want to send a quit signal to your app, this is the correct method
174 to call, because it means that requests that come from the system get handled
175 in the same way as those from your own application code. So e.g. you'd
176 call this method from a "quit" item on a menu bar.
177 */
178 virtual void systemRequestedQuit() = 0;
179
180 /** This method is called when the application is being put into background mode
181 by the operating system.
182 */
183 virtual void suspended() = 0;
184
185 /** This method is called when the application is being woken from background mode
186 by the operating system.
187 */
188 virtual void resumed() = 0;
189
190 /** If any unhandled exceptions make it through to the message dispatch loop, this
191 callback will be triggered, in case you want to log them or do some other
192 type of error-handling.
193
194 If the type of exception is derived from the std::exception class, the pointer
195 passed-in will be valid. If the exception is of unknown type, this pointer
196 will be null.
197 */
198 virtual void unhandledException (const std::exception*,
199 const String& sourceFilename,
200 int lineNumber) = 0;
201
202 /** Called by the operating system to indicate that you should reduce your memory
203 footprint.
204
205 You should override this method to free up some memory gracefully, if possible,
206 otherwise the host may forcibly kill your app.
207
208 At the moment this method is only called on iOS.
209 */
210 virtual void memoryWarningReceived() { jassertfalse; }
211
212 //==============================================================================
213 /** Override this method to be informed when the back button is pressed on a device.
214 This is currently only implemented on Android devices.
215 */
216 virtual void backButtonPressed() {}
217
218 //==============================================================================
219 /** Signals that the main message loop should stop and the application should terminate.
220
221 This isn't synchronous, it just posts a quit message to the main queue, and
222 when this message arrives, the message loop will stop, the shutdown() method
223 will be called, and the app will exit.
224
225 Note that this will cause an unconditional quit to happen, so if you need an
226 extra level before this, e.g. to give the user the chance to save their work
227 and maybe cancel the quit, you'll need to handle this in the systemRequestedQuit()
228 method - see that method's help for more info.
229
230 @see MessageManager
231 */
232 static void quit();
233
234 //==============================================================================
235 /** Returns the application's command line parameters as a set of strings.
236 @see getCommandLineParameters
237 */
238 static StringArray JUCE_CALLTYPE getCommandLineParameterArray();
239
240 /** Returns the application's command line parameters as a single string.
241 @see getCommandLineParameterArray
242 */
243 static String JUCE_CALLTYPE getCommandLineParameters();
244
245 //==============================================================================
246 /** Sets the value that should be returned as the application's exit code when the
247 app quits.
248
249 This is the value that's returned by the main() function. Normally you'd leave this
250 as 0 unless you want to indicate an error code.
251
252 @see getApplicationReturnValue
253 */
254 void setApplicationReturnValue (int newReturnValue) noexcept;
255
256 /** Returns the value that has been set as the application's exit code.
257 @see setApplicationReturnValue
258 */
259 int getApplicationReturnValue() const noexcept { return appReturnValue; }
260
261 //==============================================================================
262 /** Returns true if this executable is running as an app (as opposed to being a plugin
263 or other kind of shared library. */
264 static bool isStandaloneApp() noexcept { return createInstance != nullptr; }
265
266 /** Returns true if the application hasn't yet completed its initialise() method
267 and entered the main event loop.
268
269 This is handy for things like splash screens to know when the app's up-and-running
270 properly.
271 */
272 bool isInitialising() const noexcept { return stillInitialising; }
273
274
275 //==============================================================================
276 #ifndef DOXYGEN
277 // The following methods are for internal use only...
278 static int main();
279 static int main (int argc, const char* argv[]);
280
281 static void appWillTerminateByForce();
284
285 #if JUCE_IOS
286 static void* iOSCustomDelegate;
287 #endif
288
289 virtual bool initialiseApp();
290 int shutdownApp();
291 static void JUCE_CALLTYPE sendUnhandledException (const std::exception*, const char* sourceFile, int lineNumber);
293 #endif
294
295private:
296 //==============================================================================
297 static JUCEApplicationBase* appInstance;
298 int appReturnValue = 0;
299 bool stillInitialising = true;
300
301 struct MultipleInstanceHandler;
302 std::unique_ptr<MultipleInstanceHandler> multipleInstanceHandler;
303
304 JUCE_DECLARE_NON_COPYABLE (JUCEApplicationBase)
305};
306
307
308//==============================================================================
309#if JUCE_CATCH_UNHANDLED_EXCEPTIONS || defined (DOXYGEN)
310
311 /** The JUCE_TRY/JUCE_CATCH_EXCEPTION wrappers can be used to pass any uncaught exceptions to
312 the JUCEApplicationBase::sendUnhandledException() method.
313 This functionality can be enabled with the JUCE_CATCH_UNHANDLED_EXCEPTIONS macro.
314 */
315 #define JUCE_TRY try
316
317 /** The JUCE_TRY/JUCE_CATCH_EXCEPTION wrappers can be used to pass any uncaught exceptions to
318 the JUCEApplicationBase::sendUnhandledException() method.
319 This functionality can be enabled with the JUCE_CATCH_UNHANDLED_EXCEPTIONS macro.
320 */
321 #define JUCE_CATCH_EXCEPTION \
322 catch (const std::exception& e) { juce::JUCEApplicationBase::sendUnhandledException (&e, __FILE__, __LINE__); } \
323 catch (...) { juce::JUCEApplicationBase::sendUnhandledException (nullptr, __FILE__, __LINE__); }
324
325#else
326 #define JUCE_TRY
327 #define JUCE_CATCH_EXCEPTION
328#endif
329
330} // namespace juce
331
332/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
Abstract base class for application classes.
bool isInitialising() const noexcept
Returns true if the application hasn't yet completed its initialise() method and entered the main eve...
virtual void systemRequestedQuit()=0
Called when the operating system is trying to close the application.
virtual void initialise(const String &commandLineParameters)=0
Called when the application starts.
virtual const String getApplicationName()=0
Returns the application's name.
virtual void memoryWarningReceived()
Called by the operating system to indicate that you should reduce your memory footprint.
virtual void suspended()=0
This method is called when the application is being put into background mode by the operating system.
virtual void resumed()=0
This method is called when the application is being woken from background mode by the operating syste...
virtual void anotherInstanceStarted(const String &commandLine)=0
Indicates that the user has tried to start up another instance of the app.
static JUCEApplicationBase * getInstance() noexcept
Returns the global instance of the application object that's running.
virtual const String getApplicationVersion()=0
Returns the application's version number.
static bool isStandaloneApp() noexcept
Returns true if this executable is running as an app (as opposed to being a plugin or other kind of s...
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 trigg...
virtual bool moreThanOneInstanceAllowed()=0
Checks whether multiple instances of the app are allowed.
virtual void backButtonPressed()
Override this method to be informed when the back button is pressed on a device.
int getApplicationReturnValue() const noexcept
Returns the value that has been set as the application's exit code.
A special array for holding a list of strings.
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.