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 // ----------------------------------------------------------------------------
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
40 #include "wx/window.h" // for wxTopLevelWindows
46 // ----------------------------------------------------------------------------
48 // ----------------------------------------------------------------------------
50 static const int wxPRINT_WINDOWS
= 1;
51 static const int wxPRINT_POSTSCRIPT
= 2;
53 // ----------------------------------------------------------------------------
54 // the common part of wxApp implementations for all platforms
55 // ----------------------------------------------------------------------------
57 class WXDLLEXPORT wxAppBase
: public wxEvtHandler
60 // the virtual functions which may/must be overridden in the derived class
61 // -----------------------------------------------------------------------
63 // called during the program initialization, returning FALSE from here
64 // prevents the program from continuing - it's a good place to create
65 // the top level program window and return TRUE.
68 virtual bool OnInit() { return FALSE
; };
70 // a platform-dependent version of OnInit(): the code here is likely to
71 // depend on the toolkit. default version does nothing.
74 virtual bool OnInitGui() { return TRUE
; }
76 // called to start program execution - the default version just enters
77 // the main GUI loop in which events are received and processed until
78 // the last window is not deleted (if GetExitOnFrameDelete) or
79 // ExitMainLoop() is called.
82 virtual int OnRun() { return MainLoop(); };
84 // called after the main loop termination. This is a good place for
85 // cleaning up (it may be too late in dtor) and is also useful if you
86 // want to return some non-default exit code - this is just the return
87 // value of this method.
90 virtual int OnExit() { return 0; }
92 // called when a fatal exception occurs, this function should take care
93 // not to do anything which might provoke a nested exception! It may be
94 // overridden if you wish to react somehow in non-default way (core
95 // dump under Unix, application crash under Windows) to fatal program
96 // errors, however extreme care should be taken if you don't want this
100 virtual void OnFatalException() { }
102 // the worker functions - usually not used directly by the user code
103 // -----------------------------------------------------------------
105 // execute the main GUI loop, the function returns when the loop ends
106 virtual int MainLoop() = 0;
108 // exit the main GUI loop during the next iteration (i.e. it does not
109 // stop the program immediately!)
110 virtual void ExitMainLoop() = 0;
112 // returns TRUE if the program is initialized
113 virtual bool Initialized() = 0;
115 // returns TRUE if there are unprocessed events in the event queue
116 virtual bool Pending() = 0;
118 // process the first event in the event queue (blocks until an event
119 // apperas if there are none currently)
120 virtual void Dispatch() = 0;
122 // application info: name, description, vendor
123 // -------------------------------------------
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
129 // set/get the application name
130 wxString
GetAppName() const
137 void SetAppName(const wxString
& name
) { m_appName
= name
; }
139 // set/get the app class name
140 wxString
GetClassName() const { return m_className
; }
141 void SetClassName(const wxString
& name
) { m_className
= name
; }
143 // set/get the vendor name
144 const wxString
& GetVendorName() const { return m_vendorName
; }
145 void SetVendorName(const wxString
& name
) { m_vendorName
= name
; }
147 // top level window functions
148 // --------------------------
150 // set the "main" top level window
151 void SetTopWindow(wxWindow
*win
) { m_topWindow
= win
; }
153 // return the "main" top level window (if it hadn't been set previously
154 // with SetTopWindow(), will return just some top level window and, if
155 // there are none, will return NULL)
156 wxWindow
*GetTopWindow() const
160 else if (wxTopLevelWindows
.GetCount() > 0)
161 return wxTopLevelWindows
.GetFirst()->GetData();
163 return (wxWindow
*)NULL
;
166 // control the exit behaviour: by default, the program will exit the
167 // main loop (and so, usually, terminate) when the last top-level
168 // program window is deleted. Beware that if you disabel this (with
169 // SetExitOnFrameDelete(FALSE)), you'll have to call ExitMainLoop()
170 // explicitly from somewhere.
171 void SetExitOnFrameDelete(bool flag
) { m_exitOnFrameDelete
= flag
; }
172 bool GetExitOnFrameDelete() const { return m_exitOnFrameDelete
; }
174 // miscellaneous customization functions
175 // -------------------------------------
178 // override this function to create default log target of arbitrary
179 // user-defined class (default implementation creates a wxLogGui
180 // object) - this log object is used by default by all wxLogXXX()
182 virtual wxLog
*CreateLogTarget() { return new wxLogGui
; }
186 // get the standard icon used by wxWin dialogs - this allows the user
187 // to customize the standard dialogs. The 'which' parameter is one of
189 virtual wxIcon
GetStdIcon(int which
) const = 0;
191 // VZ: what does this do exactly?
192 void SetWantDebugOutput( bool flag
) { m_wantDebugOutput
= flag
; }
193 bool GetWantDebugOutput() const { return m_wantDebugOutput
; }
195 // set/get printing mode: see wxPRINT_XXX constants.
197 // default behaviour is the normal one for Unix: always use PostScript
199 virtual void SetPrintMode(int WXUNUSED(mode
)) { }
200 int GetPrintMode() const { return wxPRINT_POSTSCRIPT
; }
202 // implementation only from now on
203 // -------------------------------
205 // helpers for dynamic wxApp construction
206 static void SetInitializerFunction(wxAppInitializerFunction fn
)
207 { m_appInitFn
= fn
; }
208 static wxAppInitializerFunction
GetInitializerFunction()
209 { return m_appInitFn
; }
211 // access to the command line arguments
217 // function used for dynamic wxApp creation
218 static wxAppInitializerFunction m_appInitFn
;
220 // application info (must be set from the user code)
221 wxString m_vendorName
, // vendor name (ACME Inc)
222 m_appName
, // app name
223 m_className
; // class name
225 // if TRUE, exit the main loop when the last top level window is deleted
226 bool m_exitOnFrameDelete
;
228 // TRUE if the application wants to get debug output
229 bool m_wantDebugOutput
;
231 // the main top level window - may be NULL
232 wxWindow
*m_topWindow
;
235 // ----------------------------------------------------------------------------
236 // now include the declaration of the real class
237 // ----------------------------------------------------------------------------
239 #if defined(__WXMSW__)
240 #include "wx/msw/app.h"
241 #elif defined(__WXMOTIF__)
242 #include "wx/motif/app.h"
243 #elif defined(__WXQT__)
244 #include "wx/qt/app.h"
245 #elif defined(__WXGTK__)
246 #include "wx/gtk/app.h"
247 #elif defined(__WXMAC__)
248 #include "wx/mac/app.h"
249 #elif defined(__WXSTUBS__)
250 #include "wx/stubs/app.h"
253 // ----------------------------------------------------------------------------
255 // ----------------------------------------------------------------------------
257 // the one and only application object - use of wxTheApp in application code
258 // is discouraged, consider using DECLARE_APP() after which you may call
259 // wxGetApp() which will return the object of the correct type (i.e. MyApp and
261 WXDLLEXPORT_DATA(extern wxApp
*) wxTheApp
;
263 // ----------------------------------------------------------------------------
265 // ----------------------------------------------------------------------------
267 // Force an exit from main loop
268 void WXDLLEXPORT
wxExit();
270 // Yield to other apps/messages
271 bool WXDLLEXPORT
wxYield();
273 // ----------------------------------------------------------------------------
274 // macros for dynamic creation of the application object
275 // ----------------------------------------------------------------------------
277 // Having a global instance of this class allows wxApp to be aware of the app
278 // creator function. wxApp can then call this function to create a new app
279 // object. Convoluted, but necessary.
281 class WXDLLEXPORT wxAppInitializer
284 wxAppInitializer(wxAppInitializerFunction fn
)
285 { wxApp::SetInitializerFunction(fn
); }
288 // Here's a macro you can use if your compiler really, really wants main() to
289 // be in your main program (e.g. hello.cpp). Now IMPLEMENT_APP should add this
292 #if defined(__AIX__) || defined(__HPUX__)
293 #define IMPLEMENT_WXWIN_MAIN \
294 extern int wxEntry( int argc, char *argv[] ); \
295 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
296 #elif defined(__WXMSW__) && defined(WXUSINGDLL)
297 // NT defines APIENTRY, 3.x not
298 #if !defined(WXAPIENTRY)
300 #define WXAPIENTRY PASCAL
302 #define WXAPIENTRY FAR PASCAL
306 #define IMPLEMENT_WXWIN_MAIN \
307 int WXAPIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,\
308 LPSTR m_lpCmdLine, int nCmdShow )\
310 return wxEntry((WXHINSTANCE) hInstance, \
311 (WXHINSTANCE) hPrevInstance,\
312 m_lpCmdLine, nCmdShow);\
316 #define IMPLEMENT_WXWIN_MAIN
319 // use this macro exactly once, the argument is the name of the wxApp-derived
320 // class which is the class of your application
321 #define IMPLEMENT_APP(appname) \
322 wxApp *wxCreateApp() { return new appname; } \
323 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
324 appname& wxGetApp() { return *(appname *)wxTheApp; } \
327 #define DECLARE_APP(appname) extern appname& wxGetApp();