]>
Commit | Line | Data |
---|---|---|
c801d85f | 1 | ///////////////////////////////////////////////////////////////////////////// |
090a6d7a | 2 | // Name: wx/app.h |
094637f6 VZ |
3 | // Purpose: wxAppBase class and macros used for declaration of wxApp |
4 | // derived class in the user code | |
c801d85f KB |
5 | // Author: Julian Smart |
6 | // Modified by: | |
7 | // Created: 01/02/97 | |
8 | // RCS-ID: $Id$ | |
371a5b4e | 9 | // Copyright: (c) Julian Smart |
65571936 | 10 | // Licence: wxWindows licence |
c801d85f KB |
11 | ///////////////////////////////////////////////////////////////////////////// |
12 | ||
34138703 JS |
13 | #ifndef _WX_APP_H_BASE_ |
14 | #define _WX_APP_H_BASE_ | |
c801d85f | 15 | |
23280650 VZ |
16 | // ---------------------------------------------------------------------------- |
17 | // headers we have to include here | |
18 | // ---------------------------------------------------------------------------- | |
19 | ||
20 | #include "wx/event.h" // for the base class | |
090a6d7a | 21 | #include "wx/build.h" |
541ea80f | 22 | #include "wx/cmdargs.h" // for wxCmdLineArgsArray used by wxApp::argv |
0fcbaf23 | 23 | #include "wx/init.h" // we must declare wxEntry() |
5ff14574 | 24 | #include "wx/intl.h" // for wxLayoutDirection |
090a6d7a | 25 | |
b5dbe15d VS |
26 | class WXDLLIMPEXP_FWD_BASE wxAppConsole; |
27 | class WXDLLIMPEXP_FWD_BASE wxAppTraits; | |
28 | class WXDLLIMPEXP_FWD_BASE wxCmdLineParser; | |
29 | class WXDLLIMPEXP_FWD_BASE wxEventLoopBase; | |
30 | class WXDLLIMPEXP_FWD_BASE wxLog; | |
31 | class WXDLLIMPEXP_FWD_BASE wxMessageOutput; | |
a69be60b | 32 | |
4d90072c | 33 | #if wxUSE_GUI |
4ec80a59 | 34 | struct WXDLLIMPEXP_FWD_CORE wxVideoMode; |
d48b06bd | 35 | class WXDLLIMPEXP_FWD_CORE wxWindow; |
fb761cd5 | 36 | #endif |
1bf77ee5 | 37 | |
53c9228e VZ |
38 | // ---------------------------------------------------------------------------- |
39 | // typedefs | |
40 | // ---------------------------------------------------------------------------- | |
41 | ||
42 | // the type of the function used to create a wxApp object on program start up | |
e8e1149b | 43 | typedef wxAppConsole* (*wxAppInitializerFunction)(); |
53c9228e | 44 | |
094637f6 VZ |
45 | // ---------------------------------------------------------------------------- |
46 | // constants | |
47 | // ---------------------------------------------------------------------------- | |
48 | ||
e2478fde VZ |
49 | enum |
50 | { | |
51 | wxPRINT_WINDOWS = 1, | |
52 | wxPRINT_POSTSCRIPT = 2 | |
53 | }; | |
094637f6 VZ |
54 | |
55 | // ---------------------------------------------------------------------------- | |
e0954e72 | 56 | // wxAppConsoleBase: wxApp for non-GUI applications |
094637f6 VZ |
57 | // ---------------------------------------------------------------------------- |
58 | ||
e0954e72 | 59 | class WXDLLIMPEXP_BASE wxAppConsoleBase : public wxEvtHandler |
094637f6 VZ |
60 | { |
61 | public: | |
e2478fde | 62 | // ctor and dtor |
e0954e72 VZ |
63 | wxAppConsoleBase(); |
64 | virtual ~wxAppConsoleBase(); | |
e2478fde | 65 | |
1e6feb95 | 66 | |
094637f6 VZ |
67 | // the virtual functions which may/must be overridden in the derived class |
68 | // ----------------------------------------------------------------------- | |
bf188f1a | 69 | |
94826170 VZ |
70 | // This is the very first function called for a newly created wxApp object, |
71 | // it is used by the library to do the global initialization. If, for some | |
72 | // reason, you must override it (instead of just overriding OnInit(), as | |
73 | // usual, for app-specific initializations), do not forget to call the base | |
74 | // class version! | |
05e2b077 | 75 | virtual bool Initialize(int& argc, wxChar **argv); |
94826170 | 76 | |
7fbc89bb DE |
77 | // This gives wxCocoa a chance to call OnInit() with a memory pool in place |
78 | virtual bool CallOnInit() { return OnInit(); } | |
79 | ||
e2478fde VZ |
80 | // Called before OnRun(), this is a good place to do initialization -- if |
81 | // anything fails, return false from here to prevent the program from | |
82 | // continuing. The command line is normally parsed here, call the base | |
83 | // class OnInit() to do it. | |
bf188f1a | 84 | virtual bool OnInit(); |
094637f6 | 85 | |
e2478fde VZ |
86 | // This is the replacement for the normal main(): all program work should |
87 | // be done here. When OnRun() returns, the programs starts shutting down. | |
b46b1d59 | 88 | virtual int OnRun(); |
094637f6 | 89 | |
ec38d07d FM |
90 | // This is called by wxEventLoopBase::SetActive(): you should put the code |
91 | // which needs an active event loop here. | |
92 | // Note that this function is called whenever an event loop is activated; | |
93 | // you may want to use wxEventLoopBase::IsMain() to perform initialization | |
94 | // specific for the app's main event loop. | |
95 | virtual void OnEventLoopEnter(wxEventLoopBase* WXUNUSED(loop)) {} | |
96 | ||
e2478fde VZ |
97 | // This is only called if OnInit() returned true so it's a good place to do |
98 | // any cleanup matching the initializations done there. | |
7beba2fc | 99 | virtual int OnExit(); |
094637f6 | 100 | |
ec38d07d FM |
101 | // This is called by wxEventLoopBase::OnExit() for each event loop which |
102 | // is exited. | |
103 | virtual void OnEventLoopExit(wxEventLoopBase* WXUNUSED(loop)) {} | |
104 | ||
94826170 VZ |
105 | // This is the very last function called on wxApp object before it is |
106 | // destroyed. If you override it (instead of overriding OnExit() as usual) | |
107 | // do not forget to call the base class version! | |
108 | virtual void CleanUp(); | |
109 | ||
e2478fde VZ |
110 | // Called when a fatal exception occurs, this function should take care not |
111 | // to do anything which might provoke a nested exception! It may be | |
112 | // overridden if you wish to react somehow in non-default way (core dump | |
113 | // under Unix, application crash under Windows) to fatal program errors, | |
114 | // however extreme care should be taken if you don't want this function to | |
115 | // crash. | |
094637f6 VZ |
116 | virtual void OnFatalException() { } |
117 | ||
e2478fde VZ |
118 | // Called from wxExit() function, should terminate the application a.s.a.p. |
119 | virtual void Exit(); | |
b137e493 | 120 | |
094637f6 VZ |
121 | |
122 | // application info: name, description, vendor | |
123 | // ------------------------------------------- | |
124 | ||
125 | // NB: all these should be set by the application itself, there are no | |
126 | // reasonable default except for the application name which is taken to | |
127 | // be argv[0] | |
128 | ||
129 | // set/get the application name | |
130 | wxString GetAppName() const | |
131 | { | |
e2478fde | 132 | return m_appName.empty() ? m_className : m_appName; |
094637f6 VZ |
133 | } |
134 | void SetAppName(const wxString& name) { m_appName = name; } | |
135 | ||
9cf3d218 VZ |
136 | // set/get the application display name: the display name is the name |
137 | // shown to the user in titles, reports, etc while the app name is | |
138 | // used for paths, config, and other places the user doesn't see | |
139 | // | |
140 | // so the app name could be myapp while display name could be "My App" | |
141 | wxString GetAppDisplayName() const | |
142 | { | |
328fafa1 VZ |
143 | return m_appDisplayName.empty() ? GetAppName().Capitalize() |
144 | : m_appDisplayName; | |
9cf3d218 | 145 | } |
328fafa1 | 146 | |
9cf3d218 VZ |
147 | void SetAppDisplayName(const wxString& name) { m_appDisplayName = name; } |
148 | ||
094637f6 VZ |
149 | // set/get the app class name |
150 | wxString GetClassName() const { return m_className; } | |
151 | void SetClassName(const wxString& name) { m_className = name; } | |
152 | ||
153 | // set/get the vendor name | |
154 | const wxString& GetVendorName() const { return m_vendorName; } | |
155 | void SetVendorName(const wxString& name) { m_vendorName = name; } | |
156 | ||
180b5b48 VZ |
157 | // set/get the vendor display name: the display name is shown |
158 | // in titles/reports/dialogs to the user, while the vendor name | |
159 | // is used in some areas such as wxConfig, wxStandardPaths, etc | |
160 | const wxString& GetVendorDisplayName() const | |
161 | { | |
162 | return m_vendorDisplayName.empty() ? GetVendorName() | |
163 | : m_vendorDisplayName; | |
164 | } | |
165 | void SetVendorDisplayName(const wxString& name) | |
166 | { | |
167 | m_vendorDisplayName = name; | |
168 | } | |
169 | ||
e90c1d2a | 170 | |
bf188f1a VZ |
171 | // cmd line parsing stuff |
172 | // ---------------------- | |
173 | ||
174 | // all of these methods may be overridden in the derived class to | |
175 | // customize the command line parsing (by default only a few standard | |
176 | // options are handled) | |
177 | // | |
178 | // you also need to call wxApp::OnInit() from YourApp::OnInit() for all | |
179 | // this to work | |
180 | ||
181 | #if wxUSE_CMDLINE_PARSER | |
182 | // this one is called from OnInit() to add all supported options | |
b913d3ed VZ |
183 | // to the given parser (don't forget to call the base class version if you |
184 | // override it!) | |
bf188f1a VZ |
185 | virtual void OnInitCmdLine(wxCmdLineParser& parser); |
186 | ||
4629016d WS |
187 | // called after successfully parsing the command line, return true |
188 | // to continue and false to exit (don't forget to call the base class | |
b913d3ed | 189 | // version if you override it!) |
bf188f1a VZ |
190 | virtual bool OnCmdLineParsed(wxCmdLineParser& parser); |
191 | ||
4629016d WS |
192 | // called if "--help" option was specified, return true to continue |
193 | // and false to exit | |
bf188f1a VZ |
194 | virtual bool OnCmdLineHelp(wxCmdLineParser& parser); |
195 | ||
196 | // called if incorrect command line options were given, return | |
4629016d | 197 | // false to abort and true to continue |
bf188f1a VZ |
198 | virtual bool OnCmdLineError(wxCmdLineParser& parser); |
199 | #endif // wxUSE_CMDLINE_PARSER | |
200 | ||
e2478fde | 201 | |
094637f6 VZ |
202 | // miscellaneous customization functions |
203 | // ------------------------------------- | |
204 | ||
e2478fde VZ |
205 | // create the app traits object to which we delegate for everything which |
206 | // either should be configurable by the user (then he can change the | |
207 | // default behaviour simply by overriding CreateTraits() and returning his | |
208 | // own traits object) or which is GUI/console dependent as then wxAppTraits | |
9d55bfef | 209 | // allows us to abstract the differences behind the common facade |
e2478fde VZ |
210 | wxAppTraits *GetTraits(); |
211 | ||
96b2cbe8 VZ |
212 | // this function provides safer access to traits object than |
213 | // wxTheApp->GetTraits() during startup or termination when the global | |
214 | // application object itself may be unavailable | |
215 | // | |
216 | // of course, it still returns NULL in this case and the caller must check | |
217 | // for it | |
218 | static wxAppTraits *GetTraitsIfExists(); | |
75acb532 | 219 | |
ec38d07d FM |
220 | // returns the main event loop instance, i.e. the event loop which is started |
221 | // by OnRun() and which dispatches all events sent from the native toolkit | |
222 | // to the application (except when new event loops are temporarily set-up). | |
223 | // The returned value maybe NULL. Put initialization code which needs a | |
224 | // non-NULL main event loop into OnEventLoopEnter(). | |
225 | wxEventLoopBase* GetMainLoop() const | |
226 | { return m_mainLoop; } | |
227 | ||
228 | ||
e2478fde VZ |
229 | // event processing functions |
230 | // -------------------------- | |
094637f6 | 231 | |
9154d8cf VZ |
232 | // this method allows to filter all the events processed by the program, so |
233 | // you should try to return quickly from it to avoid slowing down the | |
234 | // program to the crawl | |
235 | // | |
236 | // return value should be -1 to continue with the normal event processing, | |
237 | // or TRUE or FALSE to stop further processing and pretend that the event | |
238 | // had been already processed or won't be processed at all, respectively | |
239 | virtual int FilterEvent(wxEvent& event); | |
240 | ||
dde19c21 FM |
241 | // return true if we're running event loop, i.e. if the events can |
242 | // (already) be dispatched | |
243 | static bool IsMainLoopRunning(); | |
244 | ||
883117d1 | 245 | #if wxUSE_EXCEPTIONS |
3c778901 VZ |
246 | // execute the functor to handle the given event |
247 | // | |
248 | // this is a generalization of HandleEvent() below and the base class | |
249 | // implementation of CallEventHandler() still calls HandleEvent() for | |
250 | // compatibility for functors which are just wxEventFunctions (i.e. methods | |
251 | // of wxEvtHandler) | |
252 | virtual void CallEventHandler(wxEvtHandler *handler, | |
253 | wxEventFunctor& functor, | |
254 | wxEvent& event) const; | |
255 | ||
883117d1 VZ |
256 | // call the specified handler on the given object with the given event |
257 | // | |
258 | // this method only exists to allow catching the exceptions thrown by any | |
259 | // event handler, it would lead to an extra (useless) virtual function call | |
260 | // if the exceptions were not used, so it doesn't even exist in that case | |
261 | virtual void HandleEvent(wxEvtHandler *handler, | |
262 | wxEventFunction func, | |
263 | wxEvent& event) const; | |
2dc62891 VZ |
264 | |
265 | // Called when an unhandled C++ exception occurs inside OnRun(): note that | |
1663c655 VZ |
266 | // the main event loop has already terminated by now and the program will |
267 | // exit, if you need to really handle the exceptions you need to override | |
268 | // OnExceptionInMainLoop() | |
269 | virtual void OnUnhandledException(); | |
dde19c21 FM |
270 | |
271 | // Function called if an uncaught exception is caught inside the main | |
272 | // event loop: it may return true to continue running the event loop or | |
273 | // false to stop it (in the latter case it may rethrow the exception as | |
274 | // well) | |
275 | virtual bool OnExceptionInMainLoop(); | |
276 | ||
883117d1 VZ |
277 | #endif // wxUSE_EXCEPTIONS |
278 | ||
b46b1d59 | 279 | |
8e40ed85 FM |
280 | // pending events |
281 | // -------------- | |
282 | ||
283 | // IMPORTANT: all these methods conceptually belong to wxEventLoopBase | |
284 | // but for many reasons we need to allow queuing of events | |
285 | // even when there's no event loop (e.g. in wxApp::OnInit); | |
286 | // this feature is used e.g. to queue events on secondary threads | |
287 | // or in wxPython to use wx.CallAfter before the GUI is initialized | |
288 | ||
289 | // process all events in the m_handlersWithPendingEvents list -- it is necessary | |
290 | // to call this function to process posted events. This happens during each | |
291 | // event loop iteration in GUI mode but if there is no main loop, it may be | |
292 | // also called directly. | |
e2478fde | 293 | virtual void ProcessPendingEvents(); |
8e40ed85 FM |
294 | |
295 | // check if there are pending events on global pending event list | |
b46b1d59 VZ |
296 | bool HasPendingEvents() const; |
297 | ||
8e40ed85 FM |
298 | // temporary suspends processing of the pending events |
299 | void SuspendProcessingOfPendingEvents(); | |
300 | ||
301 | // resume processing of the pending events previously stopped because of a | |
302 | // call to SuspendProcessingOfPendingEvents() | |
303 | void ResumeProcessingOfPendingEvents(); | |
304 | ||
305 | // called by ~wxEvtHandler to (eventually) remove the handler from the list of | |
306 | // the handlers with pending events | |
307 | void RemovePendingEventHandler(wxEvtHandler* toRemove); | |
308 | ||
309 | // adds an event handler to the list of the handlers with pending events | |
310 | void AppendPendingEventHandler(wxEvtHandler* toAppend); | |
311 | ||
312 | // moves the event handler from the list of the handlers with pending events | |
313 | //to the list of the handlers with _delayed_ pending events | |
314 | void DelayPendingEventHandler(wxEvtHandler* toDelay); | |
315 | ||
316 | ||
317 | // wxEventLoop redirections | |
318 | // ------------------------ | |
319 | ||
dde19c21 FM |
320 | virtual bool Pending(); |
321 | virtual bool Dispatch(); | |
b46b1d59 | 322 | |
b46b1d59 | 323 | virtual int MainLoop(); |
b46b1d59 VZ |
324 | virtual void ExitMainLoop(); |
325 | ||
dde19c21 | 326 | bool Yield(bool onlyIfNeeded = false); |
e2478fde | 327 | |
dde19c21 | 328 | virtual void WakeUpIdle(); |
b46b1d59 VZ |
329 | virtual bool ProcessIdle(); |
330 | ||
d48b06bd | 331 | |
a5f1fd3e VZ |
332 | // debugging support |
333 | // ----------------- | |
334 | ||
3ec4a23f | 335 | #ifdef __WXDEBUG__ |
a5f1fd3e VZ |
336 | // this function is called when an assert failure occurs, the base class |
337 | // version does the normal processing (i.e. shows the usual assert failure | |
338 | // dialog box) | |
aad65f13 | 339 | // |
3ec4a23f VZ |
340 | // the arguments are the location of the failed assert (func may be empty |
341 | // if the compiler doesn't support C99 __FUNCTION__), the text of the | |
aad65f13 | 342 | // assert itself and the user-specified message |
3ec4a23f VZ |
343 | virtual void OnAssertFailure(const wxChar *file, |
344 | int line, | |
345 | const wxChar *func, | |
346 | const wxChar *cond, | |
347 | const wxChar *msg); | |
348 | ||
349 | // old version of the function without func parameter, for compatibility | |
350 | // only, override OnAssertFailure() in the new code | |
aad65f13 VZ |
351 | virtual void OnAssert(const wxChar *file, |
352 | int line, | |
353 | const wxChar *cond, | |
354 | const wxChar *msg); | |
a5f1fd3e | 355 | #endif // __WXDEBUG__ |
8030d606 | 356 | |
090a6d7a VZ |
357 | // check that the wxBuildOptions object (constructed in the application |
358 | // itself, usually the one from IMPLEMENT_APP() macro) matches the build | |
359 | // options of the library and abort if it doesn't | |
2a7c7605 VS |
360 | static bool CheckBuildOptions(const char *optionsSignature, |
361 | const char *componentName); | |
73deed44 | 362 | |
094637f6 VZ |
363 | // implementation only from now on |
364 | // ------------------------------- | |
365 | ||
366 | // helpers for dynamic wxApp construction | |
367 | static void SetInitializerFunction(wxAppInitializerFunction fn) | |
e2478fde | 368 | { ms_appInitFn = fn; } |
094637f6 | 369 | static wxAppInitializerFunction GetInitializerFunction() |
e2478fde | 370 | { return ms_appInitFn; } |
094637f6 | 371 | |
a80e5f9e VZ |
372 | // accessors for ms_appInstance field (external code might wish to modify |
373 | // it, this is why we provide a setter here as well, but you should really | |
374 | // know what you're doing if you call it), wxTheApp is usually used instead | |
375 | // of GetInstance() | |
376 | static wxAppConsole *GetInstance() { return ms_appInstance; } | |
377 | static void SetInstance(wxAppConsole *app) { ms_appInstance = app; } | |
378 | ||
72cdf4c9 | 379 | |
e2478fde | 380 | // command line arguments (public for backwards compatibility) |
541ea80f VZ |
381 | int argc; |
382 | ||
383 | // this object is implicitly convertible to either "char**" (traditional | |
384 | // type of argv parameter of main()) or to "wchar_t **" (for compatibility | |
385 | // with Unicode build in previous wx versions and because the command line | |
386 | // can, in pr | |
387 | #if wxUSE_UNICODE | |
388 | wxCmdLineArgsArray argv; | |
389 | #else | |
390 | char **argv; | |
391 | #endif | |
094637f6 | 392 | |
094637f6 | 393 | protected: |
e2478fde VZ |
394 | // the function which creates the traits object when GetTraits() needs it |
395 | // for the first time | |
396 | virtual wxAppTraits *CreateTraits(); | |
397 | ||
094637f6 | 398 | // function used for dynamic wxApp creation |
e2478fde | 399 | static wxAppInitializerFunction ms_appInitFn; |
094637f6 | 400 | |
a80e5f9e VZ |
401 | // the one and only global application object |
402 | static wxAppConsole *ms_appInstance; | |
403 | ||
b46b1d59 VZ |
404 | // create main loop from AppTraits or return NULL if |
405 | // there is no main loop implementation | |
2ddff00c | 406 | wxEventLoopBase *CreateMainLoop(); |
7cafd224 | 407 | |
094637f6 | 408 | // application info (must be set from the user code) |
180b5b48 VZ |
409 | wxString m_vendorName, // vendor name ("acme") |
410 | m_vendorDisplayName, // vendor display name (e.g. "ACME Inc") | |
9cf3d218 VZ |
411 | m_appName, // app name ("myapp") |
412 | m_appDisplayName, // app display name ("My Application") | |
413 | m_className; // class name | |
a69be60b | 414 | |
e2478fde VZ |
415 | // the class defining the application behaviour, NULL initially and created |
416 | // by GetTraits() when first needed | |
417 | wxAppTraits *m_traits; | |
418 | ||
b46b1d59 VZ |
419 | // the main event loop of the application (may be NULL if the loop hasn't |
420 | // been started yet or has already terminated) | |
2ddff00c | 421 | wxEventLoopBase *m_mainLoop; |
e2478fde | 422 | |
8e40ed85 FM |
423 | // the array of the handlers with pending events which needs to be processed |
424 | // inside ProcessPendingEvents() | |
425 | wxEvtHandlerArray m_handlersWithPendingEvents; | |
426 | ||
427 | // helper array used by ProcessPendingEvents() | |
428 | wxEvtHandlerArray m_handlersWithPendingDelayedEvents; | |
429 | ||
430 | #if wxUSE_THREADS | |
431 | // this critical section protects both the lists above | |
432 | wxCriticalSection m_handlersWithPendingEventsLocker; | |
433 | #endif | |
434 | ||
e799e8d7 | 435 | friend class WXDLLIMPEXP_FWD_BASE wxEvtHandler; |
d48b06bd | 436 | |
e2478fde VZ |
437 | // the application object is a singleton anyhow, there is no sense in |
438 | // copying it | |
c0c133e1 | 439 | wxDECLARE_NO_COPY_CLASS(wxAppConsoleBase); |
e2478fde VZ |
440 | }; |
441 | ||
e0954e72 VZ |
442 | #if defined(__UNIX__) |
443 | #include "wx/unix/app.h" | |
444 | #else | |
4c2a8d89 VZ |
445 | // this has to be a class and not a typedef as we forward declare it |
446 | class wxAppConsole : public wxAppConsoleBase { }; | |
e0954e72 VZ |
447 | #endif |
448 | ||
e2478fde VZ |
449 | // ---------------------------------------------------------------------------- |
450 | // wxAppBase: the common part of wxApp implementations for all platforms | |
451 | // ---------------------------------------------------------------------------- | |
452 | ||
1e6feb95 | 453 | #if wxUSE_GUI |
e2478fde | 454 | |
bddd7a8d | 455 | class WXDLLIMPEXP_CORE wxAppBase : public wxAppConsole |
e2478fde VZ |
456 | { |
457 | public: | |
458 | wxAppBase(); | |
459 | virtual ~wxAppBase(); | |
460 | ||
461 | // the virtual functions which may/must be overridden in the derived class | |
462 | // ----------------------------------------------------------------------- | |
463 | ||
94826170 VZ |
464 | // very first initialization function |
465 | // | |
466 | // Override: very rarely | |
05e2b077 | 467 | virtual bool Initialize(int& argc, wxChar **argv); |
94826170 | 468 | |
e2478fde VZ |
469 | // a platform-dependent version of OnInit(): the code here is likely to |
470 | // depend on the toolkit. default version does nothing. | |
471 | // | |
472 | // Override: rarely. | |
473 | virtual bool OnInitGui(); | |
474 | ||
475 | // called to start program execution - the default version just enters | |
476 | // the main GUI loop in which events are received and processed until | |
477 | // the last window is not deleted (if GetExitOnFrameDelete) or | |
478 | // ExitMainLoop() is called. In console mode programs, the execution | |
479 | // of the program really starts here | |
480 | // | |
481 | // Override: rarely in GUI applications, always in console ones. | |
482 | virtual int OnRun(); | |
483 | ||
b913d3ed VZ |
484 | // a matching function for OnInit() |
485 | virtual int OnExit(); | |
486 | ||
94826170 VZ |
487 | // very last clean up function |
488 | // | |
489 | // Override: very rarely | |
490 | virtual void CleanUp(); | |
e2478fde VZ |
491 | |
492 | ||
493 | // the worker functions - usually not used directly by the user code | |
494 | // ----------------------------------------------------------------- | |
495 | ||
d48b06bd FM |
496 | // safer alternatives to Yield(), using wxWindowDisabler |
497 | virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded); | |
498 | virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess); | |
e2478fde VZ |
499 | |
500 | // this virtual function is called in the GUI mode when the application | |
501 | // becomes idle and normally just sends wxIdleEvent to all interested | |
502 | // parties | |
503 | // | |
4629016d | 504 | // it should return true if more idle events are needed, false if not |
1bf77ee5 | 505 | virtual bool ProcessIdle(); |
e39af974 | 506 | |
e39af974 | 507 | // Send idle event to window and all subwindows |
4629016d | 508 | // Returns true if more idle time is requested. |
5109ae5d | 509 | virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); |
e2478fde | 510 | |
2dc62891 | 511 | |
e2478fde VZ |
512 | // top level window functions |
513 | // -------------------------- | |
514 | ||
4629016d | 515 | // return true if our app has focus |
e2478fde VZ |
516 | virtual bool IsActive() const { return m_isActive; } |
517 | ||
518 | // set the "main" top level window | |
519 | void SetTopWindow(wxWindow *win) { m_topWindow = win; } | |
520 | ||
521 | // return the "main" top level window (if it hadn't been set previously | |
522 | // with SetTopWindow(), will return just some top level window and, if | |
523 | // there are none, will return NULL) | |
5ff14574 | 524 | virtual wxWindow *GetTopWindow() const; |
e2478fde VZ |
525 | |
526 | // control the exit behaviour: by default, the program will exit the | |
527 | // main loop (and so, usually, terminate) when the last top-level | |
528 | // program window is deleted. Beware that if you disable this behaviour | |
4629016d | 529 | // (with SetExitOnFrameDelete(false)), you'll have to call |
e2478fde VZ |
530 | // ExitMainLoop() explicitly from somewhere. |
531 | void SetExitOnFrameDelete(bool flag) | |
532 | { m_exitOnFrameDelete = flag ? Yes : No; } | |
533 | bool GetExitOnFrameDelete() const | |
534 | { return m_exitOnFrameDelete == Yes; } | |
535 | ||
536 | ||
537 | // display mode, visual, printing mode, ... | |
538 | // ------------------------------------------------------------------------ | |
539 | ||
540 | // Get display mode that is used use. This is only used in framebuffer | |
b3c86150 | 541 | // wxWin ports (such as wxMGL or wxDFB). |
5ff14574 | 542 | virtual wxVideoMode GetDisplayMode() const; |
e2478fde | 543 | // Set display mode to use. This is only used in framebuffer wxWin |
b3c86150 | 544 | // ports (such as wxMGL or wxDFB). This method should be called from |
e2478fde | 545 | // wxApp::OnInitGui |
4629016d | 546 | virtual bool SetDisplayMode(const wxVideoMode& WXUNUSED(info)) { return true; } |
e2478fde VZ |
547 | |
548 | // set use of best visual flag (see below) | |
9cf3d218 | 549 | void SetUseBestVisual( bool flag, bool forceTrueColour = false ) |
515a31bf | 550 | { m_useBestVisual = flag; m_forceTrueColour = forceTrueColour; } |
e2478fde VZ |
551 | bool GetUseBestVisual() const { return m_useBestVisual; } |
552 | ||
553 | // set/get printing mode: see wxPRINT_XXX constants. | |
554 | // | |
555 | // default behaviour is the normal one for Unix: always use PostScript | |
556 | // printing. | |
557 | virtual void SetPrintMode(int WXUNUSED(mode)) { } | |
558 | int GetPrintMode() const { return wxPRINT_POSTSCRIPT; } | |
559 | ||
475a93b7 VZ |
560 | // Return the layout direction for the current locale or wxLayout_Default |
561 | // if it's unknown | |
562 | virtual wxLayoutDirection GetLayoutDirection() const; | |
563 | ||
c50c6fb2 VZ |
564 | // Change the theme used by the application, return true on success. |
565 | virtual bool SetNativeTheme(const wxString& WXUNUSED(theme)) { return false; } | |
566 | ||
e2478fde | 567 | |
b913d3ed VZ |
568 | // command line parsing (GUI-specific) |
569 | // ------------------------------------------------------------------------ | |
570 | ||
8030d606 | 571 | #if wxUSE_CMDLINE_PARSER |
b913d3ed VZ |
572 | virtual bool OnCmdLineParsed(wxCmdLineParser& parser); |
573 | virtual void OnInitCmdLine(wxCmdLineParser& parser); | |
8030d606 | 574 | #endif |
b913d3ed | 575 | |
e2478fde VZ |
576 | // miscellaneous other stuff |
577 | // ------------------------------------------------------------------------ | |
578 | ||
579 | // called by toolkit-specific code to set the app status: active (we have | |
580 | // focus) or not and also the last window which had focus before we were | |
581 | // deactivated | |
582 | virtual void SetActive(bool isActive, wxWindow *lastFocus); | |
583 | ||
40ff126a | 584 | #if WXWIN_COMPATIBILITY_2_6 |
dd435a79 VZ |
585 | // OBSOLETE: don't use, always returns true |
586 | // | |
587 | // returns true if the program is successfully initialized | |
40ff126a WS |
588 | wxDEPRECATED( bool Initialized() ); |
589 | #endif // WXWIN_COMPATIBILITY_2_6 | |
dd435a79 | 590 | |
e2478fde | 591 | protected: |
94826170 VZ |
592 | // delete all objects in wxPendingDelete list |
593 | void DeletePendingObjects(); | |
594 | ||
e2478fde VZ |
595 | // override base class method to use GUI traits |
596 | virtual wxAppTraits *CreateTraits(); | |
597 | ||
598 | ||
599 | // the main top level window (may be NULL) | |
1e6feb95 VZ |
600 | wxWindow *m_topWindow; |
601 | ||
1cbee0b4 VZ |
602 | // if Yes, exit the main loop when the last top level window is deleted, if |
603 | // No don't do it and if Later -- only do it once we reach our OnRun() | |
604 | // | |
605 | // the explanation for using this strange scheme is given in appcmn.cpp | |
606 | enum | |
607 | { | |
608 | Later = -1, | |
609 | No, | |
610 | Yes | |
611 | } m_exitOnFrameDelete; | |
1e6feb95 | 612 | |
90e572f1 | 613 | // true if the app wants to use the best visual on systems where |
8480b297 RR |
614 | // more than one are available (Sun, SGI, XFree86 4.0 ?) |
615 | bool m_useBestVisual; | |
515a31bf RR |
616 | // force TrueColour just in case "best" isn't TrueColour |
617 | bool m_forceTrueColour; | |
094637f6 | 618 | |
90e572f1 | 619 | // does any of our windows have focus? |
1e6feb95 | 620 | bool m_isActive; |
e2478fde | 621 | |
c0c133e1 | 622 | wxDECLARE_NO_COPY_CLASS(wxAppBase); |
094637f6 VZ |
623 | }; |
624 | ||
40ff126a WS |
625 | #if WXWIN_COMPATIBILITY_2_6 |
626 | inline bool wxAppBase::Initialized() { return true; } | |
627 | #endif // WXWIN_COMPATIBILITY_2_6 | |
628 | ||
094637f6 VZ |
629 | // ---------------------------------------------------------------------------- |
630 | // now include the declaration of the real class | |
631 | // ---------------------------------------------------------------------------- | |
632 | ||
e0954e72 VZ |
633 | #if defined(__WXPALMOS__) |
634 | #include "wx/palmos/app.h" | |
635 | #elif defined(__WXMSW__) | |
636 | #include "wx/msw/app.h" | |
637 | #elif defined(__WXMOTIF__) | |
638 | #include "wx/motif/app.h" | |
639 | #elif defined(__WXMGL__) | |
640 | #include "wx/mgl/app.h" | |
641 | #elif defined(__WXDFB__) | |
642 | #include "wx/dfb/app.h" | |
643 | #elif defined(__WXGTK20__) | |
644 | #include "wx/gtk/app.h" | |
645 | #elif defined(__WXGTK__) | |
646 | #include "wx/gtk1/app.h" | |
647 | #elif defined(__WXX11__) | |
648 | #include "wx/x11/app.h" | |
649 | #elif defined(__WXMAC__) | |
ef0e9220 | 650 | #include "wx/osx/app.h" |
e0954e72 VZ |
651 | #elif defined(__WXCOCOA__) |
652 | #include "wx/cocoa/app.h" | |
653 | #elif defined(__WXPM__) | |
654 | #include "wx/os2/app.h" | |
655 | #endif | |
656 | ||
e90c1d2a | 657 | #else // !GUI |
e0954e72 VZ |
658 | |
659 | // wxApp is defined in core and we cannot define another one in wxBase, | |
660 | // so use the preprocessor to allow using wxApp in console programs too | |
661 | #define wxApp wxAppConsole | |
662 | ||
e90c1d2a | 663 | #endif // GUI/!GUI |
c801d85f | 664 | |
094637f6 | 665 | // ---------------------------------------------------------------------------- |
ee31c392 VZ |
666 | // the global data |
667 | // ---------------------------------------------------------------------------- | |
668 | ||
7cafd224 VZ |
669 | // for compatibility, we define this macro to access the global application |
670 | // object of type wxApp | |
671 | // | |
672 | // note that instead of using of wxTheApp in application code you should | |
673 | // consider using DECLARE_APP() after which you may call wxGetApp() which will | |
674 | // return the object of the correct type (i.e. MyApp and not wxApp) | |
675 | // | |
676 | // the cast is safe as in GUI build we only use wxApp, not wxAppConsole, and in | |
677 | // console mode it does nothing at all | |
5c33522f | 678 | #define wxTheApp static_cast<wxApp*>(wxApp::GetInstance()) |
ee31c392 VZ |
679 | |
680 | // ---------------------------------------------------------------------------- | |
681 | // global functions | |
682 | // ---------------------------------------------------------------------------- | |
683 | ||
e90c1d2a VZ |
684 | // event loop related functions only work in GUI programs |
685 | // ------------------------------------------------------ | |
686 | ||
ee31c392 | 687 | // Force an exit from main loop |
38281826 | 688 | WXDLLIMPEXP_BASE void wxExit(); |
ee31c392 | 689 | |
d48b06bd | 690 | // avoid redeclaring this function here if it had been already declared by |
a131b460 VZ |
691 | // wx/utils.h, this results in warnings from g++ with -Wredundant-decls |
692 | #ifndef wx_YIELD_DECLARED | |
693 | #define wx_YIELD_DECLARED | |
694 | ||
ee31c392 | 695 | // Yield to other apps/messages |
38281826 | 696 | WXDLLIMPEXP_CORE bool wxYield(); |
e90c1d2a | 697 | |
a131b460 VZ |
698 | #endif // wx_YIELD_DECLARED |
699 | ||
bf9e3e73 | 700 | // Yield to other apps/messages |
38281826 | 701 | WXDLLIMPEXP_BASE void wxWakeUpIdle(); |
bf9e3e73 | 702 | |
ee31c392 | 703 | // ---------------------------------------------------------------------------- |
094637f6 VZ |
704 | // macros for dynamic creation of the application object |
705 | // ---------------------------------------------------------------------------- | |
706 | ||
707 | // Having a global instance of this class allows wxApp to be aware of the app | |
708 | // creator function. wxApp can then call this function to create a new app | |
709 | // object. Convoluted, but necessary. | |
c801d85f | 710 | |
bddd7a8d | 711 | class WXDLLIMPEXP_BASE wxAppInitializer |
c801d85f KB |
712 | { |
713 | public: | |
094637f6 VZ |
714 | wxAppInitializer(wxAppInitializerFunction fn) |
715 | { wxApp::SetInitializerFunction(fn); } | |
c801d85f KB |
716 | }; |
717 | ||
956495ca VZ |
718 | // the code below defines a IMPLEMENT_WXWIN_MAIN macro which you can use if |
719 | // your compiler really, really wants main() to be in your main program (e.g. | |
720 | // hello.cpp). Now IMPLEMENT_APP should add this code if required. | |
26a87b69 | 721 | |
80b2db4e VS |
722 | #define IMPLEMENT_WXWIN_MAIN_CONSOLE \ |
723 | int main(int argc, char **argv) { return wxEntry(argc, argv); } | |
724 | ||
90e572f1 | 725 | // port-specific header could have defined it already in some special way |
956495ca | 726 | #ifndef IMPLEMENT_WXWIN_MAIN |
7738c2e5 | 727 | #define IMPLEMENT_WXWIN_MAIN IMPLEMENT_WXWIN_MAIN_CONSOLE |
956495ca | 728 | #endif // defined(IMPLEMENT_WXWIN_MAIN) |
26a87b69 | 729 | |
24e78d27 VZ |
730 | #ifdef __WXUNIVERSAL__ |
731 | #include "wx/univ/theme.h" | |
732 | ||
ee92941a VS |
733 | #ifdef wxUNIV_DEFAULT_THEME |
734 | #define IMPLEMENT_WX_THEME_SUPPORT \ | |
735 | WX_USE_THEME(wxUNIV_DEFAULT_THEME); | |
736 | #else | |
737 | #define IMPLEMENT_WX_THEME_SUPPORT | |
738 | #endif | |
24e78d27 VZ |
739 | #else |
740 | #define IMPLEMENT_WX_THEME_SUPPORT | |
741 | #endif | |
c801d85f | 742 | |
c661ecca RR |
743 | // Use this macro if you want to define your own main() or WinMain() function |
744 | // and call wxEntry() from there. | |
94826170 | 745 | #define IMPLEMENT_APP_NO_MAIN(appname) \ |
e8e1149b | 746 | wxAppConsole *wxCreateApp() \ |
94826170 | 747 | { \ |
2a7c7605 | 748 | wxAppConsole::CheckBuildOptions(WX_BUILD_OPTIONS_SIGNATURE, \ |
82c75aea | 749 | "your program"); \ |
94826170 VZ |
750 | return new appname; \ |
751 | } \ | |
752 | wxAppInitializer \ | |
753 | wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \ | |
17a1ebd1 | 754 | DECLARE_APP(appname) \ |
5c33522f | 755 | appname& wxGetApp() { return *static_cast<appname*>(wxApp::GetInstance()); } |
c661ecca | 756 | |
24e78d27 VZ |
757 | // Same as IMPLEMENT_APP() normally but doesn't include themes support in |
758 | // wxUniversal builds | |
759 | #define IMPLEMENT_APP_NO_THEMES(appname) \ | |
760 | IMPLEMENT_APP_NO_MAIN(appname) \ | |
761 | IMPLEMENT_WXWIN_MAIN | |
762 | ||
763 | // Use this macro exactly once, the argument is the name of the wxApp-derived | |
764 | // class which is the class of your application. | |
765 | #define IMPLEMENT_APP(appname) \ | |
766 | IMPLEMENT_APP_NO_THEMES(appname) \ | |
767 | IMPLEMENT_WX_THEME_SUPPORT | |
768 | ||
80b2db4e VS |
769 | // Same as IMPLEMENT_APP(), but for console applications. |
770 | #define IMPLEMENT_APP_CONSOLE(appname) \ | |
771 | IMPLEMENT_APP_NO_MAIN(appname) \ | |
772 | IMPLEMENT_WXWIN_MAIN_CONSOLE | |
773 | ||
24e78d27 VZ |
774 | // this macro can be used multiple times and just allows you to use wxGetApp() |
775 | // function | |
094637f6 | 776 | #define DECLARE_APP(appname) extern appname& wxGetApp(); |
c801d85f | 777 | |
17a1ebd1 VZ |
778 | |
779 | // declare the stuff defined by IMPLEMENT_APP() macro, it's not really needed | |
780 | // anywhere else but at the very least it suppresses icc warnings about | |
781 | // defining extern symbols without prior declaration, and it shouldn't do any | |
782 | // harm | |
783 | extern wxAppConsole *wxCreateApp(); | |
784 | extern wxAppInitializer wxTheAppInitializer; | |
785 | ||
94826170 | 786 | #endif // _WX_APP_H_BASE_ |