implemented, tested and documented wxTextCtrl::SetMaxLength()
[wxWidgets.git] / include / wx / app.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: app.h
3 // Purpose: wxAppBase class and macros used for declaration of wxApp
4 // derived class in the user code
5 // Author: Julian Smart
6 // Modified by:
7 // Created: 01/02/97
8 // RCS-ID: $Id$
9 // Copyright: (c) Julian Smart and Markus Holzem
10 // Licence: wxWindows licence
11 /////////////////////////////////////////////////////////////////////////////
12
13 #ifndef _WX_APP_H_BASE_
14 #define _WX_APP_H_BASE_
15
16 #ifdef __GNUG__
17 #pragma interface "appbase.h"
18 #endif
19
20 // ----------------------------------------------------------------------------
21 // typedefs
22 // ----------------------------------------------------------------------------
23
24 #if (defined(__WXMSW__) && !defined(__WXMICROWIN__)) || defined (__WXPM__)
25 class WXDLLEXPORT wxApp;
26 typedef wxApp* (*wxAppInitializerFunction)();
27 #else
28 // returning wxApp* won't work with gcc
29 #include "wx/object.h"
30
31 typedef wxObject* (*wxAppInitializerFunction)();
32 #endif
33
34 class WXDLLEXPORT wxCmdLineParser;
35
36 // ----------------------------------------------------------------------------
37 // headers we have to include here
38 // ----------------------------------------------------------------------------
39
40 #include "wx/event.h" // for the base class
41
42 #if wxUSE_GUI
43 #include "wx/window.h" // for wxTopLevelWindows
44 #endif // wxUSE_GUI
45
46 #if wxUSE_LOG
47 #include "wx/log.h"
48 #endif
49
50 // ----------------------------------------------------------------------------
51 // constants
52 // ----------------------------------------------------------------------------
53
54 static const int wxPRINT_WINDOWS = 1;
55 static const int wxPRINT_POSTSCRIPT = 2;
56
57 // ----------------------------------------------------------------------------
58 // the common part of wxApp implementations for all platforms
59 // ----------------------------------------------------------------------------
60
61 class WXDLLEXPORT wxAppBase : public wxEvtHandler
62 {
63 public:
64 wxAppBase();
65
66 // the virtual functions which may/must be overridden in the derived class
67 // -----------------------------------------------------------------------
68 #ifdef __DARWIN__
69 virtual ~wxAppBase() { }
70 #endif
71
72 // called during the program initialization, returning FALSE from here
73 // prevents the program from continuing - it's a good place to create
74 // the top level program window and return TRUE.
75 //
76 // Override: always in GUI application, rarely in console ones.
77 virtual bool OnInit();
78
79 #if wxUSE_GUI
80 // a platform-dependent version of OnInit(): the code here is likely to
81 // depend on the toolkit. default version does nothing.
82 //
83 // Override: rarely.
84 virtual bool OnInitGui();
85 #endif // wxUSE_GUI
86
87 // called to start program execution - the default version just enters
88 // the main GUI loop in which events are received and processed until
89 // the last window is not deleted (if GetExitOnFrameDelete) or
90 // ExitMainLoop() is called. In console mode programs, the execution
91 // of the program really starts here
92 //
93 // Override: rarely in GUI applications, always in console ones.
94 #if wxUSE_GUI
95 virtual int OnRun() { return MainLoop(); };
96 #else // !GUI
97 virtual int OnRun() = 0;
98 #endif // wxUSE_GUI
99
100 // called after the main loop termination. This is a good place for
101 // cleaning up (it may be too late in dtor) and is also useful if you
102 // want to return some non-default exit code - this is just the return
103 // value of this method.
104 //
105 // Override: often.
106 virtual int OnExit();
107
108 // called when a fatal exception occurs, this function should take care
109 // not to do anything which might provoke a nested exception! It may be
110 // overridden if you wish to react somehow in non-default way (core
111 // dump under Unix, application crash under Windows) to fatal program
112 // errors, however extreme care should be taken if you don't want this
113 // function to crash.
114 //
115 // Override: rarely.
116 virtual void OnFatalException() { }
117
118 // the worker functions - usually not used directly by the user code
119 // -----------------------------------------------------------------
120
121 #if wxUSE_GUI
122 // execute the main GUI loop, the function returns when the loop ends
123 virtual int MainLoop() = 0;
124
125 // exit the main GUI loop during the next iteration (i.e. it does not
126 // stop the program immediately!)
127 virtual void ExitMainLoop() = 0;
128
129 // returns TRUE if the program is initialized
130 virtual bool Initialized() = 0;
131
132 // returns TRUE if there are unprocessed events in the event queue
133 virtual bool Pending() = 0;
134
135 // process the first event in the event queue (blocks until an event
136 // apperas if there are none currently)
137 virtual void Dispatch() = 0;
138 #endif // wxUSE_GUI
139
140 // application info: name, description, vendor
141 // -------------------------------------------
142
143 // NB: all these should be set by the application itself, there are no
144 // reasonable default except for the application name which is taken to
145 // be argv[0]
146
147 // set/get the application name
148 wxString GetAppName() const
149 {
150 if ( !m_appName )
151 return m_className;
152 else
153 return m_appName;
154 }
155 void SetAppName(const wxString& name) { m_appName = name; }
156
157 // set/get the app class name
158 wxString GetClassName() const { return m_className; }
159 void SetClassName(const wxString& name) { m_className = name; }
160
161 // set/get the vendor name
162 const wxString& GetVendorName() const { return m_vendorName; }
163 void SetVendorName(const wxString& name) { m_vendorName = name; }
164
165 #if wxUSE_GUI
166 // top level window functions
167 // --------------------------
168
169 // return TRUE if our app has focus
170 virtual bool IsActive() const { return m_isActive; }
171
172 // set the "main" top level window
173 void SetTopWindow(wxWindow *win) { m_topWindow = win; }
174
175 // return the "main" top level window (if it hadn't been set previously
176 // with SetTopWindow(), will return just some top level window and, if
177 // there are none, will return NULL)
178 virtual wxWindow *GetTopWindow() const
179 {
180 if (m_topWindow)
181 return m_topWindow;
182 else if (wxTopLevelWindows.GetCount() > 0)
183 return wxTopLevelWindows.GetFirst()->GetData();
184 else
185 return (wxWindow *)NULL;
186 }
187
188 // control the exit behaviour: by default, the program will exit the
189 // main loop (and so, usually, terminate) when the last top-level
190 // program window is deleted. Beware that if you disabel this (with
191 // SetExitOnFrameDelete(FALSE)), you'll have to call ExitMainLoop()
192 // explicitly from somewhere.
193 void SetExitOnFrameDelete(bool flag) { m_exitOnFrameDelete = flag; }
194 bool GetExitOnFrameDelete() const { return m_exitOnFrameDelete; }
195
196 #endif // wxUSE_GUI
197
198 // cmd line parsing stuff
199 // ----------------------
200
201 // all of these methods may be overridden in the derived class to
202 // customize the command line parsing (by default only a few standard
203 // options are handled)
204 //
205 // you also need to call wxApp::OnInit() from YourApp::OnInit() for all
206 // this to work
207
208 #if wxUSE_CMDLINE_PARSER
209 // this one is called from OnInit() to add all supported options
210 // to the given parser
211 virtual void OnInitCmdLine(wxCmdLineParser& parser);
212
213 // called after successfully parsing the command line, return TRUE
214 // to continue and FALSE to exit
215 virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
216
217 // called if "--help" option was specified, return TRUE to continue
218 // and FALSE to exit
219 virtual bool OnCmdLineHelp(wxCmdLineParser& parser);
220
221 // called if incorrect command line options were given, return
222 // FALSE to abort and TRUE to continue
223 virtual bool OnCmdLineError(wxCmdLineParser& parser);
224 #endif // wxUSE_CMDLINE_PARSER
225
226 // miscellaneous customization functions
227 // -------------------------------------
228
229 #if wxUSE_LOG
230 // override this function to create default log target of arbitrary
231 // user-defined class (default implementation creates a wxLogGui
232 // object) - this log object is used by default by all wxLogXXX()
233 // functions.
234 virtual wxLog *CreateLogTarget()
235 #if wxUSE_GUI && wxUSE_LOGGUI && !defined(__WXMICROWIN__)
236 { return new wxLogGui; }
237 #else // !GUI
238 { return new wxLogStderr; }
239 #endif // wxUSE_GUI
240 #endif // wxUSE_LOG
241
242 #if wxUSE_GUI
243 // get the standard icon used by wxWin dialogs - this allows the user
244 // to customize the standard dialogs. The 'which' parameter is one of
245 // wxICON_XXX values
246 virtual wxIcon GetStdIcon(int which) const = 0;
247
248 // VZ: what does this do exactly?
249 void SetWantDebugOutput( bool flag ) { m_wantDebugOutput = flag; }
250 bool GetWantDebugOutput() const { return m_wantDebugOutput; }
251
252 // set use of best visual flag (see below)
253 void SetUseBestVisual( bool flag ) { m_useBestVisual = flag; }
254 bool GetUseBestVisual() const { return m_useBestVisual; }
255
256 // set/get printing mode: see wxPRINT_XXX constants.
257 //
258 // default behaviour is the normal one for Unix: always use PostScript
259 // printing.
260 virtual void SetPrintMode(int WXUNUSED(mode)) { }
261 int GetPrintMode() const { return wxPRINT_POSTSCRIPT; }
262
263 // called by toolkit-specific code to set the app status: active (we have
264 // focus) or not and also the last window which had focus before we were
265 // deactivated
266 virtual void SetActive(bool isActive, wxWindow *lastFocus);
267 #endif // wxUSE_GUI
268
269 // debugging support
270 // -----------------
271
272 // this function is called when an assert failure occurs, the base class
273 // version does the normal processing (i.e. shows the usual assert failure
274 // dialog box)
275 #ifdef __WXDEBUG__
276 virtual void OnAssert(const wxChar *file, int line, const wxChar *msg);
277 #endif // __WXDEBUG__
278
279 // implementation only from now on
280 // -------------------------------
281
282 // helpers for dynamic wxApp construction
283 static void SetInitializerFunction(wxAppInitializerFunction fn)
284 { m_appInitFn = fn; }
285 static wxAppInitializerFunction GetInitializerFunction()
286 { return m_appInitFn; }
287
288 // process all events in the wxPendingEvents list
289 virtual void ProcessPendingEvents();
290
291 // access to the command line arguments
292 int argc;
293 wxChar **argv;
294
295 protected:
296 // function used for dynamic wxApp creation
297 static wxAppInitializerFunction m_appInitFn;
298
299 // application info (must be set from the user code)
300 wxString m_vendorName, // vendor name (ACME Inc)
301 m_appName, // app name
302 m_className; // class name
303
304 // TRUE if the application wants to get debug output
305 bool m_wantDebugOutput;
306
307 #if wxUSE_GUI
308 // the main top level window - may be NULL
309 wxWindow *m_topWindow;
310
311 // if TRUE, exit the main loop when the last top level window is deleted
312 bool m_exitOnFrameDelete;
313
314 // TRUE if the apps whats to use the best visual on systems where
315 // more than one are available (Sun, SGI, XFree86 4.0 ?)
316 bool m_useBestVisual;
317
318 // does any of our windows has focus?
319 bool m_isActive;
320 #endif // wxUSE_GUI
321 };
322
323 // ----------------------------------------------------------------------------
324 // now include the declaration of the real class
325 // ----------------------------------------------------------------------------
326
327 #if wxUSE_GUI
328 #if defined(__WXMSW__)
329 #include "wx/msw/app.h"
330 #elif defined(__WXMOTIF__)
331 #include "wx/motif/app.h"
332 #elif defined(__WXMGL__)
333 #include "wx/mgl/app.h"
334 #elif defined(__WXQT__)
335 #include "wx/qt/app.h"
336 #elif defined(__WXGTK__)
337 #include "wx/gtk/app.h"
338 #elif defined(__WXMAC__)
339 #include "wx/mac/app.h"
340 #elif defined(__WXPM__)
341 #include "wx/os2/app.h"
342 #elif defined(__WXSTUBS__)
343 #include "wx/stubs/app.h"
344 #endif
345 #else // !GUI
346 // can't use typedef because wxApp forward declared as a class
347 class WXDLLEXPORT wxApp : public wxAppBase
348 {
349 };
350 #endif // GUI/!GUI
351
352 // ----------------------------------------------------------------------------
353 // the global data
354 // ----------------------------------------------------------------------------
355
356 // the one and only application object - use of wxTheApp in application code
357 // is discouraged, consider using DECLARE_APP() after which you may call
358 // wxGetApp() which will return the object of the correct type (i.e. MyApp and
359 // not wxApp)
360 WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
361
362 // ----------------------------------------------------------------------------
363 // global functions
364 // ----------------------------------------------------------------------------
365
366 // event loop related functions only work in GUI programs
367 // ------------------------------------------------------
368
369 // Force an exit from main loop
370 extern void WXDLLEXPORT wxExit();
371
372 // Yield to other apps/messages
373 extern bool WXDLLEXPORT wxYield();
374
375 // Yield to other apps/messages
376 extern void WXDLLEXPORT wxWakeUpIdle();
377
378 // Post a message to the given eventhandler which will be processed during the
379 // next event loop iteration
380 inline void wxPostEvent(wxEvtHandler *dest, wxEvent& event)
381 {
382 wxCHECK_RET( dest, wxT("need an object to post event to in wxPostEvent") );
383
384 #if wxUSE_GUI
385 dest->AddPendingEvent(event);
386 #else
387 dest->ProcessEvent(event);
388 #endif // wxUSE_GUI
389 }
390
391 // console applications may avoid using DECLARE_APP and IMPLEMENT_APP macros
392 // and call these functions instead at the program startup and termination
393 // -------------------------------------------------------------------------
394
395 #if !wxUSE_GUI
396
397 // initialize the library (may be called as many times as needed, but each
398 // call to wxInitialize() must be matched by wxUninitialize())
399 extern bool WXDLLEXPORT wxInitialize();
400
401 // clean up - the library can't be used any more after the last call to
402 // wxUninitialize()
403 extern void WXDLLEXPORT wxUninitialize();
404
405 // create an object of this class on stack to initialize/cleanup thel ibrary
406 // automatically
407 class WXDLLEXPORT wxInitializer
408 {
409 public:
410 // initialize the library
411 wxInitializer() { m_ok = wxInitialize(); }
412
413 // has the initialization been successful? (explicit test)
414 bool IsOk() const { return m_ok; }
415
416 // has the initialization been successful? (implicit test)
417 operator bool() const { return m_ok; }
418
419 // dtor only does clean up if we initialized the library properly
420 ~wxInitializer() { if ( m_ok ) wxUninitialize(); }
421
422 private:
423 bool m_ok;
424 };
425
426 #endif // !wxUSE_GUI
427
428 // ----------------------------------------------------------------------------
429 // macros for dynamic creation of the application object
430 // ----------------------------------------------------------------------------
431
432 // Having a global instance of this class allows wxApp to be aware of the app
433 // creator function. wxApp can then call this function to create a new app
434 // object. Convoluted, but necessary.
435
436 class WXDLLEXPORT wxAppInitializer
437 {
438 public:
439 wxAppInitializer(wxAppInitializerFunction fn)
440 { wxApp::SetInitializerFunction(fn); }
441 };
442
443 // Here's a macro you can use if your compiler really, really wants main() to
444 // be in your main program (e.g. hello.cpp). Now IMPLEMENT_APP should add this
445 // code if required.
446
447 #if !wxUSE_GUI || defined(__WXMOTIF__) || defined(__WXGTK__) || defined(__WXPM__) || defined(__WXMGL__)
448 #define IMPLEMENT_WXWIN_MAIN \
449 extern int wxEntry( int argc, char *argv[] ); \
450 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
451 #elif defined(__WXMAC__) && defined(__UNIX__)
452 // wxMac seems to have a specific wxEntry prototype
453 #define IMPLEMENT_WXWIN_MAIN \
454 extern int wxEntry( int argc, char *argv[], bool enterLoop = 1 ); \
455 int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
456 #elif defined(__WXMSW__) && defined(WXUSINGDLL)
457 // NT defines APIENTRY, 3.x not
458 #if !defined(WXAPIENTRY)
459 #define WXAPIENTRY WXFAR wxSTDCALL
460 #endif
461
462 #include <windows.h>
463 #include "wx/msw/winundef.h"
464
465 #define IMPLEMENT_WXWIN_MAIN \
466 extern "C" int WXAPIENTRY WinMain(HINSTANCE hInstance,\
467 HINSTANCE hPrevInstance,\
468 LPSTR m_lpCmdLine, int nCmdShow)\
469 {\
470 return wxEntry((WXHINSTANCE) hInstance,\
471 (WXHINSTANCE) hPrevInstance,\
472 m_lpCmdLine, nCmdShow);\
473 }
474 #else
475 #define IMPLEMENT_WXWIN_MAIN
476 #endif
477
478 #ifdef __WXUNIVERSAL__
479 #include "wx/univ/theme.h"
480
481 #define IMPLEMENT_WX_THEME_SUPPORT \
482 WX_USE_THEME(win32); \
483 WX_USE_THEME(gtk);
484 #else
485 #define IMPLEMENT_WX_THEME_SUPPORT
486 #endif
487
488 // Use this macro if you want to define your own main() or WinMain() function
489 // and call wxEntry() from there.
490 #define IMPLEMENT_APP_NO_MAIN(appname) \
491 wxApp *wxCreateApp() { return new appname; } \
492 wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
493 appname& wxGetApp() { return *(appname *)wxTheApp; }
494
495 // Same as IMPLEMENT_APP() normally but doesn't include themes support in
496 // wxUniversal builds
497 #define IMPLEMENT_APP_NO_THEMES(appname) \
498 IMPLEMENT_APP_NO_MAIN(appname) \
499 IMPLEMENT_WXWIN_MAIN
500
501 // Use this macro exactly once, the argument is the name of the wxApp-derived
502 // class which is the class of your application.
503 #define IMPLEMENT_APP(appname) \
504 IMPLEMENT_APP_NO_THEMES(appname) \
505 IMPLEMENT_WX_THEME_SUPPORT
506
507 // this macro can be used multiple times and just allows you to use wxGetApp()
508 // function
509 #define DECLARE_APP(appname) extern appname& wxGetApp();
510
511 #endif
512 // _WX_APP_H_BASE_