]> git.saurik.com Git - wxWidgets.git/blame - include/wx/app.h
Remove wxRTTI macro for wxComboBox from Motif port.
[wxWidgets.git] / include / wx / app.h
CommitLineData
c801d85f 1/////////////////////////////////////////////////////////////////////////////
090a6d7a 2// Name: wx/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$
371a5b4e 9// Copyright: (c) Julian Smart
65571936 10// Licence: wxWindows licence
c801d85f
KB
11/////////////////////////////////////////////////////////////////////////////
12
34138703
JS
13#ifndef _WX_APP_H_BASE_
14#define _WX_APP_H_BASE_
c801d85f 15
23280650
VZ
16// ----------------------------------------------------------------------------
17// headers we have to include here
18// ----------------------------------------------------------------------------
19
20#include "wx/event.h" // for the base class
58cc1587 21#include "wx/eventfilter.h" // (and another one)
090a6d7a 22#include "wx/build.h"
541ea80f 23#include "wx/cmdargs.h" // for wxCmdLineArgsArray used by wxApp::argv
0fcbaf23 24#include "wx/init.h" // we must declare wxEntry()
5ff14574 25#include "wx/intl.h" // for wxLayoutDirection
7d9550df 26#include "wx/log.h" // for wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
090a6d7a 27
b5dbe15d
VS
28class WXDLLIMPEXP_FWD_BASE wxAppConsole;
29class WXDLLIMPEXP_FWD_BASE wxAppTraits;
30class WXDLLIMPEXP_FWD_BASE wxCmdLineParser;
31class WXDLLIMPEXP_FWD_BASE wxEventLoopBase;
b5dbe15d 32class WXDLLIMPEXP_FWD_BASE wxMessageOutput;
a69be60b 33
4d90072c 34#if wxUSE_GUI
4ec80a59 35 struct WXDLLIMPEXP_FWD_CORE wxVideoMode;
d48b06bd 36 class WXDLLIMPEXP_FWD_CORE wxWindow;
fb761cd5 37#endif
1bf77ee5 38
7d9550df
VZ
39// this macro should be used in any main() or equivalent functions defined in wx
40#define wxDISABLE_DEBUG_SUPPORT() \
41 wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
42 wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
43
53c9228e
VZ
44// ----------------------------------------------------------------------------
45// typedefs
46// ----------------------------------------------------------------------------
47
48// the type of the function used to create a wxApp object on program start up
e8e1149b 49typedef wxAppConsole* (*wxAppInitializerFunction)();
53c9228e 50
094637f6
VZ
51// ----------------------------------------------------------------------------
52// constants
53// ----------------------------------------------------------------------------
54
e2478fde
VZ
55enum
56{
57 wxPRINT_WINDOWS = 1,
58 wxPRINT_POSTSCRIPT = 2
59};
094637f6 60
3185abc2
VZ
61// ----------------------------------------------------------------------------
62// global variables
63// ----------------------------------------------------------------------------
64
65// use of this list is strongly deprecated, use wxApp ScheduleForDestruction()
66// and IsScheduledForDestruction() methods instead of this list directly, it
67// is here for compatibility purposes only
68extern WXDLLIMPEXP_DATA_BASE(wxList) wxPendingDelete;
69
094637f6 70// ----------------------------------------------------------------------------
e0954e72 71// wxAppConsoleBase: wxApp for non-GUI applications
094637f6
VZ
72// ----------------------------------------------------------------------------
73
58cc1587
VZ
74class WXDLLIMPEXP_BASE wxAppConsoleBase : public wxEvtHandler,
75 public wxEventFilter
094637f6
VZ
76{
77public:
e2478fde 78 // ctor and dtor
e0954e72
VZ
79 wxAppConsoleBase();
80 virtual ~wxAppConsoleBase();
e2478fde 81
1e6feb95 82
094637f6
VZ
83 // the virtual functions which may/must be overridden in the derived class
84 // -----------------------------------------------------------------------
bf188f1a 85
94826170
VZ
86 // This is the very first function called for a newly created wxApp object,
87 // it is used by the library to do the global initialization. If, for some
88 // reason, you must override it (instead of just overriding OnInit(), as
89 // usual, for app-specific initializations), do not forget to call the base
90 // class version!
05e2b077 91 virtual bool Initialize(int& argc, wxChar **argv);
94826170 92
7fbc89bb
DE
93 // This gives wxCocoa a chance to call OnInit() with a memory pool in place
94 virtual bool CallOnInit() { return OnInit(); }
95
e2478fde
VZ
96 // Called before OnRun(), this is a good place to do initialization -- if
97 // anything fails, return false from here to prevent the program from
98 // continuing. The command line is normally parsed here, call the base
99 // class OnInit() to do it.
bf188f1a 100 virtual bool OnInit();
094637f6 101
e2478fde
VZ
102 // This is the replacement for the normal main(): all program work should
103 // be done here. When OnRun() returns, the programs starts shutting down.
b46b1d59 104 virtual int OnRun();
094637f6 105
ec38d07d
FM
106 // This is called by wxEventLoopBase::SetActive(): you should put the code
107 // which needs an active event loop here.
108 // Note that this function is called whenever an event loop is activated;
109 // you may want to use wxEventLoopBase::IsMain() to perform initialization
110 // specific for the app's main event loop.
111 virtual void OnEventLoopEnter(wxEventLoopBase* WXUNUSED(loop)) {}
112
e2478fde
VZ
113 // This is only called if OnInit() returned true so it's a good place to do
114 // any cleanup matching the initializations done there.
7beba2fc 115 virtual int OnExit();
094637f6 116
ec38d07d
FM
117 // This is called by wxEventLoopBase::OnExit() for each event loop which
118 // is exited.
119 virtual void OnEventLoopExit(wxEventLoopBase* WXUNUSED(loop)) {}
120
94826170
VZ
121 // This is the very last function called on wxApp object before it is
122 // destroyed. If you override it (instead of overriding OnExit() as usual)
123 // do not forget to call the base class version!
124 virtual void CleanUp();
125
e2478fde
VZ
126 // Called when a fatal exception occurs, this function should take care not
127 // to do anything which might provoke a nested exception! It may be
128 // overridden if you wish to react somehow in non-default way (core dump
129 // under Unix, application crash under Windows) to fatal program errors,
130 // however extreme care should be taken if you don't want this function to
131 // crash.
094637f6
VZ
132 virtual void OnFatalException() { }
133
e2478fde
VZ
134 // Called from wxExit() function, should terminate the application a.s.a.p.
135 virtual void Exit();
b137e493 136
094637f6
VZ
137
138 // application info: name, description, vendor
139 // -------------------------------------------
140
141 // NB: all these should be set by the application itself, there are no
142 // reasonable default except for the application name which is taken to
143 // be argv[0]
144
145 // set/get the application name
f432e677 146 wxString GetAppName() const;
094637f6
VZ
147 void SetAppName(const wxString& name) { m_appName = name; }
148
9cf3d218
VZ
149 // set/get the application display name: the display name is the name
150 // shown to the user in titles, reports, etc while the app name is
151 // used for paths, config, and other places the user doesn't see
152 //
f432e677
VZ
153 // by default the display name is the same as app name or a capitalized
154 // version of the program if app name was not set neither but it's
155 // usually better to set it explicitly to something nicer
156 wxString GetAppDisplayName() const;
328fafa1 157
9cf3d218
VZ
158 void SetAppDisplayName(const wxString& name) { m_appDisplayName = name; }
159
094637f6
VZ
160 // set/get the app class name
161 wxString GetClassName() const { return m_className; }
162 void SetClassName(const wxString& name) { m_className = name; }
163
164 // set/get the vendor name
165 const wxString& GetVendorName() const { return m_vendorName; }
166 void SetVendorName(const wxString& name) { m_vendorName = name; }
167
180b5b48
VZ
168 // set/get the vendor display name: the display name is shown
169 // in titles/reports/dialogs to the user, while the vendor name
170 // is used in some areas such as wxConfig, wxStandardPaths, etc
171 const wxString& GetVendorDisplayName() const
172 {
173 return m_vendorDisplayName.empty() ? GetVendorName()
174 : m_vendorDisplayName;
175 }
176 void SetVendorDisplayName(const wxString& name)
177 {
178 m_vendorDisplayName = name;
179 }
180
e90c1d2a 181
bf188f1a
VZ
182 // cmd line parsing stuff
183 // ----------------------
184
185 // all of these methods may be overridden in the derived class to
186 // customize the command line parsing (by default only a few standard
187 // options are handled)
188 //
189 // you also need to call wxApp::OnInit() from YourApp::OnInit() for all
190 // this to work
191
192#if wxUSE_CMDLINE_PARSER
193 // this one is called from OnInit() to add all supported options
b913d3ed
VZ
194 // to the given parser (don't forget to call the base class version if you
195 // override it!)
bf188f1a
VZ
196 virtual void OnInitCmdLine(wxCmdLineParser& parser);
197
4629016d
WS
198 // called after successfully parsing the command line, return true
199 // to continue and false to exit (don't forget to call the base class
b913d3ed 200 // version if you override it!)
bf188f1a
VZ
201 virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
202
4629016d
WS
203 // called if "--help" option was specified, return true to continue
204 // and false to exit
bf188f1a
VZ
205 virtual bool OnCmdLineHelp(wxCmdLineParser& parser);
206
207 // called if incorrect command line options were given, return
4629016d 208 // false to abort and true to continue
bf188f1a
VZ
209 virtual bool OnCmdLineError(wxCmdLineParser& parser);
210#endif // wxUSE_CMDLINE_PARSER
211
e2478fde 212
094637f6
VZ
213 // miscellaneous customization functions
214 // -------------------------------------
215
e2478fde
VZ
216 // create the app traits object to which we delegate for everything which
217 // either should be configurable by the user (then he can change the
218 // default behaviour simply by overriding CreateTraits() and returning his
219 // own traits object) or which is GUI/console dependent as then wxAppTraits
9d55bfef 220 // allows us to abstract the differences behind the common facade
e2478fde
VZ
221 wxAppTraits *GetTraits();
222
96b2cbe8
VZ
223 // this function provides safer access to traits object than
224 // wxTheApp->GetTraits() during startup or termination when the global
225 // application object itself may be unavailable
226 //
227 // of course, it still returns NULL in this case and the caller must check
228 // for it
229 static wxAppTraits *GetTraitsIfExists();
75acb532 230
ec38d07d
FM
231 // returns the main event loop instance, i.e. the event loop which is started
232 // by OnRun() and which dispatches all events sent from the native toolkit
233 // to the application (except when new event loops are temporarily set-up).
234 // The returned value maybe NULL. Put initialization code which needs a
235 // non-NULL main event loop into OnEventLoopEnter().
236 wxEventLoopBase* GetMainLoop() const
237 { return m_mainLoop; }
238
b5101417
VZ
239 // This function sets the C locale to the default locale for the current
240 // environment. It is advised to call this to ensure that the underlying
241 // toolkit uses the locale in which the numbers and monetary amounts are
242 // shown in the format expected by user and so on.
243 //
244 // Notice that this does _not_ change the global C++ locale, you need to do
245 // it explicitly if you want.
246 //
247 // Finally, notice that while this function is virtual, it is not supposed
248 // to be overridden outside of the library itself.
249 virtual void SetCLocale();
250
ec38d07d 251
e2478fde
VZ
252 // event processing functions
253 // --------------------------
094637f6 254
58cc1587
VZ
255 // Implement the inherited wxEventFilter method but just return -1 from it
256 // to indicate that default processing should take place.
9154d8cf
VZ
257 virtual int FilterEvent(wxEvent& event);
258
dde19c21
FM
259 // return true if we're running event loop, i.e. if the events can
260 // (already) be dispatched
261 static bool IsMainLoopRunning();
262
883117d1 263#if wxUSE_EXCEPTIONS
3c778901
VZ
264 // execute the functor to handle the given event
265 //
266 // this is a generalization of HandleEvent() below and the base class
267 // implementation of CallEventHandler() still calls HandleEvent() for
268 // compatibility for functors which are just wxEventFunctions (i.e. methods
269 // of wxEvtHandler)
270 virtual void CallEventHandler(wxEvtHandler *handler,
271 wxEventFunctor& functor,
272 wxEvent& event) const;
273
883117d1
VZ
274 // call the specified handler on the given object with the given event
275 //
276 // this method only exists to allow catching the exceptions thrown by any
277 // event handler, it would lead to an extra (useless) virtual function call
278 // if the exceptions were not used, so it doesn't even exist in that case
279 virtual void HandleEvent(wxEvtHandler *handler,
280 wxEventFunction func,
281 wxEvent& event) const;
2dc62891
VZ
282
283 // Called when an unhandled C++ exception occurs inside OnRun(): note that
1663c655
VZ
284 // the main event loop has already terminated by now and the program will
285 // exit, if you need to really handle the exceptions you need to override
286 // OnExceptionInMainLoop()
287 virtual void OnUnhandledException();
dde19c21
FM
288
289 // Function called if an uncaught exception is caught inside the main
290 // event loop: it may return true to continue running the event loop or
291 // false to stop it (in the latter case it may rethrow the exception as
292 // well)
293 virtual bool OnExceptionInMainLoop();
294
883117d1
VZ
295#endif // wxUSE_EXCEPTIONS
296
b46b1d59 297
8e40ed85
FM
298 // pending events
299 // --------------
300
301 // IMPORTANT: all these methods conceptually belong to wxEventLoopBase
302 // but for many reasons we need to allow queuing of events
303 // even when there's no event loop (e.g. in wxApp::OnInit);
304 // this feature is used e.g. to queue events on secondary threads
305 // or in wxPython to use wx.CallAfter before the GUI is initialized
306
307 // process all events in the m_handlersWithPendingEvents list -- it is necessary
308 // to call this function to process posted events. This happens during each
309 // event loop iteration in GUI mode but if there is no main loop, it may be
310 // also called directly.
e2478fde 311 virtual void ProcessPendingEvents();
8e40ed85
FM
312
313 // check if there are pending events on global pending event list
b46b1d59
VZ
314 bool HasPendingEvents() const;
315
8e40ed85
FM
316 // temporary suspends processing of the pending events
317 void SuspendProcessingOfPendingEvents();
318
319 // resume processing of the pending events previously stopped because of a
320 // call to SuspendProcessingOfPendingEvents()
321 void ResumeProcessingOfPendingEvents();
322
323 // called by ~wxEvtHandler to (eventually) remove the handler from the list of
324 // the handlers with pending events
325 void RemovePendingEventHandler(wxEvtHandler* toRemove);
326
327 // adds an event handler to the list of the handlers with pending events
328 void AppendPendingEventHandler(wxEvtHandler* toAppend);
329
330 // moves the event handler from the list of the handlers with pending events
331 //to the list of the handlers with _delayed_ pending events
332 void DelayPendingEventHandler(wxEvtHandler* toDelay);
333
cae9e7b1
FM
334 // deletes the current pending events
335 void DeletePendingEvents();
336
8e40ed85 337
3185abc2
VZ
338 // delayed destruction
339 // -------------------
340
341 // If an object may have pending events for it, it shouldn't be deleted
342 // immediately as this would result in a crash when trying to handle these
343 // events: instead, it should be scheduled for destruction and really
344 // destroyed only after processing all pending events.
345 //
346 // Notice that this is only possible if we have a running event loop,
347 // otherwise the object is just deleted directly by ScheduleForDestruction()
348 // and IsScheduledForDestruction() always returns false.
349
350 // schedule the object for destruction in the near future
351 void ScheduleForDestruction(wxObject *object);
352
353 // return true if the object is scheduled for destruction
354 bool IsScheduledForDestruction(wxObject *object) const;
355
356
357 // wxEventLoop-related methods
358 // ---------------------------
8e40ed85 359
a758f601
VZ
360 // all these functions are forwarded to the corresponding methods of the
361 // currently active event loop -- and do nothing if there is none
dde19c21
FM
362 virtual bool Pending();
363 virtual bool Dispatch();
b46b1d59 364
b46b1d59 365 virtual int MainLoop();
b46b1d59
VZ
366 virtual void ExitMainLoop();
367
dde19c21 368 bool Yield(bool onlyIfNeeded = false);
e2478fde 369
dde19c21 370 virtual void WakeUpIdle();
a758f601
VZ
371
372 // this method is called by the active event loop when there are no events
373 // to process
374 //
375 // by default it generates the idle events and if you override it in your
376 // derived class you should call the base class version to ensure that idle
377 // events are still sent out
b46b1d59
VZ
378 virtual bool ProcessIdle();
379
3185abc2
VZ
380 // this virtual function is overridden in GUI wxApp to always return true
381 // as GUI applications always have an event loop -- but console ones may
382 // have it or not, so it simply returns true if already have an event loop
383 // running but false otherwise
384 virtual bool UsesEventLoop() const;
385
d48b06bd 386
a5f1fd3e
VZ
387 // debugging support
388 // -----------------
389
390 // this function is called when an assert failure occurs, the base class
391 // version does the normal processing (i.e. shows the usual assert failure
392 // dialog box)
aad65f13 393 //
3ec4a23f
VZ
394 // the arguments are the location of the failed assert (func may be empty
395 // if the compiler doesn't support C99 __FUNCTION__), the text of the
aad65f13 396 // assert itself and the user-specified message
3ec4a23f
VZ
397 virtual void OnAssertFailure(const wxChar *file,
398 int line,
399 const wxChar *func,
400 const wxChar *cond,
401 const wxChar *msg);
402
403 // old version of the function without func parameter, for compatibility
404 // only, override OnAssertFailure() in the new code
aad65f13
VZ
405 virtual void OnAssert(const wxChar *file,
406 int line,
407 const wxChar *cond,
408 const wxChar *msg);
8030d606 409
090a6d7a 410 // check that the wxBuildOptions object (constructed in the application
e4431849 411 // itself, usually the one from wxIMPLEMENT_APP() macro) matches the build
090a6d7a 412 // options of the library and abort if it doesn't
2a7c7605
VS
413 static bool CheckBuildOptions(const char *optionsSignature,
414 const char *componentName);
73deed44 415
094637f6
VZ
416 // implementation only from now on
417 // -------------------------------
418
419 // helpers for dynamic wxApp construction
420 static void SetInitializerFunction(wxAppInitializerFunction fn)
e2478fde 421 { ms_appInitFn = fn; }
094637f6 422 static wxAppInitializerFunction GetInitializerFunction()
e2478fde 423 { return ms_appInitFn; }
094637f6 424
a80e5f9e
VZ
425 // accessors for ms_appInstance field (external code might wish to modify
426 // it, this is why we provide a setter here as well, but you should really
427 // know what you're doing if you call it), wxTheApp is usually used instead
428 // of GetInstance()
429 static wxAppConsole *GetInstance() { return ms_appInstance; }
430 static void SetInstance(wxAppConsole *app) { ms_appInstance = app; }
431
72cdf4c9 432
e2478fde 433 // command line arguments (public for backwards compatibility)
541ea80f
VZ
434 int argc;
435
436 // this object is implicitly convertible to either "char**" (traditional
437 // type of argv parameter of main()) or to "wchar_t **" (for compatibility
438 // with Unicode build in previous wx versions and because the command line
439 // can, in pr
440#if wxUSE_UNICODE
441 wxCmdLineArgsArray argv;
442#else
443 char **argv;
444#endif
094637f6 445
094637f6 446protected:
3185abc2
VZ
447 // delete all objects in wxPendingDelete list
448 //
449 // called from ProcessPendingEvents()
450 void DeletePendingObjects();
451
e2478fde
VZ
452 // the function which creates the traits object when GetTraits() needs it
453 // for the first time
454 virtual wxAppTraits *CreateTraits();
455
094637f6 456 // function used for dynamic wxApp creation
e2478fde 457 static wxAppInitializerFunction ms_appInitFn;
094637f6 458
a80e5f9e
VZ
459 // the one and only global application object
460 static wxAppConsole *ms_appInstance;
461
b46b1d59
VZ
462 // create main loop from AppTraits or return NULL if
463 // there is no main loop implementation
2ddff00c 464 wxEventLoopBase *CreateMainLoop();
7cafd224 465
094637f6 466 // application info (must be set from the user code)
180b5b48
VZ
467 wxString m_vendorName, // vendor name ("acme")
468 m_vendorDisplayName, // vendor display name (e.g. "ACME Inc")
9cf3d218
VZ
469 m_appName, // app name ("myapp")
470 m_appDisplayName, // app display name ("My Application")
471 m_className; // class name
a69be60b 472
e2478fde
VZ
473 // the class defining the application behaviour, NULL initially and created
474 // by GetTraits() when first needed
475 wxAppTraits *m_traits;
476
b46b1d59
VZ
477 // the main event loop of the application (may be NULL if the loop hasn't
478 // been started yet or has already terminated)
2ddff00c 479 wxEventLoopBase *m_mainLoop;
e2478fde 480
cae9e7b1
FM
481
482 // pending events management vars:
483
8e40ed85
FM
484 // the array of the handlers with pending events which needs to be processed
485 // inside ProcessPendingEvents()
486 wxEvtHandlerArray m_handlersWithPendingEvents;
487
cae9e7b1
FM
488 // helper array used by ProcessPendingEvents() to store the event handlers
489 // which have pending events but of these events none can be processed right now
490 // (because of a call to wxEventLoop::YieldFor() which asked to selectively process
491 // pending events)
8e40ed85
FM
492 wxEvtHandlerArray m_handlersWithPendingDelayedEvents;
493
494#if wxUSE_THREADS
495 // this critical section protects both the lists above
496 wxCriticalSection m_handlersWithPendingEventsLocker;
497#endif
498
cae9e7b1
FM
499 // flag modified by Suspend/ResumeProcessingOfPendingEvents()
500 bool m_bDoPendingEventProcessing;
501
e799e8d7 502 friend class WXDLLIMPEXP_FWD_BASE wxEvtHandler;
d48b06bd 503
e2478fde
VZ
504 // the application object is a singleton anyhow, there is no sense in
505 // copying it
c0c133e1 506 wxDECLARE_NO_COPY_CLASS(wxAppConsoleBase);
e2478fde
VZ
507};
508
acbed114 509#if defined(__UNIX__) && !defined(__WXMSW__)
e0954e72
VZ
510 #include "wx/unix/app.h"
511#else
4c2a8d89
VZ
512 // this has to be a class and not a typedef as we forward declare it
513 class wxAppConsole : public wxAppConsoleBase { };
e0954e72
VZ
514#endif
515
e2478fde
VZ
516// ----------------------------------------------------------------------------
517// wxAppBase: the common part of wxApp implementations for all platforms
518// ----------------------------------------------------------------------------
519
1e6feb95 520#if wxUSE_GUI
e2478fde 521
bddd7a8d 522class WXDLLIMPEXP_CORE wxAppBase : public wxAppConsole
e2478fde
VZ
523{
524public:
525 wxAppBase();
526 virtual ~wxAppBase();
527
528 // the virtual functions which may/must be overridden in the derived class
529 // -----------------------------------------------------------------------
530
94826170
VZ
531 // very first initialization function
532 //
533 // Override: very rarely
05e2b077 534 virtual bool Initialize(int& argc, wxChar **argv);
94826170 535
e2478fde
VZ
536 // a platform-dependent version of OnInit(): the code here is likely to
537 // depend on the toolkit. default version does nothing.
538 //
539 // Override: rarely.
540 virtual bool OnInitGui();
541
542 // called to start program execution - the default version just enters
543 // the main GUI loop in which events are received and processed until
544 // the last window is not deleted (if GetExitOnFrameDelete) or
545 // ExitMainLoop() is called. In console mode programs, the execution
546 // of the program really starts here
547 //
548 // Override: rarely in GUI applications, always in console ones.
549 virtual int OnRun();
550
b913d3ed
VZ
551 // a matching function for OnInit()
552 virtual int OnExit();
553
94826170
VZ
554 // very last clean up function
555 //
556 // Override: very rarely
557 virtual void CleanUp();
e2478fde
VZ
558
559
560 // the worker functions - usually not used directly by the user code
561 // -----------------------------------------------------------------
562
d48b06bd
FM
563 // safer alternatives to Yield(), using wxWindowDisabler
564 virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
565 virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
e2478fde
VZ
566
567 // this virtual function is called in the GUI mode when the application
568 // becomes idle and normally just sends wxIdleEvent to all interested
569 // parties
570 //
4629016d 571 // it should return true if more idle events are needed, false if not
1bf77ee5 572 virtual bool ProcessIdle();
e39af974 573
3185abc2
VZ
574 // override base class version: GUI apps always use an event loop
575 virtual bool UsesEventLoop() const { return true; }
576
2dc62891 577
e2478fde
VZ
578 // top level window functions
579 // --------------------------
580
4629016d 581 // return true if our app has focus
e2478fde
VZ
582 virtual bool IsActive() const { return m_isActive; }
583
584 // set the "main" top level window
585 void SetTopWindow(wxWindow *win) { m_topWindow = win; }
586
587 // return the "main" top level window (if it hadn't been set previously
588 // with SetTopWindow(), will return just some top level window and, if
589 // there are none, will return NULL)
5ff14574 590 virtual wxWindow *GetTopWindow() const;
e2478fde
VZ
591
592 // control the exit behaviour: by default, the program will exit the
593 // main loop (and so, usually, terminate) when the last top-level
594 // program window is deleted. Beware that if you disable this behaviour
4629016d 595 // (with SetExitOnFrameDelete(false)), you'll have to call
e2478fde
VZ
596 // ExitMainLoop() explicitly from somewhere.
597 void SetExitOnFrameDelete(bool flag)
598 { m_exitOnFrameDelete = flag ? Yes : No; }
599 bool GetExitOnFrameDelete() const
600 { return m_exitOnFrameDelete == Yes; }
601
602
603 // display mode, visual, printing mode, ...
604 // ------------------------------------------------------------------------
605
606 // Get display mode that is used use. This is only used in framebuffer
0e1f8ea4 607 // wxWin ports such as wxDFB.
5ff14574 608 virtual wxVideoMode GetDisplayMode() const;
e2478fde 609 // Set display mode to use. This is only used in framebuffer wxWin
0e1f8ea4 610 // ports such as wxDFB. This method should be called from
e2478fde 611 // wxApp::OnInitGui
4629016d 612 virtual bool SetDisplayMode(const wxVideoMode& WXUNUSED(info)) { return true; }
e2478fde
VZ
613
614 // set use of best visual flag (see below)
9cf3d218 615 void SetUseBestVisual( bool flag, bool forceTrueColour = false )
515a31bf 616 { m_useBestVisual = flag; m_forceTrueColour = forceTrueColour; }
e2478fde
VZ
617 bool GetUseBestVisual() const { return m_useBestVisual; }
618
619 // set/get printing mode: see wxPRINT_XXX constants.
620 //
621 // default behaviour is the normal one for Unix: always use PostScript
622 // printing.
623 virtual void SetPrintMode(int WXUNUSED(mode)) { }
624 int GetPrintMode() const { return wxPRINT_POSTSCRIPT; }
625
475a93b7
VZ
626 // Return the layout direction for the current locale or wxLayout_Default
627 // if it's unknown
628 virtual wxLayoutDirection GetLayoutDirection() const;
629
c50c6fb2
VZ
630 // Change the theme used by the application, return true on success.
631 virtual bool SetNativeTheme(const wxString& WXUNUSED(theme)) { return false; }
632
e2478fde 633
b913d3ed
VZ
634 // command line parsing (GUI-specific)
635 // ------------------------------------------------------------------------
636
8030d606 637#if wxUSE_CMDLINE_PARSER
b913d3ed
VZ
638 virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
639 virtual void OnInitCmdLine(wxCmdLineParser& parser);
8030d606 640#endif
b913d3ed 641
e2478fde
VZ
642 // miscellaneous other stuff
643 // ------------------------------------------------------------------------
644
645 // called by toolkit-specific code to set the app status: active (we have
646 // focus) or not and also the last window which had focus before we were
647 // deactivated
648 virtual void SetActive(bool isActive, wxWindow *lastFocus);
649
40ff126a 650#if WXWIN_COMPATIBILITY_2_6
dd435a79
VZ
651 // OBSOLETE: don't use, always returns true
652 //
653 // returns true if the program is successfully initialized
40ff126a
WS
654 wxDEPRECATED( bool Initialized() );
655#endif // WXWIN_COMPATIBILITY_2_6
dd435a79 656
e2478fde
VZ
657protected:
658 // override base class method to use GUI traits
659 virtual wxAppTraits *CreateTraits();
660
661
662 // the main top level window (may be NULL)
1e6feb95
VZ
663 wxWindow *m_topWindow;
664
1cbee0b4
VZ
665 // if Yes, exit the main loop when the last top level window is deleted, if
666 // No don't do it and if Later -- only do it once we reach our OnRun()
667 //
668 // the explanation for using this strange scheme is given in appcmn.cpp
669 enum
670 {
671 Later = -1,
672 No,
673 Yes
674 } m_exitOnFrameDelete;
1e6feb95 675
90e572f1 676 // true if the app wants to use the best visual on systems where
8480b297
RR
677 // more than one are available (Sun, SGI, XFree86 4.0 ?)
678 bool m_useBestVisual;
515a31bf
RR
679 // force TrueColour just in case "best" isn't TrueColour
680 bool m_forceTrueColour;
094637f6 681
90e572f1 682 // does any of our windows have focus?
1e6feb95 683 bool m_isActive;
e2478fde 684
c0c133e1 685 wxDECLARE_NO_COPY_CLASS(wxAppBase);
094637f6
VZ
686};
687
40ff126a
WS
688#if WXWIN_COMPATIBILITY_2_6
689 inline bool wxAppBase::Initialized() { return true; }
690#endif // WXWIN_COMPATIBILITY_2_6
691
094637f6
VZ
692// ----------------------------------------------------------------------------
693// now include the declaration of the real class
694// ----------------------------------------------------------------------------
695
bd362275 696#if defined(__WXMSW__)
e0954e72
VZ
697 #include "wx/msw/app.h"
698#elif defined(__WXMOTIF__)
699 #include "wx/motif/app.h"
e0954e72
VZ
700#elif defined(__WXDFB__)
701 #include "wx/dfb/app.h"
702#elif defined(__WXGTK20__)
703 #include "wx/gtk/app.h"
704#elif defined(__WXGTK__)
705 #include "wx/gtk1/app.h"
706#elif defined(__WXX11__)
707 #include "wx/x11/app.h"
708#elif defined(__WXMAC__)
ef0e9220 709 #include "wx/osx/app.h"
e0954e72
VZ
710#elif defined(__WXCOCOA__)
711 #include "wx/cocoa/app.h"
712#elif defined(__WXPM__)
713 #include "wx/os2/app.h"
714#endif
715
e90c1d2a 716#else // !GUI
e0954e72
VZ
717
718// wxApp is defined in core and we cannot define another one in wxBase,
719// so use the preprocessor to allow using wxApp in console programs too
720#define wxApp wxAppConsole
721
e90c1d2a 722#endif // GUI/!GUI
c801d85f 723
094637f6 724// ----------------------------------------------------------------------------
ee31c392
VZ
725// the global data
726// ----------------------------------------------------------------------------
727
7cafd224
VZ
728// for compatibility, we define this macro to access the global application
729// object of type wxApp
730//
731// note that instead of using of wxTheApp in application code you should
e4431849 732// consider using wxDECLARE_APP() after which you may call wxGetApp() which will
7cafd224
VZ
733// return the object of the correct type (i.e. MyApp and not wxApp)
734//
735// the cast is safe as in GUI build we only use wxApp, not wxAppConsole, and in
736// console mode it does nothing at all
5c33522f 737#define wxTheApp static_cast<wxApp*>(wxApp::GetInstance())
ee31c392
VZ
738
739// ----------------------------------------------------------------------------
740// global functions
741// ----------------------------------------------------------------------------
742
e90c1d2a
VZ
743// event loop related functions only work in GUI programs
744// ------------------------------------------------------
745
ee31c392 746// Force an exit from main loop
38281826 747WXDLLIMPEXP_BASE void wxExit();
ee31c392 748
d48b06bd 749// avoid redeclaring this function here if it had been already declared by
a131b460
VZ
750// wx/utils.h, this results in warnings from g++ with -Wredundant-decls
751#ifndef wx_YIELD_DECLARED
752#define wx_YIELD_DECLARED
753
ee31c392 754// Yield to other apps/messages
38281826 755WXDLLIMPEXP_CORE bool wxYield();
e90c1d2a 756
a131b460
VZ
757#endif // wx_YIELD_DECLARED
758
bf9e3e73 759// Yield to other apps/messages
38281826 760WXDLLIMPEXP_BASE void wxWakeUpIdle();
bf9e3e73 761
ee31c392 762// ----------------------------------------------------------------------------
094637f6
VZ
763// macros for dynamic creation of the application object
764// ----------------------------------------------------------------------------
765
766// Having a global instance of this class allows wxApp to be aware of the app
767// creator function. wxApp can then call this function to create a new app
768// object. Convoluted, but necessary.
c801d85f 769
bddd7a8d 770class WXDLLIMPEXP_BASE wxAppInitializer
c801d85f
KB
771{
772public:
094637f6
VZ
773 wxAppInitializer(wxAppInitializerFunction fn)
774 { wxApp::SetInitializerFunction(fn); }
c801d85f
KB
775};
776
e4431849 777// the code below defines a wxIMPLEMENT_WXWIN_MAIN macro which you can use if
956495ca 778// your compiler really, really wants main() to be in your main program (e.g.
e4431849 779// hello.cpp). Now wxIMPLEMENT_APP should add this code if required.
26a87b69 780
bfa78c63
VZ
781// For compilers that support it, prefer to use wmain() as this ensures any
782// Unicode strings can be passed as command line parameters and not just those
783// representable in the current locale.
784#if wxUSE_UNICODE && defined(__VISUALC__)
785 #define wxIMPLEMENT_WXWIN_MAIN_CONSOLE \
786 int wmain(int argc, wchar_t **argv) \
787 { \
788 wxDISABLE_DEBUG_SUPPORT(); \
7d9550df 789 \
bfa78c63
VZ
790 return wxEntry(argc, argv); \
791 }
792#else // Use standard main()
793 #define wxIMPLEMENT_WXWIN_MAIN_CONSOLE \
794 int main(int argc, char **argv) \
795 { \
796 wxDISABLE_DEBUG_SUPPORT(); \
797 \
798 return wxEntry(argc, argv); \
799 }
800#endif
80b2db4e 801
90e572f1 802// port-specific header could have defined it already in some special way
e4431849
FM
803#ifndef wxIMPLEMENT_WXWIN_MAIN
804 #define wxIMPLEMENT_WXWIN_MAIN wxIMPLEMENT_WXWIN_MAIN_CONSOLE
805#endif // defined(wxIMPLEMENT_WXWIN_MAIN)
26a87b69 806
24e78d27
VZ
807#ifdef __WXUNIVERSAL__
808 #include "wx/univ/theme.h"
809
ee92941a 810 #ifdef wxUNIV_DEFAULT_THEME
e4431849 811 #define wxIMPLEMENT_WX_THEME_SUPPORT \
ee92941a
VS
812 WX_USE_THEME(wxUNIV_DEFAULT_THEME);
813 #else
e4431849 814 #define wxIMPLEMENT_WX_THEME_SUPPORT
ee92941a 815 #endif
24e78d27 816#else
e4431849 817 #define wxIMPLEMENT_WX_THEME_SUPPORT
24e78d27 818#endif
c801d85f 819
c661ecca
RR
820// Use this macro if you want to define your own main() or WinMain() function
821// and call wxEntry() from there.
e4431849 822#define wxIMPLEMENT_APP_NO_MAIN(appname) \
458f68d0 823 appname& wxGetApp() { return *static_cast<appname*>(wxApp::GetInstance()); } \
e8e1149b 824 wxAppConsole *wxCreateApp() \
94826170 825 { \
2a7c7605 826 wxAppConsole::CheckBuildOptions(WX_BUILD_OPTIONS_SIGNATURE, \
82c75aea 827 "your program"); \
94826170
VZ
828 return new appname; \
829 } \
830 wxAppInitializer \
458f68d0 831 wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp)
c661ecca 832
e4431849 833// Same as wxIMPLEMENT_APP() normally but doesn't include themes support in
24e78d27 834// wxUniversal builds
e4431849
FM
835#define wxIMPLEMENT_APP_NO_THEMES(appname) \
836 wxIMPLEMENT_WXWIN_MAIN \
837 wxIMPLEMENT_APP_NO_MAIN(appname)
24e78d27
VZ
838
839// Use this macro exactly once, the argument is the name of the wxApp-derived
840// class which is the class of your application.
e4431849
FM
841#define wxIMPLEMENT_APP(appname) \
842 wxIMPLEMENT_WX_THEME_SUPPORT \
843 wxIMPLEMENT_APP_NO_THEMES(appname)
24e78d27 844
80b2db4e 845// Same as IMPLEMENT_APP(), but for console applications.
e4431849
FM
846#define wxIMPLEMENT_APP_CONSOLE(appname) \
847 wxIMPLEMENT_WXWIN_MAIN_CONSOLE \
848 wxIMPLEMENT_APP_NO_MAIN(appname)
80b2db4e 849
24e78d27
VZ
850// this macro can be used multiple times and just allows you to use wxGetApp()
851// function
e4431849
FM
852#define wxDECLARE_APP(appname) \
853 extern appname& wxGetApp()
c801d85f 854
17a1ebd1 855
e4431849 856// declare the stuff defined by wxIMPLEMENT_APP() macro, it's not really needed
17a1ebd1
VZ
857// anywhere else but at the very least it suppresses icc warnings about
858// defining extern symbols without prior declaration, and it shouldn't do any
859// harm
860extern wxAppConsole *wxCreateApp();
861extern wxAppInitializer wxTheAppInitializer;
862
e4431849
FM
863// ----------------------------------------------------------------------------
864// Compatibility macro aliases
865// ----------------------------------------------------------------------------
866
867// deprecated variants _not_ requiring a semicolon after them
868// (note that also some wx-prefixed macro do _not_ require a semicolon because
869// it's not always possible to force the compire to require it)
870
871#define IMPLEMENT_WXWIN_MAIN_CONSOLE wxIMPLEMENT_WXWIN_MAIN_CONSOLE
872#define IMPLEMENT_WXWIN_MAIN wxIMPLEMENT_WXWIN_MAIN
873#define IMPLEMENT_WX_THEME_SUPPORT wxIMPLEMENT_WX_THEME_SUPPORT
874#define IMPLEMENT_APP_NO_MAIN(app) wxIMPLEMENT_APP_NO_MAIN(app);
875#define IMPLEMENT_APP_NO_THEMES(app) wxIMPLEMENT_APP_NO_THEMES(app);
876#define IMPLEMENT_APP(app) wxIMPLEMENT_APP(app);
877#define IMPLEMENT_APP_CONSOLE(app) wxIMPLEMENT_APP_CONSOLE(app);
878#define DECLARE_APP(app) wxDECLARE_APP(app);
879
94826170 880#endif // _WX_APP_H_BASE_