]> git.saurik.com Git - wxWidgets.git/blame - include/wx/app.h
respect wxUSE_WIZARDDLG setting
[wxWidgets.git] / include / wx / app.h
CommitLineData
c801d85f
KB
1/////////////////////////////////////////////////////////////////////////////
2// Name: app.h
094637f6
VZ
3// Purpose: wxAppBase class and macros used for declaration of wxApp
4// derived class in the user code
c801d85f
KB
5// Author: Julian Smart
6// Modified by:
7// Created: 01/02/97
8// RCS-ID: $Id$
9// Copyright: (c) Julian Smart and Markus Holzem
094637f6 10// Licence: wxWindows licence
c801d85f
KB
11/////////////////////////////////////////////////////////////////////////////
12
34138703
JS
13#ifndef _WX_APP_H_BASE_
14#define _WX_APP_H_BASE_
c801d85f 15
094637f6
VZ
16#ifdef __GNUG__
17 #pragma interface "appbase.h"
10b959e3 18#endif
c801d85f 19
094637f6
VZ
20// ----------------------------------------------------------------------------
21// typedefs
22// ----------------------------------------------------------------------------
23
04ef50df 24#if (defined(__WXMSW__) && !defined(__WXMICROWIN__)) || defined (__WXPM__)
094637f6
VZ
25 class WXDLLEXPORT wxApp;
26 typedef wxApp* (*wxAppInitializerFunction)();
27#else
28 // returning wxApp* won't work with gcc
29 #include "wx/object.h"
c801d85f 30
094637f6 31 typedef wxObject* (*wxAppInitializerFunction)();
10b959e3 32#endif
c801d85f 33
23280650
VZ
34// ----------------------------------------------------------------------------
35// headers we have to include here
36// ----------------------------------------------------------------------------
37
38#include "wx/event.h" // for the base class
39
e90c1d2a
VZ
40#if wxUSE_GUI
41 #include "wx/window.h" // for wxTopLevelWindows
42#endif // wxUSE_GUI
23280650
VZ
43
44#if wxUSE_LOG
45 #include "wx/log.h"
46#endif
47
094637f6
VZ
48// ----------------------------------------------------------------------------
49// constants
50// ----------------------------------------------------------------------------
51
52static const int wxPRINT_WINDOWS = 1;
53static const int wxPRINT_POSTSCRIPT = 2;
54
55// ----------------------------------------------------------------------------
56// the common part of wxApp implementations for all platforms
57// ----------------------------------------------------------------------------
58
59class WXDLLEXPORT wxAppBase : public wxEvtHandler
60{
61public:
1e6feb95
VZ
62 wxAppBase();
63
094637f6
VZ
64 // the virtual functions which may/must be overridden in the derived class
65 // -----------------------------------------------------------------------
03e11df5
GD
66#ifdef __WXMAC_X__
67 virtual ~wxAppBase() {} // Added min for Mac X
68#endif
094637f6
VZ
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.
72 //
e90c1d2a
VZ
73 // Override: always in GUI application, rarely in console ones.
74#if wxUSE_GUI
094637f6 75 virtual bool OnInit() { return FALSE; };
e90c1d2a
VZ
76#else // !GUI
77 virtual bool OnInit() { return TRUE; };
78#endif // wxUSE_GUI
094637f6 79
e90c1d2a 80#if wxUSE_GUI
094637f6
VZ
81 // a platform-dependent version of OnInit(): the code here is likely to
82 // depend on the toolkit. default version does nothing.
83 //
84 // Override: rarely.
1e6feb95 85 virtual bool OnInitGui();
e90c1d2a 86#endif // wxUSE_GUI
094637f6
VZ
87
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
e90c1d2a
VZ
91 // ExitMainLoop() is called. In console mode programs, the execution
92 // of the program really starts here
094637f6 93 //
e90c1d2a
VZ
94 // Override: rarely in GUI applications, always in console ones.
95#if wxUSE_GUI
094637f6 96 virtual int OnRun() { return MainLoop(); };
e90c1d2a
VZ
97#else // !GUI
98 virtual int OnRun() = 0;
99#endif // wxUSE_GUI
094637f6
VZ
100
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.
105 //
106 // Override: often.
7beba2fc 107 virtual int OnExit();
094637f6
VZ
108
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.
115 //
116 // Override: rarely.
117 virtual void OnFatalException() { }
118
119 // the worker functions - usually not used directly by the user code
120 // -----------------------------------------------------------------
121
e90c1d2a 122#if wxUSE_GUI
094637f6
VZ
123 // execute the main GUI loop, the function returns when the loop ends
124 virtual int MainLoop() = 0;
125
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;
129
130 // returns TRUE if the program is initialized
131 virtual bool Initialized() = 0;
132
133 // returns TRUE if there are unprocessed events in the event queue
134 virtual bool Pending() = 0;
135
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;
e90c1d2a 139#endif // wxUSE_GUI
094637f6
VZ
140
141 // application info: name, description, vendor
142 // -------------------------------------------
143
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
146 // be argv[0]
147
148 // set/get the application name
149 wxString GetAppName() const
150 {
151 if ( !m_appName )
152 return m_className;
153 else
154 return m_appName;
155 }
156 void SetAppName(const wxString& name) { m_appName = name; }
157
158 // set/get the app class name
159 wxString GetClassName() const { return m_className; }
160 void SetClassName(const wxString& name) { m_className = name; }
161
162 // set/get the vendor name
163 const wxString& GetVendorName() const { return m_vendorName; }
164 void SetVendorName(const wxString& name) { m_vendorName = name; }
165
e90c1d2a 166#if wxUSE_GUI
094637f6
VZ
167 // top level window functions
168 // --------------------------
169
1e6feb95
VZ
170 // return TRUE if our app has focus
171 virtual bool IsActive() const { return m_isActive; }
172
094637f6
VZ
173 // set the "main" top level window
174 void SetTopWindow(wxWindow *win) { m_topWindow = win; }
175
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)
83a5b533 179 virtual wxWindow *GetTopWindow() const
094637f6
VZ
180 {
181 if (m_topWindow)
182 return m_topWindow;
183 else if (wxTopLevelWindows.GetCount() > 0)
184 return wxTopLevelWindows.GetFirst()->GetData();
185 else
186 return (wxWindow *)NULL;
187 }
188
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; }
196
e90c1d2a
VZ
197#endif // wxUSE_GUI
198
094637f6
VZ
199 // miscellaneous customization functions
200 // -------------------------------------
201
202#if wxUSE_LOG
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()
206 // functions.
e90c1d2a 207 virtual wxLog *CreateLogTarget()
1e6feb95
VZ
208 #if wxUSE_GUI && wxUSE_LOGGUI
209 { return new wxLogGui; }
210 #else // !GUI
211 { return new wxLogStderr; }
212 #endif // wxUSE_GUI
094637f6
VZ
213#endif // wxUSE_LOG
214
e90c1d2a 215#if wxUSE_GUI
094637f6
VZ
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
218 // wxICON_XXX values
219 virtual wxIcon GetStdIcon(int which) const = 0;
220
221 // VZ: what does this do exactly?
222 void SetWantDebugOutput( bool flag ) { m_wantDebugOutput = flag; }
223 bool GetWantDebugOutput() const { return m_wantDebugOutput; }
224
8480b297
RR
225 // set use of best visual flag (see below)
226 void SetUseBestVisual( bool flag ) { m_useBestVisual = flag; }
227 bool GetUseBestVisual() const { return m_useBestVisual; }
75acb532 228
094637f6
VZ
229 // set/get printing mode: see wxPRINT_XXX constants.
230 //
231 // default behaviour is the normal one for Unix: always use PostScript
232 // printing.
233 virtual void SetPrintMode(int WXUNUSED(mode)) { }
234 int GetPrintMode() const { return wxPRINT_POSTSCRIPT; }
1e6feb95
VZ
235
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
238 // deactivated
239 virtual void SetActive(bool isActive, wxWindow *lastFocus);
e90c1d2a 240#endif // wxUSE_GUI
094637f6
VZ
241
242 // implementation only from now on
243 // -------------------------------
244
245 // helpers for dynamic wxApp construction
246 static void SetInitializerFunction(wxAppInitializerFunction fn)
247 { m_appInitFn = fn; }
248 static wxAppInitializerFunction GetInitializerFunction()
249 { return m_appInitFn; }
250
72cdf4c9
VZ
251 // process all events in the wxPendingEvents list
252 virtual void ProcessPendingEvents();
253
094637f6 254 // access to the command line arguments
c1b03ce8
OK
255 int argc;
256 wxChar **argv;
094637f6 257
094637f6
VZ
258protected:
259 // function used for dynamic wxApp creation
260 static wxAppInitializerFunction m_appInitFn;
261
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
266
094637f6
VZ
267 // TRUE if the application wants to get debug output
268 bool m_wantDebugOutput;
75acb532 269
1e6feb95
VZ
270#if wxUSE_GUI
271 // the main top level window - may be NULL
272 wxWindow *m_topWindow;
273
274 // if TRUE, exit the main loop when the last top level window is deleted
275 bool m_exitOnFrameDelete;
276
8480b297
RR
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;
094637f6 280
1e6feb95
VZ
281 // does any of our windows has focus?
282 bool m_isActive;
e90c1d2a 283#endif // wxUSE_GUI
094637f6
VZ
284};
285
286// ----------------------------------------------------------------------------
287// now include the declaration of the real class
288// ----------------------------------------------------------------------------
289
e90c1d2a
VZ
290#if wxUSE_GUI
291 #if defined(__WXMSW__)
292 #include "wx/msw/app.h"
293 #elif defined(__WXMOTIF__)
294 #include "wx/motif/app.h"
1e6feb95
VZ
295 #elif defined(__WXMGL__)
296 #include "wx/mgl/app.h"
e90c1d2a
VZ
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"
307 #endif
308#else // !GUI
b568d04f
VZ
309 // can't use typedef because wxApp forward declared as a class
310 class WXDLLEXPORT wxApp : public wxAppBase
311 {
312 };
e90c1d2a 313#endif // GUI/!GUI
c801d85f 314
094637f6 315// ----------------------------------------------------------------------------
ee31c392
VZ
316// the global data
317// ----------------------------------------------------------------------------
318
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
322// not wxApp)
323WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
324
325// ----------------------------------------------------------------------------
326// global functions
327// ----------------------------------------------------------------------------
328
e90c1d2a
VZ
329// event loop related functions only work in GUI programs
330// ------------------------------------------------------
331
ee31c392 332// Force an exit from main loop
e90c1d2a 333extern void WXDLLEXPORT wxExit();
ee31c392
VZ
334
335// Yield to other apps/messages
e90c1d2a
VZ
336extern bool WXDLLEXPORT wxYield();
337
bf9e3e73
RR
338// Yield to other apps/messages
339extern void WXDLLEXPORT wxWakeUpIdle();
bf9e3e73 340
8e193f38
VZ
341// Post a message to the given eventhandler which will be processed during the
342// next event loop iteration
6d56eb5c 343inline void wxPostEvent(wxEvtHandler *dest, wxEvent& event)
8e193f38
VZ
344{
345 wxCHECK_RET( dest, wxT("need an object to post event to in wxPostEvent") );
346
52a07708 347#if wxUSE_GUI
8e193f38 348 dest->AddPendingEvent(event);
52a07708
VZ
349#else
350 dest->ProcessEvent(event);
b568d04f 351#endif // wxUSE_GUI
52a07708 352}
e90c1d2a
VZ
353
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// -------------------------------------------------------------------------
357
b568d04f 358#if !wxUSE_GUI
e90c1d2a
VZ
359
360// initialize the library (may be called as many times as needed, but each
361// call to wxInitialize() must be matched by wxUninitialize())
362extern bool WXDLLEXPORT wxInitialize();
363
364// clean up - the library can't be used any more after the last call to
365// wxUninitialize()
366extern void WXDLLEXPORT wxUninitialize();
367
fae9f590
VZ
368// create an object of this class on stack to initialize/cleanup thel ibrary
369// automatically
370class WXDLLEXPORT wxInitializer
371{
372public:
373 // initialize the library
374 wxInitializer() { m_ok = wxInitialize(); }
375
376 // has the initialization been successful? (explicit test)
377 bool IsOk() const { return m_ok; }
378
379 // has the initialization been successful? (implicit test)
380 operator bool() const { return m_ok; }
381
382 // dtor only does clean up if we initialized the library properly
383 ~wxInitializer() { if ( m_ok ) wxUninitialize(); }
384
385private:
386 bool m_ok;
387};
388
b568d04f 389#endif // !wxUSE_GUI
ee31c392
VZ
390
391// ----------------------------------------------------------------------------
094637f6
VZ
392// macros for dynamic creation of the application object
393// ----------------------------------------------------------------------------
394
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.
c801d85f
KB
398
399class WXDLLEXPORT wxAppInitializer
400{
401public:
094637f6
VZ
402 wxAppInitializer(wxAppInitializerFunction fn)
403 { wxApp::SetInitializerFunction(fn); }
c801d85f
KB
404};
405
094637f6
VZ
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
408// code if required.
26a87b69 409
d5408e98 410#if !wxUSE_GUI || defined(__WXMOTIF__) || defined(__WXGTK__) || defined(__WXPM__)
094637f6
VZ
411 #define IMPLEMENT_WXWIN_MAIN \
412 extern int wxEntry( int argc, char *argv[] ); \
413 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
d5408e98
GD
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); }
750b78ba 419#elif defined(__WXMSW__) && defined(WXUSINGDLL)
094637f6
VZ
420 // NT defines APIENTRY, 3.x not
421 #if !defined(WXAPIENTRY)
790ad94f 422 #define WXAPIENTRY WXFAR wxSTDCALL
094637f6 423 #endif
750b78ba 424
f6bcfd97
BP
425 #include <windows.h>
426 #include "wx/msw/winundef.h"
427
428 #define IMPLEMENT_WXWIN_MAIN \
429 extern "C" int WXAPIENTRY WinMain(HINSTANCE hInstance,\
430 HINSTANCE hPrevInstance,\
431 LPSTR m_lpCmdLine, int nCmdShow)\
432 {\
433 return wxEntry((WXHINSTANCE) hInstance,\
434 (WXHINSTANCE) hPrevInstance,\
435 m_lpCmdLine, nCmdShow);\
436 }
26a87b69 437#else
094637f6 438 #define IMPLEMENT_WXWIN_MAIN
26a87b69
JS
439#endif
440
c661ecca
RR
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; } \
094637f6
VZ
445 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
446 appname& wxGetApp() { return *(appname *)wxTheApp; } \
447 IMPLEMENT_WXWIN_MAIN
c801d85f 448
c661ecca
RR
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; }
455
094637f6 456#define DECLARE_APP(appname) extern appname& wxGetApp();
c801d85f
KB
457
458#endif
34138703 459 // _WX_APP_H_BASE_