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 and Markus Holzem
10 // Licence: wxWindows licence
11 /////////////////////////////////////////////////////////////////////////////
13 #ifndef _WX_APP_H_BASE_
14 #define _WX_APP_H_BASE_
17 #pragma interface "appbase.h"
20 // ----------------------------------------------------------------------------
22 // ----------------------------------------------------------------------------
24 #if (defined(__WXMSW__) && !defined(__WXMICROWIN__)) || defined (__WXPM__)
25 class WXDLLEXPORT wxApp
;
26 typedef wxApp
* (*wxAppInitializerFunction
)();
28 // returning wxApp* won't work with gcc
29 #include "wx/object.h"
31 typedef wxObject
* (*wxAppInitializerFunction
)();
34 class WXDLLEXPORT wxCmdLineParser
;
36 // ----------------------------------------------------------------------------
37 // headers we have to include here
38 // ----------------------------------------------------------------------------
40 #include "wx/event.h" // for the base class
43 #include "wx/window.h" // for wxTopLevelWindows
50 #if WXWIN_COMPATIBILITY_2_2
56 // ----------------------------------------------------------------------------
58 // ----------------------------------------------------------------------------
60 static const int wxPRINT_WINDOWS
= 1;
61 static const int wxPRINT_POSTSCRIPT
= 2;
63 // ----------------------------------------------------------------------------
64 // support for framebuffer ports
65 // ----------------------------------------------------------------------------
68 // VS: Fullscreen/framebuffer application needs to choose display mode prior
69 // to wxWindows initialization. This class holds information about display
70 // mode. It is used by wxApp::Set/GetDisplayMode.
71 class WXDLLEXPORT wxDisplayModeInfo
74 wxDisplayModeInfo() : m_ok(FALSE
) {}
75 wxDisplayModeInfo(unsigned width
, unsigned height
, unsigned depth
)
76 : m_width(width
), m_height(height
), m_depth(depth
), m_ok(TRUE
) {}
78 unsigned GetWidth() const { return m_width
; }
79 unsigned GetHeight() const { return m_height
; }
80 unsigned GetDepth() const { return m_depth
; }
81 bool IsOk() const { return m_ok
; }
84 unsigned m_width
, m_height
, m_depth
;
89 // ----------------------------------------------------------------------------
90 // the common part of wxApp implementations for all platforms
91 // ----------------------------------------------------------------------------
93 class WXDLLEXPORT wxAppBase
: public wxEvtHandler
99 // the virtual functions which may/must be overridden in the derived class
100 // -----------------------------------------------------------------------
102 // called during the program initialization, returning FALSE from here
103 // prevents the program from continuing - it's a good place to create
104 // the top level program window and return TRUE.
106 // Override: always in GUI application, rarely in console ones.
107 virtual bool OnInit();
110 // a platform-dependent version of OnInit(): the code here is likely to
111 // depend on the toolkit. default version does nothing.
114 virtual bool OnInitGui();
117 // called to start program execution - the default version just enters
118 // the main GUI loop in which events are received and processed until
119 // the last window is not deleted (if GetExitOnFrameDelete) or
120 // ExitMainLoop() is called. In console mode programs, the execution
121 // of the program really starts here
123 // Override: rarely in GUI applications, always in console ones.
125 virtual int OnRun() { return MainLoop(); };
127 virtual int OnRun() = 0;
130 // called after the main loop termination. This is a good place for
131 // cleaning up (it may be too late in dtor) and is also useful if you
132 // want to return some non-default exit code - this is just the return
133 // value of this method.
136 virtual int OnExit();
138 // called when a fatal exception occurs, this function should take care
139 // not to do anything which might provoke a nested exception! It may be
140 // overridden if you wish to react somehow in non-default way (core
141 // dump under Unix, application crash under Windows) to fatal program
142 // errors, however extreme care should be taken if you don't want this
143 // function to crash.
146 virtual void OnFatalException() { }
148 // the worker functions - usually not used directly by the user code
149 // -----------------------------------------------------------------
152 // execute the main GUI loop, the function returns when the loop ends
153 virtual int MainLoop() = 0;
155 // exit the main GUI loop during the next iteration (i.e. it does not
156 // stop the program immediately!)
157 virtual void ExitMainLoop() = 0;
159 // returns TRUE if the program is initialized
160 virtual bool Initialized() = 0;
162 // returns TRUE if there are unprocessed events in the event queue
163 virtual bool Pending() = 0;
165 // process the first event in the event queue (blocks until an event
166 // apperas if there are none currently)
167 virtual void Dispatch() = 0;
169 // process all currently pending events right now
171 // it is an error to call Yield() recursively unless the value of
172 // onlyIfNeeded is TRUE
174 // WARNING: this function is dangerous as it can lead to unexpected
175 // reentrancies (i.e. when called from an event handler it
176 // may result in calling the same event handler again), use
177 // with _extreme_ care or, better, don't use at all!
178 virtual bool Yield(bool onlyIfNeeded
= FALSE
) = 0;
181 // application info: name, description, vendor
182 // -------------------------------------------
184 // NB: all these should be set by the application itself, there are no
185 // reasonable default except for the application name which is taken to
188 // set/get the application name
189 wxString
GetAppName() const
196 void SetAppName(const wxString
& name
) { m_appName
= name
; }
198 // set/get the app class name
199 wxString
GetClassName() const { return m_className
; }
200 void SetClassName(const wxString
& name
) { m_className
= name
; }
202 // set/get the vendor name
203 const wxString
& GetVendorName() const { return m_vendorName
; }
204 void SetVendorName(const wxString
& name
) { m_vendorName
= name
; }
207 // top level window functions
208 // --------------------------
210 // return TRUE if our app has focus
211 virtual bool IsActive() const { return m_isActive
; }
213 // set the "main" top level window
214 void SetTopWindow(wxWindow
*win
) { m_topWindow
= win
; }
216 // return the "main" top level window (if it hadn't been set previously
217 // with SetTopWindow(), will return just some top level window and, if
218 // there are none, will return NULL)
219 virtual wxWindow
*GetTopWindow() const
223 else if (wxTopLevelWindows
.GetCount() > 0)
224 return wxTopLevelWindows
.GetFirst()->GetData();
226 return (wxWindow
*)NULL
;
229 // control the exit behaviour: by default, the program will exit the
230 // main loop (and so, usually, terminate) when the last top-level
231 // program window is deleted. Beware that if you disabel this (with
232 // SetExitOnFrameDelete(FALSE)), you'll have to call ExitMainLoop()
233 // explicitly from somewhere.
234 void SetExitOnFrameDelete(bool flag
) { m_exitOnFrameDelete
= flag
; }
235 bool GetExitOnFrameDelete() const { return m_exitOnFrameDelete
; }
239 // cmd line parsing stuff
240 // ----------------------
242 // all of these methods may be overridden in the derived class to
243 // customize the command line parsing (by default only a few standard
244 // options are handled)
246 // you also need to call wxApp::OnInit() from YourApp::OnInit() for all
249 #if wxUSE_CMDLINE_PARSER
250 // this one is called from OnInit() to add all supported options
251 // to the given parser
252 virtual void OnInitCmdLine(wxCmdLineParser
& parser
);
254 // called after successfully parsing the command line, return TRUE
255 // to continue and FALSE to exit
256 virtual bool OnCmdLineParsed(wxCmdLineParser
& parser
);
258 // called if "--help" option was specified, return TRUE to continue
260 virtual bool OnCmdLineHelp(wxCmdLineParser
& parser
);
262 // called if incorrect command line options were given, return
263 // FALSE to abort and TRUE to continue
264 virtual bool OnCmdLineError(wxCmdLineParser
& parser
);
265 #endif // wxUSE_CMDLINE_PARSER
267 // miscellaneous customization functions
268 // -------------------------------------
271 // override this function to create default log target of arbitrary
272 // user-defined class (default implementation creates a wxLogGui
273 // object) - this log object is used by default by all wxLogXXX()
275 virtual wxLog
*CreateLogTarget()
276 #if wxUSE_GUI && wxUSE_LOGGUI && !defined(__WXMICROWIN__)
277 { return new wxLogGui
; }
279 { return new wxLogStderr
; }
285 #if WXWIN_COMPATIBILITY_2_2
286 // get the standard icon used by wxWin dialogs - this allows the user
287 // to customize the standard dialogs. The 'which' parameter is one of
289 virtual wxIcon
GetStdIcon(int WXUNUSED(which
)) const { return wxNullIcon
; }
292 // Get display mode that is used use. This is only used in framebuffer wxWin ports
294 virtual wxDisplayModeInfo
GetDisplayMode() const { return wxDisplayModeInfo(); }
295 // Set display mode to use. This is only used in framebuffer wxWin ports
296 // (such as wxMGL). This method should be called from wxApp:OnInitGui
297 virtual bool SetDisplayMode(const wxDisplayModeInfo
& WXUNUSED(info
)) { return TRUE
; }
299 // set use of best visual flag (see below)
300 void SetUseBestVisual( bool flag
) { m_useBestVisual
= flag
; }
301 bool GetUseBestVisual() const { return m_useBestVisual
; }
303 // set/get printing mode: see wxPRINT_XXX constants.
305 // default behaviour is the normal one for Unix: always use PostScript
307 virtual void SetPrintMode(int WXUNUSED(mode
)) { }
308 int GetPrintMode() const { return wxPRINT_POSTSCRIPT
; }
310 // called by toolkit-specific code to set the app status: active (we have
311 // focus) or not and also the last window which had focus before we were
313 virtual void SetActive(bool isActive
, wxWindow
*lastFocus
);
319 // this function is called when an assert failure occurs, the base class
320 // version does the normal processing (i.e. shows the usual assert failure
323 virtual void OnAssert(const wxChar
*file
, int line
, const wxChar
*msg
);
324 #endif // __WXDEBUG__
326 // check that the wxBuildOptions object (constructed in the application
327 // itself, usually the one from IMPLEMENT_APP() macro) matches the build
328 // options of the library and abort if it doesn't
329 static bool CheckBuildOptions(const wxBuildOptions
& buildOptions
);
331 // deprecated functions, please updae your code to not use them!
332 // -------------------------------------------------------------
334 #if WXWIN_COMPATIBILITY_2_2
335 // used by obsolete wxDebugMsg only
336 void SetWantDebugOutput( bool flag
) { m_wantDebugOutput
= flag
; }
337 bool GetWantDebugOutput() const { return m_wantDebugOutput
; }
339 // TRUE if the application wants to get debug output
340 bool m_wantDebugOutput
;
341 #endif // WXWIN_COMPATIBILITY_2_2
343 // implementation only from now on
344 // -------------------------------
346 // helpers for dynamic wxApp construction
347 static void SetInitializerFunction(wxAppInitializerFunction fn
)
348 { m_appInitFn
= fn
; }
349 static wxAppInitializerFunction
GetInitializerFunction()
350 { return m_appInitFn
; }
352 // process all events in the wxPendingEvents list
353 virtual void ProcessPendingEvents();
355 // access to the command line arguments
360 // function used for dynamic wxApp creation
361 static wxAppInitializerFunction m_appInitFn
;
363 // application info (must be set from the user code)
364 wxString m_vendorName
, // vendor name (ACME Inc)
365 m_appName
, // app name
366 m_className
; // class name
369 // the main top level window - may be NULL
370 wxWindow
*m_topWindow
;
372 // if TRUE, exit the main loop when the last top level window is deleted
373 bool m_exitOnFrameDelete
;
375 // TRUE if the apps whats to use the best visual on systems where
376 // more than one are available (Sun, SGI, XFree86 4.0 ?)
377 bool m_useBestVisual
;
379 // does any of our windows has focus?
384 // ----------------------------------------------------------------------------
385 // now include the declaration of the real class
386 // ----------------------------------------------------------------------------
389 #if defined(__WXMSW__)
390 #include "wx/msw/app.h"
391 #elif defined(__WXMOTIF__)
392 #include "wx/motif/app.h"
393 #elif defined(__WXMGL__)
394 #include "wx/mgl/app.h"
395 #elif defined(__WXGTK__)
396 #include "wx/gtk/app.h"
397 #elif defined(__WXX11__)
398 #include "wx/x11/app.h"
399 #elif defined(__WXMAC__)
400 #include "wx/mac/app.h"
401 #elif defined(__WXPM__)
402 #include "wx/os2/app.h"
403 #elif defined(__WXSTUBS__)
404 #include "wx/stubs/app.h"
407 // can't use typedef because wxApp forward declared as a class
408 class WXDLLEXPORT wxApp
: public wxAppBase
413 // ----------------------------------------------------------------------------
415 // ----------------------------------------------------------------------------
417 // the one and only application object - use of wxTheApp in application code
418 // is discouraged, consider using DECLARE_APP() after which you may call
419 // wxGetApp() which will return the object of the correct type (i.e. MyApp and
421 WXDLLEXPORT_DATA(extern wxApp
*) wxTheApp
;
423 // ----------------------------------------------------------------------------
425 // ----------------------------------------------------------------------------
427 // event loop related functions only work in GUI programs
428 // ------------------------------------------------------
430 // Force an exit from main loop
431 extern void WXDLLEXPORT
wxExit();
433 // Yield to other apps/messages
434 extern bool WXDLLEXPORT
wxYield();
436 // Yield to other apps/messages
437 extern void WXDLLEXPORT
wxWakeUpIdle();
439 // Post a message to the given eventhandler which will be processed during the
440 // next event loop iteration
441 inline void wxPostEvent(wxEvtHandler
*dest
, wxEvent
& event
)
443 wxCHECK_RET( dest
, wxT("need an object to post event to in wxPostEvent") );
446 dest
->AddPendingEvent(event
);
448 dest
->ProcessEvent(event
);
452 // console applications may avoid using DECLARE_APP and IMPLEMENT_APP macros
453 // and call these functions instead at the program startup and termination
454 // -------------------------------------------------------------------------
458 // initialize the library (may be called as many times as needed, but each
459 // call to wxInitialize() must be matched by wxUninitialize())
460 extern bool WXDLLEXPORT
wxInitialize();
462 // clean up - the library can't be used any more after the last call to
464 extern void WXDLLEXPORT
wxUninitialize();
466 // create an object of this class on stack to initialize/cleanup thel ibrary
468 class WXDLLEXPORT wxInitializer
471 // initialize the library
472 wxInitializer() { m_ok
= wxInitialize(); }
474 // has the initialization been successful? (explicit test)
475 bool IsOk() const { return m_ok
; }
477 // has the initialization been successful? (implicit test)
478 operator bool() const { return m_ok
; }
480 // dtor only does clean up if we initialized the library properly
481 ~wxInitializer() { if ( m_ok
) wxUninitialize(); }
489 // ----------------------------------------------------------------------------
490 // macros for dynamic creation of the application object
491 // ----------------------------------------------------------------------------
493 // Having a global instance of this class allows wxApp to be aware of the app
494 // creator function. wxApp can then call this function to create a new app
495 // object. Convoluted, but necessary.
497 class WXDLLEXPORT wxAppInitializer
500 wxAppInitializer(wxAppInitializerFunction fn
)
501 { wxApp::SetInitializerFunction(fn
); }
504 // Here's a macro you can use if your compiler really, really wants main() to
505 // be in your main program (e.g. hello.cpp). Now IMPLEMENT_APP should add this
508 #if !wxUSE_GUI || defined(__WXMOTIF__) || defined(__WXGTK__) || defined(__WXPM__) || defined(__WXMGL__)
509 #define IMPLEMENT_WXWIN_MAIN \
510 extern int wxEntry( int argc, char *argv[] ); \
511 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
512 #elif defined(__WXMAC__) && defined(__UNIX__)
513 // wxMac seems to have a specific wxEntry prototype
514 #define IMPLEMENT_WXWIN_MAIN \
515 extern int wxEntry( int argc, char *argv[], bool enterLoop = 1 ); \
516 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
517 #elif defined(__WXMSW__) && defined(WXUSINGDLL)
518 // NT defines APIENTRY, 3.x not
519 #if !defined(WXAPIENTRY)
520 #define WXAPIENTRY WXFAR wxSTDCALL
524 #include "wx/msw/winundef.h"
526 #define IMPLEMENT_WXWIN_MAIN \
527 extern "C" int WXAPIENTRY WinMain(HINSTANCE hInstance,\
528 HINSTANCE hPrevInstance,\
529 LPSTR m_lpCmdLine, int nCmdShow)\
531 return wxEntry((WXHINSTANCE) hInstance,\
532 (WXHINSTANCE) hPrevInstance,\
533 m_lpCmdLine, nCmdShow);\
536 #define IMPLEMENT_WXWIN_MAIN
539 #ifdef __WXUNIVERSAL__
540 #include "wx/univ/theme.h"
542 #define IMPLEMENT_WX_THEME_SUPPORT \
543 WX_USE_THEME(win32); \
546 #define IMPLEMENT_WX_THEME_SUPPORT
549 // define the build options object for the application which is compared to the
550 // one used for building the library on the program startup
551 #define WX_DEFINE_BUILDOPTS() \
552 const wxBuildOptions& wxGetBuildOptions() \
554 static wxBuildOptions s_buildOptions; \
555 return s_buildOptions; \
558 // Use this macro if you want to define your own main() or WinMain() function
559 // and call wxEntry() from there.
560 #define IMPLEMENT_APP_NO_MAIN(appname) \
561 WX_DEFINE_BUILDOPTS() \
562 wxApp *wxCreateApp() { return new appname; } \
563 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
564 appname& wxGetApp() { return *(appname *)wxTheApp; }
566 // Same as IMPLEMENT_APP() normally but doesn't include themes support in
567 // wxUniversal builds
568 #define IMPLEMENT_APP_NO_THEMES(appname) \
569 IMPLEMENT_APP_NO_MAIN(appname) \
572 // Use this macro exactly once, the argument is the name of the wxApp-derived
573 // class which is the class of your application.
574 #define IMPLEMENT_APP(appname) \
575 IMPLEMENT_APP_NO_THEMES(appname) \
576 IMPLEMENT_WX_THEME_SUPPORT
578 // this macro can be used multiple times and just allows you to use wxGetApp()
580 #define DECLARE_APP(appname) extern appname& wxGetApp();