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 
27 namespace 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 {
90 protected:
91  //==============================================================================
93 
94 public:
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();
282  using CreateInstanceFunction = JUCEApplicationBase* (*)();
283  static CreateInstanceFunction createInstance;
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);
292  bool sendCommandLineToPreexistingInstance();
293  #endif
294 
295 private:
296  //==============================================================================
297  static JUCEApplicationBase* appInstance;
298  int appReturnValue = 0;
299  bool stillInitialising = true;
300 
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 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
Abstract base class for application classes.
static JUCEApplicationBase * getInstance() noexcept
Returns the global instance of the application object that&#39;s running.
virtual void memoryWarningReceived()
Called by the operating system to indicate that you should reduce your memory footprint.
virtual void backButtonPressed()
Override this method to be informed when the back button is pressed on a device.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:42
int getApplicationReturnValue() const noexcept
Returns the value that has been set as the application&#39;s exit code.
bool isInitialising() const noexcept
Returns true if the application hasn&#39;t yet completed its initialise() method and entered the main eve...
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...