1 /* 2 ============================================================================== 3 4 This file is part of the JUCE library. 5 Copyright (c) 2020 - Raw Material Software Limited 6 7 JUCE is an open source library subject to commercial or open-source 8 licensing. 9 10 By using JUCE, you agree to the terms of both the JUCE 6 End-User License 11 Agreement and JUCE Privacy Policy (both effective as of the 16th June 2020). 12 13 End User License Agreement: www.juce.com/juce-6-licence 14 Privacy Policy: www.juce.com/juce-privacy-policy 15 16 Or: You may also use this code under the terms of the GPL v3 (see 17 www.gnu.org/licenses). 18 19 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER 20 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE 21 DISCLAIMED. 22 23 ============================================================================== 24 */ 25 26 namespace juce 27 { 28 29 //============================================================================== 30 /** 31 An instance of this class is used to specify initialisation and shutdown 32 code for the application. 33 34 Any application that wants to run an event loop must declare a subclass of 35 JUCEApplicationBase or JUCEApplication, and implement its various pure virtual 36 methods. 37 38 It then needs to use the START_JUCE_APPLICATION macro somewhere in a CPP file 39 to declare an instance of this class and generate suitable platform-specific 40 boilerplate code to launch the app. 41 42 Note that this class is derived from JUCEApplicationBase, which contains most 43 of the useful methods and functionality. This derived class is here simply as 44 a convenient way to also inherit from an ApplicationCommandTarget, and to implement 45 default versions of some of the pure virtual base class methods. But you can derive 46 your app object directly from JUCEApplicationBase if you want to, and by doing so 47 can avoid having a dependency on the juce_gui_basics module. 48 49 e.g. @code 50 class MyJUCEApp : public JUCEApplication 51 { 52 public: 53 MyJUCEApp() {} 54 ~MyJUCEApp() {} 55 56 void initialise (const String& commandLine) override 57 { 58 myMainWindow.reset (new MyApplicationWindow()); 59 myMainWindow->setBounds (100, 100, 400, 500); 60 myMainWindow->setVisible (true); 61 } 62 63 void shutdown() override 64 { 65 myMainWindow = nullptr; 66 } 67 68 const String getApplicationName() override 69 { 70 return "Super JUCE-o-matic"; 71 } 72 73 const String getApplicationVersion() override 74 { 75 return "1.0"; 76 } 77 78 private: 79 std::unique_ptr<MyApplicationWindow> myMainWindow; 80 }; 81 82 // this generates boilerplate code to launch our app class: 83 START_JUCE_APPLICATION (MyJUCEApp) 84 @endcode 85 86 @see JUCEApplicationBase, START_JUCE_APPLICATION 87 88 @tags{GUI} 89 */ 90 class JUCE_API JUCEApplication : public JUCEApplicationBase, 91 public ApplicationCommandTarget 92 { 93 public: 94 //============================================================================== 95 /** Constructs a JUCE app object. 96 97 If subclasses implement a constructor or destructor, they shouldn't call any 98 JUCE code in there - put your startup/shutdown code in initialise() and 99 shutdown() instead. 100 */ 101 JUCEApplication(); 102 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 ~JUCEApplication() override; 110 111 //============================================================================== 112 /** Returns the global instance of the application object being run. */ 113 static JUCEApplication* JUCE_CALLTYPE getInstance() noexcept; 114 115 //============================================================================== 116 #if DOXYGEN 117 /** Returns the application's name. */ 118 virtual const String getApplicationName() = 0; 119 120 /** Returns the application's version number. */ 121 virtual const String getApplicationVersion() = 0; 122 #endif 123 124 /** Checks whether multiple instances of the app are allowed. 125 126 If your application class returns true for this, more than one instance is 127 permitted to run (except on OSX where the OS automatically stops you launching 128 a second instance of an app without explicitly starting it from the command-line). 129 130 If it's false, the second instance won't start, but you will still get a 131 callback to anotherInstanceStarted() to tell you about this - which 132 gives you a chance to react to what the user was trying to do. 133 */ 134 bool moreThanOneInstanceAllowed() override; 135 136 /** Indicates that the user has tried to start up another instance of the app. 137 This will get called even if moreThanOneInstanceAllowed() is false. 138 */ 139 void anotherInstanceStarted (const String& commandLine) override; 140 141 /** Called when the operating system is trying to close the application. 142 143 The default implementation of this method is to call quit(), but it may 144 be overloaded to ignore the request or do some other special behaviour 145 instead. For example, you might want to offer the user the chance to save 146 their changes before quitting, and give them the chance to cancel. 147 148 If you want to send a quit signal to your app, this is the correct method 149 to call, because it means that requests that come from the system get handled 150 in the same way as those from your own application code. So e.g. you'd 151 call this method from a "quit" item on a menu bar. 152 */ 153 void systemRequestedQuit() override; 154 155 /** This method is called when the application is being put into background mode 156 by the operating system. 157 */ 158 void suspended() override; 159 160 /** This method is called when the application is being woken from background mode 161 by the operating system. 162 */ 163 void resumed() override; 164 165 /** If any unhandled exceptions make it through to the message dispatch loop, this 166 callback will be triggered, in case you want to log them or do some other 167 type of error-handling. 168 169 If the type of exception is derived from the std::exception class, the pointer 170 passed-in will be valid. If the exception is of unknown type, this pointer 171 will be null. 172 */ 173 void unhandledException (const std::exception* e, 174 const String& sourceFilename, 175 int lineNumber) override; 176 177 //============================================================================== 178 /** @internal */ 179 ApplicationCommandTarget* getNextCommandTarget() override; 180 /** @internal */ 181 void getCommandInfo (CommandID, ApplicationCommandInfo&) override; 182 /** @internal */ 183 void getAllCommands (Array<CommandID>&) override; 184 /** @internal */ 185 bool perform (const InvocationInfo&) override; 186 187 private: 188 bool initialiseApp() override; 189 190 JUCE_DECLARE_NON_COPYABLE (JUCEApplication) 191 }; 192 193 } // namespace juce 194