]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/app.h
Add support for wxSTB_ELLIPSIZE_* and for wxSTB_SHOW_TIPS flags under wxMSW
[wxWidgets.git] / interface / wx / app.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: app.h
e54c96f1 3// Purpose: interface of wxApp
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
8064223b 9
23324ae1 10/**
8064223b 11 @class wxAppConsole
7c913512 12
8064223b 13 This class is essential for writing console-only or hybrid apps without
f045c7f5
FM
14 having to define @c wxUSE_GUI=0.
15
16 It is used to:
17 @li set and get application-wide properties (see wxAppConsole::CreateTraits
18 and wxAppConsole::SetXXX functions)
19 @li implement the windowing system message or event loop: events in fact are
20 supported even in console-mode applications (see wxAppConsole::HandleEvent
21 and wxAppConsole::ProcessPendingEvents);
22 @li initiate application processing via wxApp::OnInit;
23 @li allow default processing of events not handled by other
24 objects in the application (see wxAppConsole::FilterEvent)
25 @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
26
27 You should use the macro IMPLEMENT_APP(appClass) in your application
28 implementation file to tell wxWidgets how to create an instance of your
29 application class.
7c913512 30
f045c7f5
FM
31 Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
32 (which returns a reference to your application object) to be visible to other
33 files.
7c913512 34
23324ae1
FM
35 @library{wxbase}
36 @category{appmanagement}
7c913512 37
84094285 38 @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
23324ae1 39*/
8064223b 40class wxAppConsole : public wxEvtHandler
23324ae1 41{
8064223b 42protected:
23324ae1 43 /**
8064223b 44 Creates the wxAppTraits object when GetTraits() needs it for the first time.
23324ae1 45
8064223b 46 @see wxAppTraits
23324ae1 47 */
8064223b 48 virtual wxAppTraits* CreateTraits();
23324ae1 49
8064223b 50public:
3c4f71cc 51
23324ae1 52 /**
8064223b 53 Destructor.
23324ae1 54 */
8064223b 55 virtual ~wxAppConsole();
23324ae1 56
4b221422
FM
57
58 /**
59 @name Event-handling
dde19c21
FM
60
61 Note that you should look at wxEvtLoopBase for more event-processing
62 documentation.
4b221422
FM
63 */
64 //@{
65
23324ae1 66 /**
dde19c21
FM
67 Called by wxWidgets on creation of the application. Override this if you wish
68 to provide your own (environment-dependent) main loop.
8064223b 69
dde19c21 70 @return 0 under X, and the wParam of the WM_QUIT message under Windows.
23324ae1 71 */
dde19c21 72 virtual int MainLoop();
23324ae1
FM
73
74 /**
75 Call this to explicitly exit the main message (event) loop.
76 You should normally exit the main loop (and the application) by deleting
77 the top window.
dde19c21
FM
78
79 This function simply calls wxEvtLoopBase::Exit() on the active loop.
23324ae1
FM
80 */
81 virtual void ExitMainLoop();
82
83 /**
84 This function is called before processing any event and allows the application
96d7cc9b
FM
85 to preempt the processing of some events.
86
87 If this method returns -1 the event is processed normally, otherwise either
88 @true or @false should be returned and the event processing stops immediately
89 considering that the event had been already processed (for the former return
90 value) or that it is not going to be processed at all (for the latter one).
23324ae1 91 */
8064223b 92 virtual int FilterEvent(wxEvent& event);
23324ae1 93
ec38d07d
FM
94 /**
95 Returns the main event loop instance, i.e. the event loop which is started
96 by OnRun() and which dispatches all events sent from the native toolkit
97 to the application (except when new event loops are temporarily set-up).
98 The returned value maybe @NULL. Put initialization code which needs a
99 non-@NULL main event loop into OnEventLoopEnter().
100 */
101 wxEventLoopBase* GetMainLoop() const;
3c4f71cc 102
4b221422
FM
103 /**
104 This function simply invokes the given method @a func of the specified
105 event handler @a handler with the @a event as parameter. It exists solely
106 to allow to catch the C++ exceptions which could be thrown by all event
107 handlers in the application in one place: if you want to do this, override
108 this function in your wxApp-derived class and add try/catch clause(s) to it.
23324ae1 109 */
4b221422
FM
110 virtual void HandleEvent(wxEvtHandler* handler,
111 wxEventFunction func,
112 wxEvent& event) const;
23324ae1 113
4b221422
FM
114 //@}
115
23324ae1 116
8e40ed85
FM
117 /**
118 @name Pending events
119
120 Pending events are handled by wxAppConsole rather than wxEventLoopBase
121 to allow queuing of events even when there's no event loop
122 (e.g. in wxAppConsole::OnInit).
123 */
124 //@{
125
126 /**
127 Process all pending events; it is necessary to call this function to
cae9e7b1 128 process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
8e40ed85 129
cae9e7b1 130 This happens during each event loop iteration (see wxEventLoopBase) in GUI mode but
8e40ed85 131 it may be also called directly.
cae9e7b1
FM
132
133 Note that this function does not only process the pending events for the wxApp object
134 itself (which derives from wxEvtHandler) but also the pending events for @e any
135 event handler of this application.
136
137 This function will immediately return and do nothing if SuspendProcessingOfPendingEvents()
138 was called.
8e40ed85
FM
139 */
140 virtual void ProcessPendingEvents();
cae9e7b1
FM
141
142 /**
143 Deletes the pending events of all wxEvtHandlers of this application.
144
145 See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
146 events.
147 */
148 void DeletePendingEvents();
8e40ed85
FM
149
150 /**
151 Returns @true if there are pending events on the internal pending event list.
cae9e7b1
FM
152
153 Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are
154 called (not only for wxApp itself, but for any event handler of the application!),
155 the internal wxApp's list of handlers with pending events is updated and this
156 function will return true.
8e40ed85
FM
157 */
158 bool HasPendingEvents() const;
159
160 /**
161 Temporary suspends processing of the pending events.
162
163 @see ResumeProcessingOfPendingEvents()
164 */
165 void SuspendProcessingOfPendingEvents();
166
167 /**
168 Resume processing of the pending events previously stopped because of a
169 call to SuspendProcessingOfPendingEvents().
170 */
171 void ResumeProcessingOfPendingEvents();
172
173 //@}
174
175
23324ae1 176 /**
4b221422
FM
177 Allows external code to modify global ::wxTheApp, but you should really
178 know what you're doing if you call it.
179
180 @param app
181 Replacement for the global application object.
182
183 @see GetInstance()
23324ae1 184 */
4b221422 185 static void SetInstance(wxAppConsole* app);
23324ae1
FM
186
187 /**
4b221422 188 Returns the one and only global application object.
d48b06bd 189 Usually ::wxTheApp is used instead.
4b221422
FM
190
191 @see SetInstance()
23324ae1 192 */
4b221422 193 static wxAppConsole* GetInstance();
23324ae1 194
23324ae1
FM
195 /**
196 Returns @true if the main event loop is currently running, i.e. if the
197 application is inside OnRun().
96d7cc9b 198
23324ae1
FM
199 This can be useful to test whether events can be dispatched. For example,
200 if this function returns @false, non-blocking sockets cannot be used because
201 the events from them would never be processed.
202 */
203 static bool IsMainLoopRunning();
204
d181e877 205
f045c7f5 206 /**
4b221422 207 @name Mac-specific functions
f045c7f5 208 */
4b221422 209 //@{
f045c7f5 210
23324ae1 211 /**
d9faa1fe 212 Called in response of an "open-application" Apple event.
23324ae1 213 Override this to create a new document in your app.
d9faa1fe 214
0f6c9085 215 @onlyfor{wxosx}
23324ae1 216 */
8064223b 217 virtual void MacNewFile();
23324ae1
FM
218
219 /**
d9faa1fe 220 Called in response of an "open-document" Apple event.
96d7cc9b
FM
221
222 You need to override this method in order to open a document file after the
223 user double clicked on it or if the document file was dropped on either the
224 running application or the application icon in Finder.
d9faa1fe 225
0f6c9085 226 @onlyfor{wxosx}
23324ae1 227 */
8064223b 228 virtual void MacOpenFile(const wxString& fileName);
23324ae1
FM
229
230 /**
d9faa1fe
FM
231 Called in response of a "get-url" Apple event.
232
0f6c9085 233 @onlyfor{wxosx}
23324ae1 234 */
8064223b 235 virtual void MacOpenURL(const wxString& url);
23324ae1
FM
236
237 /**
d9faa1fe
FM
238 Called in response of a "print-document" Apple event.
239
0f6c9085 240 @onlyfor{wxosx}
23324ae1 241 */
8064223b 242 virtual void MacPrintFile(const wxString& fileName);
23324ae1
FM
243
244 /**
d9faa1fe
FM
245 Called in response of a "reopen-application" Apple event.
246
0f6c9085 247 @onlyfor{wxosx}
23324ae1 248 */
8064223b 249 virtual void MacReopenApp();
23324ae1 250
4b221422 251 //@}
3c4f71cc 252
4b221422
FM
253
254 /**
255 @name Callbacks for application-wide "events"
23324ae1 256 */
4b221422 257 //@{
23324ae1
FM
258
259 /**
260 This function is called when an assert failure occurs, i.e. the condition
e54c96f1 261 specified in wxASSERT() macro evaluated to @false.
96d7cc9b 262
23324ae1
FM
263 It is only called in debug mode (when @c __WXDEBUG__ is defined) as
264 asserts are not left in the release code at all.
23324ae1
FM
265 The base class version shows the default assert failure dialog box proposing to
266 the user to stop the program, continue or ignore all subsequent asserts.
3c4f71cc 267
7c913512 268 @param file
4cc4bfaf 269 the name of the source file where the assert occurred
7c913512 270 @param line
4cc4bfaf 271 the line number in this file where the assert occurred
7c913512 272 @param func
4cc4bfaf
FM
273 the name of the function where the assert occurred, may be
274 empty if the compiler doesn't support C99 __FUNCTION__
7c913512 275 @param cond
4cc4bfaf 276 the condition of the failed assert in text form
7c913512 277 @param msg
96d7cc9b
FM
278 the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will
279 be @NULL if just wxASSERT or wxFAIL was used
23324ae1 280 */
8d483c9b
FM
281 virtual void OnAssertFailure(const wxChar *file,
282 int line,
283 const wxChar *func,
284 const wxChar *cond,
285 const wxChar *msg);
23324ae1
FM
286
287 /**
288 Called when command line parsing fails (i.e. an incorrect command line option
289 was specified by the user). The default behaviour is to show the program usage
290 text and abort the program.
96d7cc9b 291
7c913512 292 Return @true to continue normal execution or @false to return
23324ae1 293 @false from OnInit() thus terminating the program.
3c4f71cc 294
4cc4bfaf 295 @see OnInitCmdLine()
23324ae1 296 */
8064223b 297 virtual bool OnCmdLineError(wxCmdLineParser& parser);
23324ae1
FM
298
299 /**
300 Called when the help option (@c --help) was specified on the command line.
301 The default behaviour is to show the program usage text and abort the program.
96d7cc9b 302
7c913512 303 Return @true to continue normal execution or @false to return
23324ae1 304 @false from OnInit() thus terminating the program.
3c4f71cc 305
4cc4bfaf 306 @see OnInitCmdLine()
23324ae1 307 */
8064223b 308 virtual bool OnCmdLineHelp(wxCmdLineParser& parser);
23324ae1
FM
309
310 /**
311 Called after the command line had been successfully parsed. You may override
312 this method to test for the values of the various parameters which could be
313 set from the command line.
96d7cc9b 314
23324ae1
FM
315 Don't forget to call the base class version unless you want to suppress
316 processing of the standard command line options.
96d7cc9b
FM
317 Return @true to continue normal execution or @false to return @false from
318 OnInit() thus terminating the program.
3c4f71cc 319
4cc4bfaf 320 @see OnInitCmdLine()
23324ae1 321 */
8064223b 322 virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
23324ae1 323
ec38d07d
FM
324 /**
325 Called by wxEventLoopBase::SetActive(): you can override this function
326 and put here the code which needs an active event loop.
327
328 Note that this function is called whenever an event loop is activated;
329 you may want to use wxEventLoopBase::IsMain() to perform initialization
330 specific for the app's main event loop.
4623dc32
FM
331
332 @see OnEventLoopExit()
ec38d07d
FM
333 */
334 virtual void OnEventLoopEnter(wxEventLoopBase* loop);
335
336 /**
337 Called by wxEventLoopBase::OnExit() for each event loop which
338 is exited.
4623dc32
FM
339
340 @see OnEventLoopEnter()
ec38d07d
FM
341 */
342 virtual void OnEventLoopExit(wxEventLoopBase* loop);
343
23324ae1
FM
344 /**
345 This function is called if an unhandled exception occurs inside the main
346 application event loop. It can return @true to ignore the exception and to
347 continue running the loop or @false to exit the loop and terminate the
348 program. In the latter case it can also use C++ @c throw keyword to
349 rethrow the current exception.
96d7cc9b 350
23324ae1
FM
351 The default behaviour of this function is the latter in all ports except under
352 Windows where a dialog is shown to the user which allows him to choose between
353 the different options. You may override this function in your class to do
354 something more appropriate.
96d7cc9b 355
7c913512 356 Finally note that if the exception is rethrown from here, it can be caught in
23324ae1
FM
357 OnUnhandledException().
358 */
359 virtual bool OnExceptionInMainLoop();
360
361 /**
362 Override this member function for any processing which needs to be
363 done as the application is about to exit. OnExit is called after
364 destroying all application windows and controls, but before
7c913512 365 wxWidgets cleanup. Note that it is not called at all if
23324ae1 366 OnInit() failed.
96d7cc9b
FM
367
368 The return value of this function is currently ignored, return the same
369 value as returned by the base class method if you override it.
23324ae1
FM
370 */
371 virtual int OnExit();
372
373 /**
374 This function may be called if something fatal happens: an unhandled
375 exception under Win32 or a a fatal signal under Unix, for example. However,
7c913512 376 this will not happen by default: you have to explicitly call
e54c96f1 377 wxHandleFatalExceptions() to enable this.
96d7cc9b 378
23324ae1
FM
379 Generally speaking, this function should only show a message to the user and
380 return. You may attempt to save unsaved data but this is not guaranteed to
381 work and, in fact, probably won't.
3c4f71cc 382
e54c96f1 383 @see wxHandleFatalExceptions()
23324ae1 384 */
8064223b 385 virtual void OnFatalException();
23324ae1
FM
386
387 /**
388 This must be provided by the application, and will usually create the
96d7cc9b
FM
389 application's main window, optionally calling SetTopWindow().
390
391 You may use OnExit() to clean up anything initialized here, provided
23324ae1 392 that the function returns @true.
96d7cc9b 393
23324ae1
FM
394 Notice that if you want to to use the command line processing provided by
395 wxWidgets you have to call the base class version in the derived class
396 OnInit().
96d7cc9b 397
23324ae1
FM
398 Return @true to continue processing, @false to exit the application
399 immediately.
400 */
8064223b 401 virtual bool OnInit();
23324ae1
FM
402
403 /**
96d7cc9b
FM
404 Called from OnInit() and may be used to initialize the parser with the
405 command line options for this application. The base class versions adds
406 support for a few standard options only.
23324ae1 407 */
8064223b 408 virtual void OnInitCmdLine(wxCmdLineParser& parser);
23324ae1
FM
409
410 /**
411 This virtual function is where the execution of a program written in wxWidgets
412 starts. The default implementation just enters the main loop and starts
96d7cc9b
FM
413 handling the events until it terminates, either because ExitMainLoop() has
414 been explicitly called or because the last frame has been deleted and
415 GetExitOnFrameDelete() flag is @true (this is the default).
416
23324ae1
FM
417 The return value of this function becomes the exit code of the program, so it
418 should return 0 in case of successful termination.
419 */
420 virtual int OnRun();
421
422 /**
7c913512 423 This function is called when an unhandled C++ exception occurs inside
96d7cc9b
FM
424 OnRun() (the exceptions which occur during the program startup and shutdown
425 might not be caught at all). Notice that by now the main event loop has been
426 terminated and the program will exit, if you want to prevent this from happening
427 (i.e. continue running after catching an exception) you need to override
428 OnExceptionInMainLoop().
429
23324ae1
FM
430 The default implementation shows information about the exception in debug build
431 but does nothing in the release build.
432 */
433 virtual void OnUnhandledException();
434
4b221422
FM
435 //@}
436
437
23324ae1 438 /**
4b221422
FM
439 @name Application informations
440 */
441 //@{
3c4f71cc 442
4b221422
FM
443 /**
444 Returns the user-readable application name.
445
446 The difference between this string and the one returned by GetAppName()
447 is that this one is meant to be shown to the user and so should be used
448 for the window titles, page headers and so on while the other one
449 should be only used internally, e.g. for the file names or
450 configuration file keys. By default, returns the application name as
451 returned by GetAppName() capitalized using wxString::Capitalize().
452
453 @since 2.9.0
23324ae1 454 */
4b221422
FM
455 wxString GetAppDisplayName() const;
456
457 /**
458 Returns the application name.
459
460 @remarks wxWidgets sets this to a reasonable default before calling
461 OnInit(), but the application can reset it at will.
462
463 @see GetAppDisplayName()
464 */
465 wxString GetAppName() const;
466
467 /**
468 Gets the class name of the application. The class name may be used in a
469 platform specific manner to refer to the application.
470
471 @see SetClassName()
472 */
473 wxString GetClassName() const;
474
475 /**
476 Returns a pointer to the wxAppTraits object for the application.
477 If you want to customize the wxAppTraits object, you must override the
478 CreateTraits() function.
479 */
480 wxAppTraits* GetTraits();
481
482 /**
483 Returns the user-readable vendor name. The difference between this string
484 and the one returned by GetVendorName() is that this one is meant to be shown
485 to the user and so should be used for the window titles, page headers and so on
486 while the other one should be only used internally, e.g. for the file names or
487 configuration file keys.
488
489 By default, returns the same string as GetVendorName().
490
491 @since 2.9.0
492 */
493 const wxString& GetVendorDisplayName() const;
494
495 /**
496 Returns the application's vendor name.
497 */
498 const wxString& GetVendorName() const;
23324ae1 499
8064223b 500 /**
328fafa1
VZ
501 Set the application name to be used in the user-visible places such as
502 window titles.
503
504 See GetAppDisplayName() for more about the differences between the
8064223b 505 display name and name.
328fafa1
VZ
506
507 Notice that if this function is called, the name is used as is, without
508 any capitalization as done by default by GetAppDisplayName().
8064223b
FM
509 */
510 void SetAppDisplayName(const wxString& name);
511
512 /**
513 Sets the name of the application. This name should be used for file names,
514 configuration file entries and other internal strings. For the user-visible
515 strings, such as the window titles, the application display name set by
516 SetAppDisplayName() is used instead.
517
518 By default the application name is set to the name of its executable file.
519
520 @see GetAppName()
521 */
522 void SetAppName(const wxString& name);
523
524 /**
525 Sets the class name of the application. This may be used in a platform specific
526 manner to refer to the application.
527
528 @see GetClassName()
529 */
530 void SetClassName(const wxString& name);
531
8064223b
FM
532 /**
533 Set the vendor name to be used in the user-visible places.
534 See GetVendorDisplayName() for more about the differences between the
535 display name and name.
536 */
537 void SetVendorDisplayName(const wxString& name);
538
539 /**
540 Sets the name of application's vendor. The name will be used
541 in registry access. A default name is set by wxWidgets.
542
543 @see GetVendorName()
544 */
545 void SetVendorName(const wxString& name);
546
4b221422 547 //@}
8064223b 548
8064223b
FM
549
550 /**
551 Number of command line arguments (after environment-specific processing).
552 */
553 int argc;
554
555 /**
556 Command line arguments (after environment-specific processing).
557
558 Under Windows and Linux/Unix, you should parse the command line
559 arguments and check for files to be opened when starting your
560 application. Under OS X, you need to override MacOpenFile()
561 since command line arguments are used differently there.
562
563 You may use the wxCmdLineParser to parse command line arguments.
564 */
565 wxChar** argv;
566};
567
568
569
570
571/**
572 @class wxApp
8064223b 573
f045c7f5 574 The wxApp class represents the application itself when @c wxUSE_GUI=1.
8064223b 575
f045c7f5
FM
576 In addition to the features provided by wxAppConsole it keeps track of
577 the <em>top window</em> (see SetTopWindow()) and adds support for
578 video modes (see SetVideoMode()).
8064223b 579
f045c7f5 580 In general, application-wide settings for GUI-only apps are accessible
84094285 581 from wxApp (or from wxSystemSettings or wxSystemOptions classes).
8064223b 582
3051a44a
FM
583 @beginEventEmissionTable
584 @event{EVT_QUERY_END_SESSION(func)}
585 Process a query end session event, supplying the member function.
586 See wxCloseEvent.
587 @event{EVT_END_SESSION(func)}
588 Process an end session event, supplying the member function.
589 See wxCloseEvent.
590 @event{EVT_ACTIVATE_APP(func)}
591 Process a @c wxEVT_ACTIVATE_APP event. See wxActivateEvent.
592 @event{EVT_HIBERNATE(func)}
593 Process a hibernate event. See wxActivateEvent.
594 @event{EVT_DIALUP_CONNECTED(func)}
595 A connection with the network was established. See wxDialUpEvent.
596 @event{EVT_DIALUP_DISCONNECTED(func)}
597 The connection with the network was lost. See wxDialUpEvent.
598 @event{EVT_IDLE(func)}
599 Process a @c wxEVT_IDLE event. See wxIdleEvent.
600 @endEventTable
601
8064223b
FM
602 @library{wxbase}
603 @category{appmanagement}
604
84094285 605 @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings
8064223b
FM
606*/
607class wxApp : public wxAppConsole
608{
609public:
610 /**
611 Constructor. Called implicitly with a definition of a wxApp object.
612 */
613 wxApp();
614
615 /**
616 Destructor. Will be called implicitly on program exit if the wxApp
617 object is created on the stack.
618 */
619 virtual ~wxApp();
620
f045c7f5
FM
621 /**
622 Get display mode that is used use. This is only used in framebuffer
1f2f7329 623 wxWidgets ports (such as wxMGL or wxDFB).
f045c7f5
FM
624 */
625 virtual wxVideoMode GetDisplayMode() const;
626
8064223b
FM
627 /**
628 Returns @true if the application will exit when the top-level frame is deleted.
629
630 @see SetExitOnFrameDelete()
631 */
632 bool GetExitOnFrameDelete() const;
633
f045c7f5
FM
634 /**
635 Return the layout direction for the current locale or @c wxLayout_Default
636 if it's unknown.
637 */
638 virtual wxLayoutDirection GetLayoutDirection() const;
639
8064223b
FM
640 /**
641 Returns @true if the application will use the best visual on systems that support
642 different visuals, @false otherwise.
643
644 @see SetUseBestVisual()
645 */
646 bool GetUseBestVisual() const;
647
648 /**
649 Returns a pointer to the top window.
650
afc31d8a
FM
651 @remarks
652 If the top window hasn't been set using SetTopWindow(), this function
653 will find the first top-level window (frame or dialog or instance of
654 wxTopLevelWindow) from the internal top level window list and return that.
8064223b
FM
655
656 @see SetTopWindow()
657 */
658 virtual wxWindow* GetTopWindow() const;
659
660 /**
661 Returns @true if the application is active, i.e. if one of its windows is
662 currently in the foreground.
663
664 If this function returns @false and you need to attract users attention to
665 the application, you may use wxTopLevelWindow::RequestUserAttention to do it.
666 */
8d483c9b 667 virtual bool IsActive() const;
8064223b 668
d48b06bd
FM
669 /**
670 This function is similar to wxYield(), except that it disables the user
671 input to all program windows before calling wxAppConsole::Yield and re-enables it
672 again afterwards. If @a win is not @NULL, this window will remain enabled,
673 allowing the implementation of some limited user interaction.
674 Returns the result of the call to wxAppConsole::Yield.
675
676 @see wxSafeYield
677 */
678 virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
679
680 /**
681 Works like SafeYield() with @e onlyIfNeeded == @true except that
682 it allows the caller to specify a mask of events to be processed.
683
684 See wxAppConsole::YieldFor for more info.
685 */
686 virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
687
23324ae1 688 /**
96d7cc9b
FM
689 Windows-only function for processing a message. This function is called
690 from the main message loop, checking for windows that may wish to process it.
691
692 The function returns @true if the message was processed, @false otherwise.
693 If you use wxWidgets with another class library with its own message loop,
694 you should make sure that this function is called to allow wxWidgets to
3c4f71cc 695 receive messages. For example, to allow co-existence with the Microsoft
96d7cc9b 696 Foundation Classes, override the PreTranslateMessage function:
3c4f71cc 697
96d7cc9b
FM
698 @code
699 // Provide wxWidgets message loop compatibility
700 BOOL CTheApp::PreTranslateMessage(MSG *msg)
701 {
702 if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
703 return true;
704 else
705 return CWinApp::PreTranslateMessage(msg);
706 }
707 @endcode
d9faa1fe
FM
708
709 @onlyfor{wxmsw}
23324ae1 710 */
4cc4bfaf 711 bool ProcessMessage(WXMSG* msg);
23324ae1
FM
712
713 /**
714 Sends idle events to a window and its children.
23324ae1
FM
715 Please note that this function is internal to wxWidgets and shouldn't be used
716 by user code.
3c4f71cc 717
23324ae1 718 @remarks These functions poll the top-level windows, and their children,
96d7cc9b
FM
719 for idle event processing. If @true is returned, more OnIdle
720 processing is requested by one or more window.
3c4f71cc 721
4cc4bfaf 722 @see wxIdleEvent
23324ae1 723 */
8d483c9b 724 virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
23324ae1 725
f045c7f5 726 /**
1f2f7329
FM
727 Set display mode to use. This is only used in framebuffer wxWidgets
728 ports (such as wxMGL or wxDFB).
f045c7f5
FM
729 */
730 virtual bool SetDisplayMode(const wxVideoMode& info);
731
23324ae1
FM
732 /**
733 Allows the programmer to specify whether the application will exit when the
734 top-level frame is deleted.
3c4f71cc 735
7c913512 736 @param flag
96d7cc9b
FM
737 If @true (the default), the application will exit when the top-level frame
738 is deleted. If @false, the application will continue to run.
3c4f71cc 739
96d7cc9b 740 @see GetExitOnFrameDelete(), @ref overview_app_shutdown
23324ae1
FM
741 */
742 void SetExitOnFrameDelete(bool flag);
743
23324ae1 744 /**
96d7cc9b
FM
745 Allows runtime switching of the UI environment theme.
746
747 Currently implemented for wxGTK2-only.
23324ae1 748 Return @true if theme was successfully changed.
3c4f71cc 749
7c913512 750 @param theme
4cc4bfaf 751 The name of the new theme or an absolute path to a gtkrc-theme-file
23324ae1 752 */
8064223b 753 virtual bool SetNativeTheme(const wxString& theme);
23324ae1
FM
754
755 /**
96d7cc9b
FM
756 Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
757 know which is the main window. You don't have to set the top window;
23324ae1 758 it is only a convenience so that (for example) certain dialogs without parents
afc31d8a
FM
759 can use a specific window as the top window.
760
761 If no top window is specified by the application, wxWidgets just uses the
762 first frame or dialog (or better, any wxTopLevelWindow) in its top-level
763 window list, when it needs to use the top window.
764 If you previously called SetTopWindow() and now you need to restore this
765 automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.
3c4f71cc 766
7c913512 767 @param window
4cc4bfaf 768 The new top window.
3c4f71cc 769
4cc4bfaf 770 @see GetTopWindow(), OnInit()
23324ae1
FM
771 */
772 void SetTopWindow(wxWindow* window);
773
774 /**
775 Allows the programmer to specify whether the application will use the best
96d7cc9b
FM
776 visual on systems that support several visual on the same display. This is typically
777 the case under Solaris and IRIX, where the default visual is only 8-bit whereas
778 certain applications are supposed to run in TrueColour mode.
779
780 Note that this function has to be called in the constructor of the wxApp
23324ae1 781 instance and won't have any effect when called later on.
23324ae1 782 This function currently only has effect under GTK.
3c4f71cc 783
7c913512 784 @param flag
4cc4bfaf 785 If @true, the app will use the best visual.
96d7cc9b
FM
786 @param forceTrueColour
787 If @true then the application will try to force using a TrueColour
788 visual and abort the app if none is found.
23324ae1 789 */
4cc4bfaf 790 void SetUseBestVisual(bool flag, bool forceTrueColour = false);
23324ae1
FM
791};
792
793
e54c96f1 794
23324ae1
FM
795// ============================================================================
796// Global functions/macros
797// ============================================================================
798
23324ae1 799
b21126db 800/** @addtogroup group_funcmacro_rtti */
8af7f7c1 801//@{
23324ae1
FM
802
803/**
f045c7f5 804 This is used in headers to create a forward declaration of the ::wxGetApp()
8af7f7c1 805 function implemented by IMPLEMENT_APP().
96d7cc9b 806
eea9220d 807 It creates the declaration <tt>className& wxGetApp()</tt>.
8af7f7c1
BP
808
809 @header{wx/app.h}
810
23324ae1 811 Example:
4cc4bfaf 812
23324ae1 813 @code
8af7f7c1 814 DECLARE_APP(MyApp)
23324ae1
FM
815 @endcode
816*/
7baebf86 817#define DECLARE_APP( className )
23324ae1
FM
818
819/**
96d7cc9b
FM
820 This is used in the application class implementation file to make the
821 application class known to wxWidgets for dynamic construction.
8af7f7c1
BP
822
823 @header{wx/app.h}
824
96d7cc9b
FM
825 Example:
826
827 @code
828 IMPLEMENT_APP(MyApp)
829 @endcode
830
8af7f7c1
BP
831 @see DECLARE_APP().
832*/
7baebf86 833#define IMPLEMENT_APP( className )
8af7f7c1
BP
834
835//@}
836
837
838
8cd06fb5
BP
839/**
840 The global pointer to the singleton wxApp object.
841
842 @see wxApp::GetInstance()
843*/
844wxApp *wxTheApp;
845
846
847
b21126db 848/** @addtogroup group_funcmacro_appinitterm */
39fb8056 849//@{
23324ae1 850
23324ae1 851/**
8cd06fb5
BP
852 This function doesn't exist in wxWidgets but it is created by using the
853 IMPLEMENT_APP() macro.
96d7cc9b 854
39fb8056
FM
855 Thus, before using it anywhere but in the same module where this macro is
856 used, you must make it available using DECLARE_APP().
96d7cc9b
FM
857
858 The advantage of using this function compared to directly using the global
8cd06fb5
BP
859 ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
860 allow you to access the functions specific to your application class but
861 not present in wxApp while wxGetApp() returns the object of the right type.
027c1c27
BP
862
863 @header{wx/app.h}
23324ae1 864*/
8cd06fb5 865wxAppDerivedClass& wxGetApp();
23324ae1 866
23324ae1 867/**
4cc4bfaf 868 If @a doIt is @true, the fatal exceptions (also known as general protection
23324ae1
FM
869 faults under Windows or segmentation violations in the Unix world) will be
870 caught and passed to wxApp::OnFatalException.
96d7cc9b 871
8cd06fb5
BP
872 By default, i.e. before this function is called, they will be handled in
873 the normal way which usually just means that the application will be
874 terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false
875 will restore this default behaviour.
4cc4bfaf 876
8cd06fb5
BP
877 Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION
878 is 1 and under Windows platform this requires a compiler with support for
879 SEH (structured exception handling) which currently means only Microsoft
880 Visual C++ or a recent Borland C++ version.
027c1c27
BP
881
882 @header{wx/app.h}
23324ae1 883*/
96d7cc9b 884bool wxHandleFatalExceptions(bool doIt = true);
23324ae1 885
23324ae1
FM
886/**
887 This function is used in wxBase only and only if you don't create
888 wxApp object at all. In this case you must call it from your
889 @c main() function before calling any other wxWidgets functions.
96d7cc9b 890
23324ae1 891 If the function returns @false the initialization could not be performed,
96d7cc9b
FM
892 in this case the library cannot be used and wxUninitialize() shouldn't be
893 called neither.
894
895 This function may be called several times but wxUninitialize() must be
896 called for each successful call to this function.
027c1c27
BP
897
898 @header{wx/app.h}
23324ae1
FM
899*/
900bool wxInitialize();
901
902/**
96d7cc9b
FM
903 This function is for use in console (wxBase) programs only. It must be called
904 once for each previous successful call to wxInitialize().
027c1c27
BP
905
906 @header{wx/app.h}
23324ae1 907*/
96d7cc9b 908void wxUninitialize();
23324ae1 909
8cd06fb5
BP
910/**
911 This function wakes up the (internal and platform dependent) idle system,
912 i.e. it will force the system to send an idle event even if the system
913 currently @e is idle and thus would not send any idle event until after
914 some other event would get sent. This is also useful for sending events
915 between two threads and is used by the corresponding functions
916 wxPostEvent() and wxEvtHandler::AddPendingEvent().
027c1c27
BP
917
918 @header{wx/app.h}
8cd06fb5
BP
919*/
920void wxWakeUpIdle();
921
23324ae1 922/**
d48b06bd 923 Calls wxAppConsole::Yield.
96d7cc9b
FM
924
925 @deprecated
23324ae1 926 This function is kept only for backwards compatibility. Please use
d48b06bd 927 the wxAppConsole::Yield method instead in any new code.
027c1c27
BP
928
929 @header{wx/app.h}
23324ae1
FM
930*/
931bool wxYield();
932
39fb8056 933/**
d48b06bd 934 Calls wxApp::SafeYield.
027c1c27
BP
935
936 @header{wx/app.h}
39fb8056
FM
937*/
938bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
23324ae1 939
23324ae1 940/**
39fb8056
FM
941 This function initializes wxWidgets in a platform-dependent way. Use this if you
942 are not using the default wxWidgets entry code (e.g. main or WinMain).
7c913512 943
39fb8056
FM
944 For example, you can initialize wxWidgets from an Microsoft Foundation Classes
945 (MFC) application using this function.
946
947 @note This overload of wxEntry is available under all platforms.
948
949 @see wxEntryStart()
027c1c27
BP
950
951 @header{wx/app.h}
39fb8056
FM
952*/
953int wxEntry(int& argc, wxChar** argv);
954
955/**
956 See wxEntry(int&,wxChar**) for more info about this function.
957
958 Notice that under Windows CE platform, and only there, the type of @a pCmdLine
959 is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
7c913512 960
23324ae1 961 @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
96d7cc9b
FM
962 function wxApp::CleanUp. For example, if exiting from an MFC application
963 that also uses wxWidgets:
964 @code
965 int CTheApp::ExitInstance()
966 {
967 // OnExit isn't called by CleanUp so must be called explicitly.
968 wxTheApp->OnExit();
969 wxApp::CleanUp();
3c4f71cc 970
96d7cc9b
FM
971 return CWinApp::ExitInstance();
972 }
973 @endcode
7c913512 974
027c1c27 975 @header{wx/app.h}
23324ae1 976*/
7c913512 977int wxEntry(HINSTANCE hInstance,
4cc4bfaf
FM
978 HINSTANCE hPrevInstance = NULL,
979 char* pCmdLine = NULL,
7c913512 980 int nCmdShow = SW_SHOWNORMAL);
39fb8056
FM
981
982//@}
983
984
985
b21126db 986/** @addtogroup group_funcmacro_procctrl */
39fb8056
FM
987//@{
988
989/**
990 Exits application after calling wxApp::OnExit.
991
992 Should only be used in an emergency: normally the top-level frame
993 should be deleted (after deleting all other frames) to terminate the
994 application. See wxCloseEvent and wxApp.
027c1c27
BP
995
996 @header{wx/app.h}
39fb8056
FM
997*/
998void wxExit();
999
23324ae1
FM
1000//@}
1001