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 // ----------------------------------------------------------------------------
35 // headers we have to include here
36 // ----------------------------------------------------------------------------
38 #include "wx/event.h" // for the base class
41 #include "wx/window.h" // for wxTopLevelWindows
48 // ----------------------------------------------------------------------------
50 // ----------------------------------------------------------------------------
52 static const int wxPRINT_WINDOWS
= 1;
53 static const int wxPRINT_POSTSCRIPT
= 2;
55 // ----------------------------------------------------------------------------
56 // the common part of wxApp implementations for all platforms
57 // ----------------------------------------------------------------------------
59 class WXDLLEXPORT wxAppBase
: public wxEvtHandler
64 // the virtual functions which may/must be overridden in the derived class
65 // -----------------------------------------------------------------------
67 virtual ~wxAppBase() {} // Added min for Mac X
69 // called during the program initialization, returning FALSE from here
70 // prevents the program from continuing - it's a good place to create
71 // the top level program window and return TRUE.
73 // Override: always in GUI application, rarely in console ones.
75 virtual bool OnInit() { return FALSE
; };
77 virtual bool OnInit() { return TRUE
; };
81 // a platform-dependent version of OnInit(): the code here is likely to
82 // depend on the toolkit. default version does nothing.
85 virtual bool OnInitGui();
88 // called to start program execution - the default version just enters
89 // the main GUI loop in which events are received and processed until
90 // the last window is not deleted (if GetExitOnFrameDelete) or
91 // ExitMainLoop() is called. In console mode programs, the execution
92 // of the program really starts here
94 // Override: rarely in GUI applications, always in console ones.
96 virtual int OnRun() { return MainLoop(); };
98 virtual int OnRun() = 0;
101 // called after the main loop termination. This is a good place for
102 // cleaning up (it may be too late in dtor) and is also useful if you
103 // want to return some non-default exit code - this is just the return
104 // value of this method.
107 virtual int OnExit();
109 // called when a fatal exception occurs, this function should take care
110 // not to do anything which might provoke a nested exception! It may be
111 // overridden if you wish to react somehow in non-default way (core
112 // dump under Unix, application crash under Windows) to fatal program
113 // errors, however extreme care should be taken if you don't want this
114 // function to crash.
117 virtual void OnFatalException() { }
119 // the worker functions - usually not used directly by the user code
120 // -----------------------------------------------------------------
123 // execute the main GUI loop, the function returns when the loop ends
124 virtual int MainLoop() = 0;
126 // exit the main GUI loop during the next iteration (i.e. it does not
127 // stop the program immediately!)
128 virtual void ExitMainLoop() = 0;
130 // returns TRUE if the program is initialized
131 virtual bool Initialized() = 0;
133 // returns TRUE if there are unprocessed events in the event queue
134 virtual bool Pending() = 0;
136 // process the first event in the event queue (blocks until an event
137 // apperas if there are none currently)
138 virtual void Dispatch() = 0;
141 // application info: name, description, vendor
142 // -------------------------------------------
144 // NB: all these should be set by the application itself, there are no
145 // reasonable default except for the application name which is taken to
148 // set/get the application name
149 wxString
GetAppName() const
156 void SetAppName(const wxString
& name
) { m_appName
= name
; }
158 // set/get the app class name
159 wxString
GetClassName() const { return m_className
; }
160 void SetClassName(const wxString
& name
) { m_className
= name
; }
162 // set/get the vendor name
163 const wxString
& GetVendorName() const { return m_vendorName
; }
164 void SetVendorName(const wxString
& name
) { m_vendorName
= name
; }
167 // top level window functions
168 // --------------------------
170 // return TRUE if our app has focus
171 virtual bool IsActive() const { return m_isActive
; }
173 // set the "main" top level window
174 void SetTopWindow(wxWindow
*win
) { m_topWindow
= win
; }
176 // return the "main" top level window (if it hadn't been set previously
177 // with SetTopWindow(), will return just some top level window and, if
178 // there are none, will return NULL)
179 virtual wxWindow
*GetTopWindow() const
183 else if (wxTopLevelWindows
.GetCount() > 0)
184 return wxTopLevelWindows
.GetFirst()->GetData();
186 return (wxWindow
*)NULL
;
189 // control the exit behaviour: by default, the program will exit the
190 // main loop (and so, usually, terminate) when the last top-level
191 // program window is deleted. Beware that if you disabel this (with
192 // SetExitOnFrameDelete(FALSE)), you'll have to call ExitMainLoop()
193 // explicitly from somewhere.
194 void SetExitOnFrameDelete(bool flag
) { m_exitOnFrameDelete
= flag
; }
195 bool GetExitOnFrameDelete() const { return m_exitOnFrameDelete
; }
199 // miscellaneous customization functions
200 // -------------------------------------
203 // override this function to create default log target of arbitrary
204 // user-defined class (default implementation creates a wxLogGui
205 // object) - this log object is used by default by all wxLogXXX()
207 virtual wxLog
*CreateLogTarget()
208 #if wxUSE_GUI && wxUSE_LOGGUI && !defined(__WXMICROWIN__)
209 { return new wxLogGui
; }
211 { return new wxLogStderr
; }
216 // get the standard icon used by wxWin dialogs - this allows the user
217 // to customize the standard dialogs. The 'which' parameter is one of
219 virtual wxIcon
GetStdIcon(int which
) const = 0;
221 // VZ: what does this do exactly?
222 void SetWantDebugOutput( bool flag
) { m_wantDebugOutput
= flag
; }
223 bool GetWantDebugOutput() const { return m_wantDebugOutput
; }
225 // set use of best visual flag (see below)
226 void SetUseBestVisual( bool flag
) { m_useBestVisual
= flag
; }
227 bool GetUseBestVisual() const { return m_useBestVisual
; }
229 // set/get printing mode: see wxPRINT_XXX constants.
231 // default behaviour is the normal one for Unix: always use PostScript
233 virtual void SetPrintMode(int WXUNUSED(mode
)) { }
234 int GetPrintMode() const { return wxPRINT_POSTSCRIPT
; }
236 // called by toolkit-specific code to set the app status: active (we have
237 // focus) or not and also the last window which had focus before we were
239 virtual void SetActive(bool isActive
, wxWindow
*lastFocus
);
242 // implementation only from now on
243 // -------------------------------
245 // helpers for dynamic wxApp construction
246 static void SetInitializerFunction(wxAppInitializerFunction fn
)
247 { m_appInitFn
= fn
; }
248 static wxAppInitializerFunction
GetInitializerFunction()
249 { return m_appInitFn
; }
251 // process all events in the wxPendingEvents list
252 virtual void ProcessPendingEvents();
254 // access to the command line arguments
259 // function used for dynamic wxApp creation
260 static wxAppInitializerFunction m_appInitFn
;
262 // application info (must be set from the user code)
263 wxString m_vendorName
, // vendor name (ACME Inc)
264 m_appName
, // app name
265 m_className
; // class name
267 // TRUE if the application wants to get debug output
268 bool m_wantDebugOutput
;
271 // the main top level window - may be NULL
272 wxWindow
*m_topWindow
;
274 // if TRUE, exit the main loop when the last top level window is deleted
275 bool m_exitOnFrameDelete
;
277 // TRUE if the apps whats to use the best visual on systems where
278 // more than one are available (Sun, SGI, XFree86 4.0 ?)
279 bool m_useBestVisual
;
281 // does any of our windows has focus?
286 // ----------------------------------------------------------------------------
287 // now include the declaration of the real class
288 // ----------------------------------------------------------------------------
291 #if defined(__WXMSW__)
292 #include "wx/msw/app.h"
293 #elif defined(__WXMOTIF__)
294 #include "wx/motif/app.h"
295 #elif defined(__WXMGL__)
296 #include "wx/mgl/app.h"
297 #elif defined(__WXQT__)
298 #include "wx/qt/app.h"
299 #elif defined(__WXGTK__)
300 #include "wx/gtk/app.h"
301 #elif defined(__WXMAC__)
302 #include "wx/mac/app.h"
303 #elif defined(__WXPM__)
304 #include "wx/os2/app.h"
305 #elif defined(__WXSTUBS__)
306 #include "wx/stubs/app.h"
309 // can't use typedef because wxApp forward declared as a class
310 class WXDLLEXPORT wxApp
: public wxAppBase
315 // ----------------------------------------------------------------------------
317 // ----------------------------------------------------------------------------
319 // the one and only application object - use of wxTheApp in application code
320 // is discouraged, consider using DECLARE_APP() after which you may call
321 // wxGetApp() which will return the object of the correct type (i.e. MyApp and
323 WXDLLEXPORT_DATA(extern wxApp
*) wxTheApp
;
325 // ----------------------------------------------------------------------------
327 // ----------------------------------------------------------------------------
329 // event loop related functions only work in GUI programs
330 // ------------------------------------------------------
332 // Force an exit from main loop
333 extern void WXDLLEXPORT
wxExit();
335 // Yield to other apps/messages
336 extern bool WXDLLEXPORT
wxYield();
338 // Yield to other apps/messages
339 extern void WXDLLEXPORT
wxWakeUpIdle();
341 // Post a message to the given eventhandler which will be processed during the
342 // next event loop iteration
343 inline void wxPostEvent(wxEvtHandler
*dest
, wxEvent
& event
)
345 wxCHECK_RET( dest
, wxT("need an object to post event to in wxPostEvent") );
348 dest
->AddPendingEvent(event
);
350 dest
->ProcessEvent(event
);
354 // console applications may avoid using DECLARE_APP and IMPLEMENT_APP macros
355 // and call these functions instead at the program startup and termination
356 // -------------------------------------------------------------------------
360 // initialize the library (may be called as many times as needed, but each
361 // call to wxInitialize() must be matched by wxUninitialize())
362 extern bool WXDLLEXPORT
wxInitialize();
364 // clean up - the library can't be used any more after the last call to
366 extern void WXDLLEXPORT
wxUninitialize();
368 // create an object of this class on stack to initialize/cleanup thel ibrary
370 class WXDLLEXPORT wxInitializer
373 // initialize the library
374 wxInitializer() { m_ok
= wxInitialize(); }
376 // has the initialization been successful? (explicit test)
377 bool IsOk() const { return m_ok
; }
379 // has the initialization been successful? (implicit test)
380 operator bool() const { return m_ok
; }
382 // dtor only does clean up if we initialized the library properly
383 ~wxInitializer() { if ( m_ok
) wxUninitialize(); }
391 // ----------------------------------------------------------------------------
392 // macros for dynamic creation of the application object
393 // ----------------------------------------------------------------------------
395 // Having a global instance of this class allows wxApp to be aware of the app
396 // creator function. wxApp can then call this function to create a new app
397 // object. Convoluted, but necessary.
399 class WXDLLEXPORT wxAppInitializer
402 wxAppInitializer(wxAppInitializerFunction fn
)
403 { wxApp::SetInitializerFunction(fn
); }
406 // Here's a macro you can use if your compiler really, really wants main() to
407 // be in your main program (e.g. hello.cpp). Now IMPLEMENT_APP should add this
410 #if !wxUSE_GUI || defined(__WXMOTIF__) || defined(__WXGTK__) || defined(__WXPM__)
411 #define IMPLEMENT_WXWIN_MAIN \
412 extern int wxEntry( int argc, char *argv[] ); \
413 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
414 #elif defined(__WXMAC__) && defined(__UNIX__)
415 // wxMac seems to have a specific wxEntry prototype
416 #define IMPLEMENT_WXWIN_MAIN \
417 extern int wxEntry( int argc, char *argv[], bool enterLoop = 1 ); \
418 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
419 #elif defined(__WXMSW__) && defined(WXUSINGDLL)
420 // NT defines APIENTRY, 3.x not
421 #if !defined(WXAPIENTRY)
422 #define WXAPIENTRY WXFAR wxSTDCALL
426 #include "wx/msw/winundef.h"
428 #define IMPLEMENT_WXWIN_MAIN \
429 extern "C" int WXAPIENTRY WinMain(HINSTANCE hInstance,\
430 HINSTANCE hPrevInstance,\
431 LPSTR m_lpCmdLine, int nCmdShow)\
433 return wxEntry((WXHINSTANCE) hInstance,\
434 (WXHINSTANCE) hPrevInstance,\
435 m_lpCmdLine, nCmdShow);\
438 #define IMPLEMENT_WXWIN_MAIN
441 // Use this macro exactly once, the argument is the name of the wxApp-derived
442 // class which is the class of your application.
443 #define IMPLEMENT_APP(appname) \
444 wxApp *wxCreateApp() { return new appname; } \
445 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
446 appname& wxGetApp() { return *(appname *)wxTheApp; } \
449 // Use this macro if you want to define your own main() or WinMain() function
450 // and call wxEntry() from there.
451 #define IMPLEMENT_APP_NO_MAIN(appname) \
452 wxApp *wxCreateApp() { return new appname; } \
453 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
454 appname& wxGetApp() { return *(appname *)wxTheApp; }
456 #define DECLARE_APP(appname) extern appname& wxGetApp();