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
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
62 // the virtual functions which may/must be overridden in the derived class
63 // -----------------------------------------------------------------------
65 // called during the program initialization, returning FALSE from here
66 // prevents the program from continuing - it's a good place to create
67 // the top level program window and return TRUE.
69 // Override: always in GUI application, rarely in console ones.
71 virtual bool OnInit() { return FALSE
; };
73 virtual bool OnInit() { return TRUE
; };
77 // a platform-dependent version of OnInit(): the code here is likely to
78 // depend on the toolkit. default version does nothing.
81 virtual bool OnInitGui() { return TRUE
; }
84 // called to start program execution - the default version just enters
85 // the main GUI loop in which events are received and processed until
86 // the last window is not deleted (if GetExitOnFrameDelete) or
87 // ExitMainLoop() is called. In console mode programs, the execution
88 // of the program really starts here
90 // Override: rarely in GUI applications, always in console ones.
92 virtual int OnRun() { return MainLoop(); };
94 virtual int OnRun() = 0;
97 // called after the main loop termination. This is a good place for
98 // cleaning up (it may be too late in dtor) and is also useful if you
99 // want to return some non-default exit code - this is just the return
100 // value of this method.
103 virtual int OnExit();
105 // called when a fatal exception occurs, this function should take care
106 // not 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
108 // dump under Unix, application crash under Windows) to fatal program
109 // errors, however extreme care should be taken if you don't want this
110 // function to crash.
113 virtual void OnFatalException() { }
115 // the worker functions - usually not used directly by the user code
116 // -----------------------------------------------------------------
119 // execute the main GUI loop, the function returns when the loop ends
120 virtual int MainLoop() = 0;
122 // exit the main GUI loop during the next iteration (i.e. it does not
123 // stop the program immediately!)
124 virtual void ExitMainLoop() = 0;
126 // returns TRUE if the program is initialized
127 virtual bool Initialized() = 0;
129 // returns TRUE if there are unprocessed events in the event queue
130 virtual bool Pending() = 0;
132 // process the first event in the event queue (blocks until an event
133 // apperas if there are none currently)
134 virtual void Dispatch() = 0;
137 // application info: name, description, vendor
138 // -------------------------------------------
140 // NB: all these should be set by the application itself, there are no
141 // reasonable default except for the application name which is taken to
144 // set/get the application name
145 wxString
GetAppName() const
152 void SetAppName(const wxString
& name
) { m_appName
= name
; }
154 // set/get the app class name
155 wxString
GetClassName() const { return m_className
; }
156 void SetClassName(const wxString
& name
) { m_className
= name
; }
158 // set/get the vendor name
159 const wxString
& GetVendorName() const { return m_vendorName
; }
160 void SetVendorName(const wxString
& name
) { m_vendorName
= name
; }
163 // top level window functions
164 // --------------------------
166 // set the "main" top level window
167 void SetTopWindow(wxWindow
*win
) { m_topWindow
= win
; }
169 // return the "main" top level window (if it hadn't been set previously
170 // with SetTopWindow(), will return just some top level window and, if
171 // there are none, will return NULL)
172 wxWindow
*GetTopWindow() const
176 else if (wxTopLevelWindows
.GetCount() > 0)
177 return wxTopLevelWindows
.GetFirst()->GetData();
179 return (wxWindow
*)NULL
;
182 // control the exit behaviour: by default, the program will exit the
183 // main loop (and so, usually, terminate) when the last top-level
184 // program window is deleted. Beware that if you disabel this (with
185 // SetExitOnFrameDelete(FALSE)), you'll have to call ExitMainLoop()
186 // explicitly from somewhere.
187 void SetExitOnFrameDelete(bool flag
) { m_exitOnFrameDelete
= flag
; }
188 bool GetExitOnFrameDelete() const { return m_exitOnFrameDelete
; }
192 // miscellaneous customization functions
193 // -------------------------------------
196 // override this function to create default log target of arbitrary
197 // user-defined class (default implementation creates a wxLogGui
198 // object) - this log object is used by default by all wxLogXXX()
200 virtual wxLog
*CreateLogTarget()
202 { return new wxLogGui
; }
204 { return new wxLogStderr
; }
209 // get the standard icon used by wxWin dialogs - this allows the user
210 // to customize the standard dialogs. The 'which' parameter is one of
212 virtual wxIcon
GetStdIcon(int which
) const = 0;
214 // VZ: what does this do exactly?
215 void SetWantDebugOutput( bool flag
) { m_wantDebugOutput
= flag
; }
216 bool GetWantDebugOutput() const { return m_wantDebugOutput
; }
218 // set use of best visual flag (see below)
219 void SetUseBestVisual( bool flag
) { m_useBestVisual
= flag
; }
220 bool GetUseBestVisual() const { return m_useBestVisual
; }
222 // set/get printing mode: see wxPRINT_XXX constants.
224 // default behaviour is the normal one for Unix: always use PostScript
226 virtual void SetPrintMode(int WXUNUSED(mode
)) { }
227 int GetPrintMode() const { return wxPRINT_POSTSCRIPT
; }
230 // implementation only from now on
231 // -------------------------------
233 // helpers for dynamic wxApp construction
234 static void SetInitializerFunction(wxAppInitializerFunction fn
)
235 { m_appInitFn
= fn
; }
236 static wxAppInitializerFunction
GetInitializerFunction()
237 { return m_appInitFn
; }
239 // process all events in the wxPendingEvents list
240 virtual void ProcessPendingEvents();
242 // access to the command line arguments
248 // function used for dynamic wxApp creation
249 static wxAppInitializerFunction m_appInitFn
;
251 // application info (must be set from the user code)
252 wxString m_vendorName
, // vendor name (ACME Inc)
253 m_appName
, // app name
254 m_className
; // class name
256 // if TRUE, exit the main loop when the last top level window is deleted
257 bool m_exitOnFrameDelete
;
259 // TRUE if the application wants to get debug output
260 bool m_wantDebugOutput
;
262 // TRUE if the apps whats to use the best visual on systems where
263 // more than one are available (Sun, SGI, XFree86 4.0 ?)
264 bool m_useBestVisual
;
267 // the main top level window - may be NULL
268 wxWindow
*m_topWindow
;
272 // ----------------------------------------------------------------------------
273 // now include the declaration of the real class
274 // ----------------------------------------------------------------------------
277 #if defined(__WXMSW__)
278 #include "wx/msw/app.h"
279 #elif defined(__WXMOTIF__)
280 #include "wx/motif/app.h"
281 #elif defined(__WXQT__)
282 #include "wx/qt/app.h"
283 #elif defined(__WXGTK__)
284 #include "wx/gtk/app.h"
285 #elif defined(__WXMAC__)
286 #include "wx/mac/app.h"
287 #elif defined(__WXPM__)
288 #include "wx/os2/app.h"
289 #elif defined(__WXSTUBS__)
290 #include "wx/stubs/app.h"
293 // can't use typedef because wxApp forward declared as a class
294 class WXDLLEXPORT wxApp
: public wxAppBase
299 // ----------------------------------------------------------------------------
301 // ----------------------------------------------------------------------------
303 // the one and only application object - use of wxTheApp in application code
304 // is discouraged, consider using DECLARE_APP() after which you may call
305 // wxGetApp() which will return the object of the correct type (i.e. MyApp and
307 WXDLLEXPORT_DATA(extern wxApp
*) wxTheApp
;
309 // ----------------------------------------------------------------------------
311 // ----------------------------------------------------------------------------
313 // event loop related functions only work in GUI programs
314 // ------------------------------------------------------
316 // Force an exit from main loop
317 extern void WXDLLEXPORT
wxExit();
319 // Yield to other apps/messages
320 extern bool WXDLLEXPORT
wxYield();
322 // Yield to other apps/messages
323 extern void WXDLLEXPORT
wxWakeUpIdle();
327 // Post a message to the given eventhandler which will be processed during the
328 // next event loop iteration
329 inline void WXDLLEXPORT
wxPostEvent(wxEvtHandler
*dest
, wxEvent
& event
)
331 wxCHECK_RET( dest
, wxT("need an object to post event to in wxPostEvent") );
333 dest
->AddPendingEvent(event
);
338 // console applications may avoid using DECLARE_APP and IMPLEMENT_APP macros
339 // and call these functions instead at the program startup and termination
340 // -------------------------------------------------------------------------
344 // initialize the library (may be called as many times as needed, but each
345 // call to wxInitialize() must be matched by wxUninitialize())
346 extern bool WXDLLEXPORT
wxInitialize();
348 // clean up - the library can't be used any more after the last call to
350 extern void WXDLLEXPORT
wxUninitialize();
354 // ----------------------------------------------------------------------------
355 // macros for dynamic creation of the application object
356 // ----------------------------------------------------------------------------
358 // Having a global instance of this class allows wxApp to be aware of the app
359 // creator function. wxApp can then call this function to create a new app
360 // object. Convoluted, but necessary.
362 class WXDLLEXPORT wxAppInitializer
365 wxAppInitializer(wxAppInitializerFunction fn
)
366 { wxApp::SetInitializerFunction(fn
); }
369 // Here's a macro you can use if your compiler really, really wants main() to
370 // be in your main program (e.g. hello.cpp). Now IMPLEMENT_APP should add this
373 #if !wxUSE_GUI || defined(__AIX__) || defined(__HPUX__) || defined( __VMS__ ) || defined(__WXPM__)
374 #define IMPLEMENT_WXWIN_MAIN \
375 extern int wxEntry( int argc, char *argv[] ); \
376 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
377 #elif defined(__WXMSW__) && defined(WXUSINGDLL)
378 // NT defines APIENTRY, 3.x not
379 #if !defined(WXAPIENTRY)
380 #define WXAPIENTRY FAR wxSTDCALL
383 #define IMPLEMENT_WXWIN_MAIN \
384 int WXAPIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,\
385 LPSTR m_lpCmdLine, int nCmdShow )\
387 return wxEntry((WXHINSTANCE) hInstance, \
388 (WXHINSTANCE) hPrevInstance,\
389 m_lpCmdLine, nCmdShow);\
393 #define IMPLEMENT_WXWIN_MAIN
396 // use this macro exactly once, the argument is the name of the wxApp-derived
397 // class which is the class of your application
398 #define IMPLEMENT_APP(appname) \
399 wxApp *wxCreateApp() { return new appname; } \
400 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
401 appname& wxGetApp() { return *(appname *)wxTheApp; } \
404 #define DECLARE_APP(appname) extern appname& wxGetApp();