1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxAppBase class and macros used for declaration of wxApp
4 // derived class in the user code
5 // Author: Julian Smart
9 // Copyright: (c) Julian Smart
10 // Licence: wxWindows licence
11 /////////////////////////////////////////////////////////////////////////////
13 #ifndef _WX_APP_H_BASE_
14 #define _WX_APP_H_BASE_
16 // ----------------------------------------------------------------------------
17 // headers we have to include here
18 // ----------------------------------------------------------------------------
20 #include "wx/event.h" // for the base class
23 #include "wx/window.h" // for wxTopLevelWindows
25 #include "wx/vidmode.h"
29 #include "wx/init.h" // we must declare wxEntry()
31 class WXDLLIMPEXP_BASE wxAppConsole
;
32 class WXDLLIMPEXP_BASE wxAppTraits
;
33 class WXDLLIMPEXP_BASE wxCmdLineParser
;
34 class WXDLLIMPEXP_BASE wxLog
;
35 class WXDLLIMPEXP_BASE wxMessageOutput
;
38 class WXDLLEXPORT wxEventLoop
;
41 // ----------------------------------------------------------------------------
43 // ----------------------------------------------------------------------------
45 // the type of the function used to create a wxApp object on program start up
46 typedef wxAppConsole
* (*wxAppInitializerFunction
)();
48 // ----------------------------------------------------------------------------
50 // ----------------------------------------------------------------------------
55 wxPRINT_POSTSCRIPT
= 2
58 // ----------------------------------------------------------------------------
59 // wxAppConsole: wxApp for non-GUI applications
60 // ----------------------------------------------------------------------------
62 class WXDLLIMPEXP_BASE wxAppConsole
: public wxEvtHandler
67 virtual ~wxAppConsole();
70 // the virtual functions which may/must be overridden in the derived class
71 // -----------------------------------------------------------------------
73 // This is the very first function called for a newly created wxApp object,
74 // it is used by the library to do the global initialization. If, for some
75 // reason, you must override it (instead of just overriding OnInit(), as
76 // usual, for app-specific initializations), do not forget to call the base
78 virtual bool Initialize(int& argc
, wxChar
**argv
);
80 // This gives wxCocoa a chance to call OnInit() with a memory pool in place
81 virtual bool CallOnInit() { return OnInit(); }
83 // Called before OnRun(), this is a good place to do initialization -- if
84 // anything fails, return false from here to prevent the program from
85 // continuing. The command line is normally parsed here, call the base
86 // class OnInit() to do it.
87 virtual bool OnInit();
89 // this is here only temporary hopefully (FIXME)
90 virtual bool OnInitGui() { return true; }
92 // This is the replacement for the normal main(): all program work should
93 // be done here. When OnRun() returns, the programs starts shutting down.
94 virtual int OnRun() = 0;
96 // This is only called if OnInit() returned true so it's a good place to do
97 // any cleanup matching the initializations done there.
100 // This is the very last function called on wxApp object before it is
101 // destroyed. If you override it (instead of overriding OnExit() as usual)
102 // do not forget to call the base class version!
103 virtual void CleanUp();
105 // Called when a fatal exception occurs, this function should take care not
106 // to do anything which might provoke a nested exception! It may be
107 // overridden if you wish to react somehow in non-default way (core dump
108 // under Unix, application crash under Windows) to fatal program errors,
109 // however extreme care should be taken if you don't want this function to
111 virtual void OnFatalException() { }
113 // Called from wxExit() function, should terminate the application a.s.a.p.
117 // application info: name, description, vendor
118 // -------------------------------------------
120 // NB: all these should be set by the application itself, there are no
121 // reasonable default except for the application name which is taken to
124 // set/get the application name
125 wxString
GetAppName() const
127 return m_appName
.empty() ? m_className
: m_appName
;
129 void SetAppName(const wxString
& name
) { m_appName
= name
; }
131 // set/get the app class name
132 wxString
GetClassName() const { return m_className
; }
133 void SetClassName(const wxString
& name
) { m_className
= name
; }
135 // set/get the vendor name
136 const wxString
& GetVendorName() const { return m_vendorName
; }
137 void SetVendorName(const wxString
& name
) { m_vendorName
= name
; }
140 // cmd line parsing stuff
141 // ----------------------
143 // all of these methods may be overridden in the derived class to
144 // customize the command line parsing (by default only a few standard
145 // options are handled)
147 // you also need to call wxApp::OnInit() from YourApp::OnInit() for all
150 #if wxUSE_CMDLINE_PARSER
151 // this one is called from OnInit() to add all supported options
152 // to the given parser (don't forget to call the base class version if you
154 virtual void OnInitCmdLine(wxCmdLineParser
& parser
);
156 // called after successfully parsing the command line, return true
157 // to continue and false to exit (don't forget to call the base class
158 // version if you override it!)
159 virtual bool OnCmdLineParsed(wxCmdLineParser
& parser
);
161 // called if "--help" option was specified, return true to continue
163 virtual bool OnCmdLineHelp(wxCmdLineParser
& parser
);
165 // called if incorrect command line options were given, return
166 // false to abort and true to continue
167 virtual bool OnCmdLineError(wxCmdLineParser
& parser
);
168 #endif // wxUSE_CMDLINE_PARSER
171 // miscellaneous customization functions
172 // -------------------------------------
174 // create the app traits object to which we delegate for everything which
175 // either should be configurable by the user (then he can change the
176 // default behaviour simply by overriding CreateTraits() and returning his
177 // own traits object) or which is GUI/console dependent as then wxAppTraits
178 // allows us to abstract the differences behind the common façade
179 wxAppTraits
*GetTraits();
181 // the functions below shouldn't be used now that we have wxAppTraits
182 #if WXWIN_COMPATIBILITY_2_4
185 // override this function to create default log target of arbitrary
186 // user-defined class (default implementation creates a wxLogGui
187 // object) -- this log object is used by default by all wxLogXXX()
189 wxDEPRECATED( virtual wxLog
*CreateLogTarget() );
192 // similar to CreateLogTarget() but for the global wxMessageOutput
194 wxDEPRECATED( virtual wxMessageOutput
*CreateMessageOutput() );
196 #endif // WXWIN_COMPATIBILITY_2_4
199 // event processing functions
200 // --------------------------
202 // this method allows to filter all the events processed by the program, so
203 // you should try to return quickly from it to avoid slowing down the
204 // program to the crawl
206 // return value should be -1 to continue with the normal event processing,
207 // or TRUE or FALSE to stop further processing and pretend that the event
208 // had been already processed or won't be processed at all, respectively
209 virtual int FilterEvent(wxEvent
& event
);
212 // call the specified handler on the given object with the given event
214 // this method only exists to allow catching the exceptions thrown by any
215 // event handler, it would lead to an extra (useless) virtual function call
216 // if the exceptions were not used, so it doesn't even exist in that case
217 virtual void HandleEvent(wxEvtHandler
*handler
,
218 wxEventFunction func
,
219 wxEvent
& event
) const;
221 // Called when an unhandled C++ exception occurs inside OnRun(): note that
222 // the exception type is lost by now, so if you really want to handle the
223 // exception you should override OnRun() and put a try/catch around
224 // MainLoop() call there or use OnExceptionInMainLoop()
225 virtual void OnUnhandledException() { }
226 #endif // wxUSE_EXCEPTIONS
228 // process all events in the wxPendingEvents list -- it is necessary to
229 // call this function to process posted events. This happens during each
230 // event loop iteration in GUI mode but if there is no main loop, it may be
231 // also called directly.
232 virtual void ProcessPendingEvents();
234 // doesn't do anything in this class, just a hook for GUI wxApp
235 virtual bool Yield(bool WXUNUSED(onlyIfNeeded
) = false) { return true; }
237 // make sure that idle events are sent again
238 virtual void WakeUpIdle() { }
240 // this is just a convenience: by providing its implementation here we
241 // avoid #ifdefs in the code using it
242 static bool IsMainLoopRunning() { return false; }
249 // this function is called when an assert failure occurs, the base class
250 // version does the normal processing (i.e. shows the usual assert failure
253 // the arguments are the location of the failed assert (func may be empty
254 // if the compiler doesn't support C99 __FUNCTION__), the text of the
255 // assert itself and the user-specified message
256 virtual void OnAssertFailure(const wxChar
*file
,
262 // old version of the function without func parameter, for compatibility
263 // only, override OnAssertFailure() in the new code
264 virtual void OnAssert(const wxChar
*file
,
268 #endif // __WXDEBUG__
270 // check that the wxBuildOptions object (constructed in the application
271 // itself, usually the one from IMPLEMENT_APP() macro) matches the build
272 // options of the library and abort if it doesn't
273 static bool CheckBuildOptions(const char *optionsSignature
,
274 const char *componentName
);
275 #if WXWIN_COMPATIBILITY_2_4
276 wxDEPRECATED( static bool CheckBuildOptions(const wxBuildOptions
& buildOptions
) );
279 // implementation only from now on
280 // -------------------------------
282 // helpers for dynamic wxApp construction
283 static void SetInitializerFunction(wxAppInitializerFunction fn
)
284 { ms_appInitFn
= fn
; }
285 static wxAppInitializerFunction
GetInitializerFunction()
286 { return ms_appInitFn
; }
288 // accessors for ms_appInstance field (external code might wish to modify
289 // it, this is why we provide a setter here as well, but you should really
290 // know what you're doing if you call it), wxTheApp is usually used instead
292 static wxAppConsole
*GetInstance() { return ms_appInstance
; }
293 static void SetInstance(wxAppConsole
*app
) { ms_appInstance
= app
; }
296 // command line arguments (public for backwards compatibility)
301 // the function which creates the traits object when GetTraits() needs it
302 // for the first time
303 virtual wxAppTraits
*CreateTraits();
306 // function used for dynamic wxApp creation
307 static wxAppInitializerFunction ms_appInitFn
;
309 // the one and only global application object
310 static wxAppConsole
*ms_appInstance
;
313 // application info (must be set from the user code)
314 wxString m_vendorName
, // vendor name (ACME Inc)
315 m_appName
, // app name
316 m_className
; // class name
318 // the class defining the application behaviour, NULL initially and created
319 // by GetTraits() when first needed
320 wxAppTraits
*m_traits
;
323 // the application object is a singleton anyhow, there is no sense in
325 DECLARE_NO_COPY_CLASS(wxAppConsole
)
328 // ----------------------------------------------------------------------------
329 // wxAppBase: the common part of wxApp implementations for all platforms
330 // ----------------------------------------------------------------------------
334 class WXDLLIMPEXP_CORE wxAppBase
: public wxAppConsole
338 virtual ~wxAppBase();
340 // the virtual functions which may/must be overridden in the derived class
341 // -----------------------------------------------------------------------
343 // very first initialization function
345 // Override: very rarely
346 virtual bool Initialize(int& argc
, wxChar
**argv
);
348 // a platform-dependent version of OnInit(): the code here is likely to
349 // depend on the toolkit. default version does nothing.
352 virtual bool OnInitGui();
354 // called to start program execution - the default version just enters
355 // the main GUI loop in which events are received and processed until
356 // the last window is not deleted (if GetExitOnFrameDelete) or
357 // ExitMainLoop() is called. In console mode programs, the execution
358 // of the program really starts here
360 // Override: rarely in GUI applications, always in console ones.
363 // a matching function for OnInit()
364 virtual int OnExit();
366 // very last clean up function
368 // Override: very rarely
369 virtual void CleanUp();
372 // the worker functions - usually not used directly by the user code
373 // -----------------------------------------------------------------
375 // return true if we're running main loop, i.e. if the events can
376 // (already) be dispatched
377 static bool IsMainLoopRunning()
379 wxAppBase
*app
= wx_static_cast(wxAppBase
*, GetInstance());
380 return app
&& app
->m_mainLoop
!= NULL
;
383 // execute the main GUI loop, the function returns when the loop ends
384 virtual int MainLoop();
386 // exit the main loop thus terminating the application
389 // exit the main GUI loop during the next iteration (i.e. it does not
390 // stop the program immediately!)
391 virtual void ExitMainLoop();
393 // returns true if there are unprocessed events in the event queue
394 virtual bool Pending();
396 // process the first event in the event queue (blocks until an event
397 // appears if there are none currently, use Pending() if this is not
398 // wanted), returns false if the event loop should stop and true
400 virtual bool Dispatch();
402 // process all currently pending events right now
404 // it is an error to call Yield() recursively unless the value of
405 // onlyIfNeeded is true
407 // WARNING: this function is dangerous as it can lead to unexpected
408 // reentrancies (i.e. when called from an event handler it
409 // may result in calling the same event handler again), use
410 // with _extreme_ care or, better, don't use at all!
411 virtual bool Yield(bool onlyIfNeeded
= false) = 0;
413 // this virtual function is called in the GUI mode when the application
414 // becomes idle and normally just sends wxIdleEvent to all interested
417 // it should return true if more idle events are needed, false if not
418 virtual bool ProcessIdle();
420 // Send idle event to window and all subwindows
421 // Returns true if more idle time is requested.
422 virtual bool SendIdleEvents(wxWindow
* win
, wxIdleEvent
& event
);
426 // Function called if an uncaught exception is caught inside the main
427 // event loop: it may return true to continue running the event loop or
428 // false to stop it (in the latter case it may rethrow the exception as
430 virtual bool OnExceptionInMainLoop();
431 #endif // wxUSE_EXCEPTIONS
434 // top level window functions
435 // --------------------------
437 // return true if our app has focus
438 virtual bool IsActive() const { return m_isActive
; }
440 // set the "main" top level window
441 void SetTopWindow(wxWindow
*win
) { m_topWindow
= win
; }
443 // return the "main" top level window (if it hadn't been set previously
444 // with SetTopWindow(), will return just some top level window and, if
445 // there are none, will return NULL)
446 virtual wxWindow
*GetTopWindow() const
450 else if (wxTopLevelWindows
.GetCount() > 0)
451 return wxTopLevelWindows
.GetFirst()->GetData();
453 return (wxWindow
*)NULL
;
456 // control the exit behaviour: by default, the program will exit the
457 // main loop (and so, usually, terminate) when the last top-level
458 // program window is deleted. Beware that if you disable this behaviour
459 // (with SetExitOnFrameDelete(false)), you'll have to call
460 // ExitMainLoop() explicitly from somewhere.
461 void SetExitOnFrameDelete(bool flag
)
462 { m_exitOnFrameDelete
= flag
? Yes
: No
; }
463 bool GetExitOnFrameDelete() const
464 { return m_exitOnFrameDelete
== Yes
; }
467 // display mode, visual, printing mode, ...
468 // ------------------------------------------------------------------------
470 // Get display mode that is used use. This is only used in framebuffer
471 // wxWin ports (such as wxMGL or wxDFB).
472 virtual wxVideoMode
GetDisplayMode() const { return wxVideoMode(); }
473 // Set display mode to use. This is only used in framebuffer wxWin
474 // ports (such as wxMGL or wxDFB). This method should be called from
476 virtual bool SetDisplayMode(const wxVideoMode
& WXUNUSED(info
)) { return true; }
478 // set use of best visual flag (see below)
479 void SetUseBestVisual( bool flag
) { m_useBestVisual
= flag
; }
480 bool GetUseBestVisual() const { return m_useBestVisual
; }
482 // set/get printing mode: see wxPRINT_XXX constants.
484 // default behaviour is the normal one for Unix: always use PostScript
486 virtual void SetPrintMode(int WXUNUSED(mode
)) { }
487 int GetPrintMode() const { return wxPRINT_POSTSCRIPT
; }
490 // command line parsing (GUI-specific)
491 // ------------------------------------------------------------------------
493 #if wxUSE_CMDLINE_PARSER
494 virtual bool OnCmdLineParsed(wxCmdLineParser
& parser
);
495 virtual void OnInitCmdLine(wxCmdLineParser
& parser
);
498 // miscellaneous other stuff
499 // ------------------------------------------------------------------------
501 // called by toolkit-specific code to set the app status: active (we have
502 // focus) or not and also the last window which had focus before we were
504 virtual void SetActive(bool isActive
, wxWindow
*lastFocus
);
506 #if WXWIN_COMPATIBILITY_2_6
507 // OBSOLETE: don't use, always returns true
509 // returns true if the program is successfully initialized
510 wxDEPRECATED( bool Initialized() );
511 #endif // WXWIN_COMPATIBILITY_2_6
513 // perform standard OnIdle behaviour, ensure that this is always called
514 void OnIdle(wxIdleEvent
& event
);
518 // delete all objects in wxPendingDelete list
519 void DeletePendingObjects();
521 // override base class method to use GUI traits
522 virtual wxAppTraits
*CreateTraits();
525 // the main event loop of the application (may be NULL if the loop hasn't
526 // been started yet or has already terminated)
527 wxEventLoop
*m_mainLoop
;
529 // the main top level window (may be NULL)
530 wxWindow
*m_topWindow
;
532 // if Yes, exit the main loop when the last top level window is deleted, if
533 // No don't do it and if Later -- only do it once we reach our OnRun()
535 // the explanation for using this strange scheme is given in appcmn.cpp
541 } m_exitOnFrameDelete
;
543 // true if the app wants to use the best visual on systems where
544 // more than one are available (Sun, SGI, XFree86 4.0 ?)
545 bool m_useBestVisual
;
547 // does any of our windows have focus?
551 DECLARE_NO_COPY_CLASS(wxAppBase
)
554 #if WXWIN_COMPATIBILITY_2_6
555 inline bool wxAppBase::Initialized() { return true; }
556 #endif // WXWIN_COMPATIBILITY_2_6
560 // ----------------------------------------------------------------------------
561 // now include the declaration of the real class
562 // ----------------------------------------------------------------------------
565 #if defined(__WXPALMOS__)
566 #include "wx/palmos/app.h"
567 #elif defined(__WXMSW__)
568 #include "wx/msw/app.h"
569 #elif defined(__WXMOTIF__)
570 #include "wx/motif/app.h"
571 #elif defined(__WXMGL__)
572 #include "wx/mgl/app.h"
573 #elif defined(__WXDFB__)
574 #include "wx/dfb/app.h"
575 #elif defined(__WXGTK20__)
576 #include "wx/gtk/app.h"
577 #elif defined(__WXGTK__)
578 #include "wx/gtk1/app.h"
579 #elif defined(__WXX11__)
580 #include "wx/x11/app.h"
581 #elif defined(__WXMAC__)
582 #include "wx/mac/app.h"
583 #elif defined(__WXCOCOA__)
584 #include "wx/cocoa/app.h"
585 #elif defined(__WXPM__)
586 #include "wx/os2/app.h"
589 // allow using just wxApp (instead of wxAppConsole) in console programs
590 typedef wxAppConsole wxApp
;
593 // ----------------------------------------------------------------------------
595 // ----------------------------------------------------------------------------
597 // for compatibility, we define this macro to access the global application
598 // object of type wxApp
600 // note that instead of using of wxTheApp in application code you should
601 // consider using DECLARE_APP() after which you may call wxGetApp() which will
602 // return the object of the correct type (i.e. MyApp and not wxApp)
604 // the cast is safe as in GUI build we only use wxApp, not wxAppConsole, and in
605 // console mode it does nothing at all
606 #define wxTheApp ((wxApp *)wxApp::GetInstance())
608 // ----------------------------------------------------------------------------
610 // ----------------------------------------------------------------------------
612 // event loop related functions only work in GUI programs
613 // ------------------------------------------------------
615 // Force an exit from main loop
616 extern void WXDLLIMPEXP_BASE
wxExit();
618 // Yield to other apps/messages
619 extern bool WXDLLIMPEXP_BASE
wxYield();
621 // Yield to other apps/messages
622 extern void WXDLLIMPEXP_BASE
wxWakeUpIdle();
624 // ----------------------------------------------------------------------------
625 // macros for dynamic creation of the application object
626 // ----------------------------------------------------------------------------
628 // Having a global instance of this class allows wxApp to be aware of the app
629 // creator function. wxApp can then call this function to create a new app
630 // object. Convoluted, but necessary.
632 class WXDLLIMPEXP_BASE wxAppInitializer
635 wxAppInitializer(wxAppInitializerFunction fn
)
636 { wxApp::SetInitializerFunction(fn
); }
639 // the code below defines a IMPLEMENT_WXWIN_MAIN macro which you can use if
640 // your compiler really, really wants main() to be in your main program (e.g.
641 // hello.cpp). Now IMPLEMENT_APP should add this code if required.
643 #define IMPLEMENT_WXWIN_MAIN_CONSOLE \
644 int main(int argc, char **argv) { return wxEntry(argc, argv); }
646 // port-specific header could have defined it already in some special way
647 #ifndef IMPLEMENT_WXWIN_MAIN
648 #define IMPLEMENT_WXWIN_MAIN IMPLEMENT_WXWIN_MAIN_CONSOLE
649 #endif // defined(IMPLEMENT_WXWIN_MAIN)
651 #ifdef __WXUNIVERSAL__
652 #include "wx/univ/theme.h"
654 #define IMPLEMENT_WX_THEME_SUPPORT \
655 WX_USE_THEME(win32); \
658 #define IMPLEMENT_WX_THEME_SUPPORT
661 // Use this macro if you want to define your own main() or WinMain() function
662 // and call wxEntry() from there.
663 #define IMPLEMENT_APP_NO_MAIN(appname) \
664 wxAppConsole *wxCreateApp() \
666 wxAppConsole::CheckBuildOptions(WX_BUILD_OPTIONS_SIGNATURE, \
668 return new appname; \
671 wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
672 DECLARE_APP(appname) \
673 appname& wxGetApp() { return *(appname *)wxTheApp; }
675 // Same as IMPLEMENT_APP() normally but doesn't include themes support in
676 // wxUniversal builds
677 #define IMPLEMENT_APP_NO_THEMES(appname) \
678 IMPLEMENT_APP_NO_MAIN(appname) \
681 // Use this macro exactly once, the argument is the name of the wxApp-derived
682 // class which is the class of your application.
683 #define IMPLEMENT_APP(appname) \
684 IMPLEMENT_APP_NO_THEMES(appname) \
685 IMPLEMENT_WX_THEME_SUPPORT
687 // Same as IMPLEMENT_APP(), but for console applications.
688 #define IMPLEMENT_APP_CONSOLE(appname) \
689 IMPLEMENT_APP_NO_MAIN(appname) \
690 IMPLEMENT_WXWIN_MAIN_CONSOLE
692 // this macro can be used multiple times and just allows you to use wxGetApp()
694 #define DECLARE_APP(appname) extern appname& wxGetApp();
697 // declare the stuff defined by IMPLEMENT_APP() macro, it's not really needed
698 // anywhere else but at the very least it suppresses icc warnings about
699 // defining extern symbols without prior declaration, and it shouldn't do any
701 extern wxAppConsole
*wxCreateApp();
702 extern wxAppInitializer wxTheAppInitializer
;
704 #endif // _WX_APP_H_BASE_