juce/source/src/application/juce_Application.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_APPLICATION_JUCEHEADER__
  27 #define __JUCE_APPLICATION_JUCEHEADER__
  28
  29 #include "juce_ApplicationCommandTarget.h"
  30 #include "../events/juce_ActionListener.h"
  31 #include "../threads/juce_InterProcessLock.h"
  32
  33
  34 //==============================================================================
  35 /**
  36     An instance of this class is used to specify initialisation and shutdown
  37     code for the application.
  38
  39     An application that wants to run in the JUCE framework needs to declare a
  40     subclass of JUCEApplication and implement its various pure virtual methods.
  41
  42     It then needs to use the START_JUCE_APPLICATION macro somewhere in a cpp file
  43     to declare an instance of this class and generate a suitable platform-specific
  44     main() function.
  45
  46     e.g. @code
  47         class MyJUCEApp  : public JUCEApplication
  48         {
  49         public:
  50             MyJUCEApp()
  51             {
  52             }
  53
  54             ~MyJUCEApp()
  55             {
  56             }
  57
  58             void initialise (const String& commandLine)
  59             {
  60                 myMainWindow = new MyApplicationWindow();
  61                 myMainWindow->setBounds (100, 100, 400, 500);
  62                 myMainWindow->setVisible (true);
  63             }
  64
  65             void shutdown()
  66             {
  67                 myMainWindow = 0;
  68             }
  69
  70             const String getApplicationName()
  71             {
  72                 return "Super JUCE-o-matic";
  73             }
  74
  75             const String getApplicationVersion()
  76             {
  77                 return "1.0";
  78             }
  79
  80         private:
  81             ScopedPointer <MyApplicationWindow> myMainWindow;
  82         };
  83
  84         // this creates wrapper code to actually launch the app properly.
  85         START_JUCE_APPLICATION (MyJUCEApp)
  86     @endcode
  87
  88     @see MessageManager
  89 */
  90 class JUCE_API  JUCEApplication  : public ApplicationCommandTarget
  91 {
  92 protected:
  93     //==============================================================================
  94     /** Constructs a JUCE app object.
  95
  96         If subclasses implement a constructor or destructor, they shouldn't call any
  97         JUCE code in there - put your startup/shutdown code in initialise() and
  98         shutdown() instead.
  99     */
 100     JUCEApplication();
 101
 102 public:
 103     /** Destructor.
 104
 105         If subclasses implement a constructor or destructor, they shouldn't call any
 106         JUCE code in there - put your startup/shutdown code in initialise() and
 107         shutdown() instead.
 108     */
 109     virtual ~JUCEApplication();
 110
 111     //==============================================================================
 112     /** Returns the global instance of the application object being run. */
 113     static JUCEApplication* getInstance() noexcept          { return appInstance; }
 114
 115     //==============================================================================
 116     /** Called when the application starts.
 117
 118         This will be called once to let the application do whatever initialisation
 119         it needs, create its windows, etc.
 120
 121         After the method returns, the normal event-dispatch loop will be run,
 122         until the quit() method is called, at which point the shutdown()
 123         method will be called to let the application clear up anything it needs
 124         to delete.
 125
 126         If during the initialise() method, the application decides not to start-up
 127         after all, it can just call the quit() method and the event loop won't be run.
 128
 129         @param commandLineParameters    the line passed in does not include the
 130                                         name of the executable, just the parameter list.
 131         @see shutdown, quit
 132     */
 133     virtual void initialise (const String& commandLineParameters) = 0;
 134
 135     /** Returns true if the application hasn't yet completed its initialise() method
 136         and entered the main event loop.
 137
 138         This is handy for things like splash screens to know when the app's up-and-running
 139         properly.
 140     */
 141     bool isInitialising() const noexcept                    { return stillInitialising; }
 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     //==============================================================================
 158     /** Returns the application's name.
 159
 160         An application must implement this to name itself.
 161     */
 162     virtual const String getApplicationName() = 0;
 163
 164     /** Returns the application's version number.
 165     */
 166     virtual const String getApplicationVersion() = 0;
 167
 168     /** Checks whether multiple instances of the app are allowed.
 169
 170         If you application class returns true for this, more than one instance is
 171         permitted to run (except on the Mac where this isn't possible).
 172
 173         If it's false, the second instance won't start, but it you will still get a
 174         callback to anotherInstanceStarted() to tell you about this - which
 175         gives you a chance to react to what the user was trying to do.
 176     */
 177     virtual bool moreThanOneInstanceAllowed();
 178
 179     /** Indicates that the user has tried to start up another instance of the app.
 180
 181         This will get called even if moreThanOneInstanceAllowed() is false.
 182     */
 183     virtual void anotherInstanceStarted (const String& commandLine);
 184
 185     /** Called when the operating system is trying to close the application.
 186
 187         The default implementation of this method is to call quit(), but it may
 188         be overloaded to ignore the request or do some other special behaviour
 189         instead. For example, you might want to offer the user the chance to save
 190         their changes before quitting, and give them the chance to cancel.
 191
 192         If you want to send a quit signal to your app, this is the correct method
 193         to call, because it means that requests that come from the system get handled
 194         in the same way as those from your own application code. So e.g. you'd
 195         call this method from a "quit" item on a menu bar.
 196     */
 197     virtual void systemRequestedQuit();
 198
 199     /** If any unhandled exceptions make it through to the message dispatch loop, this
 200         callback will be triggered, in case you want to log them or do some other
 201         type of error-handling.
 202
 203         If the type of exception is derived from the std::exception class, the pointer
 204         passed-in will be valid. If the exception is of unknown type, this pointer
 205         will be null.
 206     */
 207     virtual void unhandledException (const std::exception* e,
 208                                      const String& sourceFilename,
 209                                      int lineNumber);
 210
 211     //==============================================================================
 212     /** Signals that the main message loop should stop and the application should terminate.
 213
 214         This isn't synchronous, it just posts a quit message to the main queue, and
 215         when this message arrives, the message loop will stop, the shutdown() method
 216         will be called, and the app will exit.
 217
 218         Note that this will cause an unconditional quit to happen, so if you need an
 219         extra level before this, e.g. to give the user the chance to save their work
 220         and maybe cancel the quit, you'll need to handle this in the systemRequestedQuit()
 221         method - see that method's help for more info.
 222
 223         @see MessageManager
 224     */
 225     static void quit();
 226
 227     /** Sets the value that should be returned as the application's exit code when the
 228         app quits.
 229
 230         This is the value that's returned by the main() function. Normally you'd leave this
 231         as 0 unless you want to indicate an error code.
 232
 233         @see getApplicationReturnValue
 234     */
 235     void setApplicationReturnValue (int newReturnValue) noexcept;
 236
 237     /** Returns the value that has been set as the application's exit code.
 238         @see setApplicationReturnValue
 239     */
 240     int getApplicationReturnValue() const noexcept                  { return appReturnValue; }
 241
 242     /** Returns the application's command line parameters. */
 243     const String& getCommandLineParameters() const noexcept         { return commandLineParameters; }
 244
 245     /** Returns true if this executable is running as an app (as opposed to being a plugin
 246         or other kind of shared library. */
 247     static inline bool isStandaloneApp() noexcept                   { return createInstance != 0; }
 248
 249     //==============================================================================
 250     /** @internal */
 251     ApplicationCommandTarget* getNextCommandTarget();
 252     /** @internal */
 253     void getCommandInfo (CommandID commandID, ApplicationCommandInfo& result);
 254     /** @internal */
 255     void getAllCommands (Array <CommandID>& commands);
 256     /** @internal */
 257     bool perform (const InvocationInfo& info);
 258
 259     //==============================================================================
 260    #ifndef DOXYGEN
 261     // The following methods are internal calls - not for public use.
 262     static int main (const String& commandLine);
 263     static int main (int argc, const char* argv[]);
 264     static void sendUnhandledException (const std::exception* e, const char* sourceFile, int lineNumber);
 265     bool initialiseApp (const String& commandLine);
 266     int shutdownApp();
 267     static void appWillTerminateByForce();
 268     typedef JUCEApplication* (*CreateInstanceFunction)();
 269     static CreateInstanceFunction createInstance;
 270    #endif
 271
 272 private:
 273     //==============================================================================
 274     static JUCEApplication* appInstance;
 275
 276     String commandLineParameters;
 277     ScopedPointer<InterProcessLock> appLock;
 278     ScopedPointer<ActionListener> broadcastCallback;
 279     int appReturnValue;
 280     bool stillInitialising;
 281
 282     JUCE_DECLARE_NON_COPYABLE (JUCEApplication);
 283 };
 284
 285
 286 #endif   // __JUCE_APPLICATION_JUCEHEADER__