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